WordPress.org

Languages: English • 日本語 (Add your language)

Description

Output an unordered list of checkbox <input> elements labeled with category names. This is essentially a convenience function for simplifying calls to wp_terms_checklist()

Usage

<?php
   wp_category_checklist( $post_id, $descendants_and_self, $selected_cats,
         $popular_cats, $walker, $checked_ontop);
?>

Parameters

While strictly speaking all parameters are optional because there are defaults, this function is not so useful without specifying either a $post_id or an array of $selected_cats. But don't try to do both.

$post_id

(integer) (optional) Mark categories associated with this post as checked. $selected_cats must be false, and not an array, if a nonzero value is passed here.

Default: 0

$descendants_and_self

(integer) (optional) ID of the category to output along with its descendents.

Default: 0

$selected_cats

(boolean|array) (optional) An array of category IDs to mark as checked. If passing a valid $post_id, this should be set as false.

Default: false

$popular_cats

(boolean|array) (optional) An array of category IDs that overrides the list of categories receiving the "popular-category" class.

Default: false

$walker

(object) (optional) Walker object to use to build the output. If empty, an instance of Walker_Category_Checklist will be used.

Default: null

$checked_ontop

(boolean) (optional) Move checked items out of the hierarchy and to the top of the list.

Default: true

Examples

Output a list of all categories:

wp_category_checklist();

Output a the list of a certain category and its descendants:

$category_id = 22;

wp_category_checklist( 0, $category_id );

Mark all categories for a particular post as checked:

$post_id = 45;

wp_category_checklist( $post_id );

Specify an array of categories to preselect instead:

$selected_cats = array( 45, 33, 118 );

wp_category_checklist( 0, 0, $selected_cats );

To override which categories will be marked as popular:

$popular = array( 45, 33, 118 );

wp_category_checklist( 0, 0, false, $popular );

Specify a walker object to use:

$walker = new My_Walker_Category_Checklist;

wp_category_checklist( 0, 0, false, false, $walker );

List the checked categories before the rest:

$selected_cats = array( 45, 33, 118 );
$checked_ontop = true;

wp_category_checklist( 0, 0, $selected_cats, false, null, $checked_ontop );

You may also use any of the parameters in combination, except for $post_id and $selected_cats, which should not be used together.

Changelog

Since 2.5.1

Source File

wp_category_checklist() is located in wp-admin/includes/template.php.

Related

• Article: Categories
• Function: the_category()
• Function: the_category_rss()
• Function: single_cat_title()
• Function: category_description()
• Function: wp_dropdown_categories()
• Function: wp_list_categories()
• Function: get_the_category()
• Function: get_the_category_by_ID()
• Function: get_category_by_slug()
• Function: get_the_category_list()
• Function: get_category_parents()
• Function: get_category_link()
• Function: is_category()
• Function: in_category()
• wp_terms_checklist()
• get_categories()

List & Dropdown Functions

• Function: wp_list_authors()
• Function: wp_list_categories()
• Function: wp_list_pages()
• Function: wp_list_bookmarks()
• Function: wp_list_comments()
• Function: wp_get_archives()
• Function: wp_page_menu()
• Function: wp_dropdown_pages()
• Function: wp_dropdown_categories()
• Function: wp_dropdown_users()
• Function: wp_dropdown_roles()
• Function: wp_dropdown_languages()