wp_terms_checklist() – Function | Developer.WordPress.org

Outputs an unordered list of checkbox input elements labelled with term names.

Description

Taxonomy-independent version of wp_category_checklist() .

Parameters

$post_idintoptional

Post ID. Default 0.

$argsarray|stringoptional

Array or string of arguments for generating a terms checklist.

descendants_and_self int
ID of the category to output along with its descendants.
Default 0.
selected_cats int[]
Array of category IDs to mark as checked. Default false.
popular_cats int[]
Array of category IDs to receive the "popular-category" class.
Default false.
walker Walker
Walker object to use to build the output. Default empty which results in a Walker_Category_Checklist instance being used.
taxonomy string
Taxonomy to generate the checklist for. Default 'category'.
checked_ontop bool
Whether to move checked items out of the hierarchy and to the top of the list. Default true.
echo bool
Whether to echo the generated markup. False to return the markup instead of echoing it. Default true.

Default:array()

Return

string HTML list of input elements.

Source

function wp_terms_checklist( $post_id = 0, $args = array() ) {	$defaults = array(	'descendants_and_self' => 0,	'selected_cats' => false,	'popular_cats' => false,	'walker' => null,	'taxonomy' => 'category',	'checked_ontop' => true,	'echo' => true,	);	/** * Filters the taxonomy terms checklist arguments. * * @since 3.4.0 * * @see wp_terms_checklist() * * @param array|string $args An array or string of arguments. * @param int $post_id The post ID. */	$params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );	$parsed_args = wp_parse_args( $params, $defaults );	if ( empty( $parsed_args['walker'] ) || ! ( $parsed_args['walker'] instanceof Walker ) ) {	$walker = new Walker_Category_Checklist();	} else {	$walker = $parsed_args['walker'];	}	$taxonomy = $parsed_args['taxonomy'];	$descendants_and_self = (int) $parsed_args['descendants_and_self'];	$args = array( 'taxonomy' => $taxonomy );	$tax = get_taxonomy( $taxonomy );	$args['disabled'] = ! current_user_can( $tax->cap->assign_terms );	$args['list_only'] = ! empty( $parsed_args['list_only'] );	if ( is_array( $parsed_args['selected_cats'] ) ) {	$args['selected_cats'] = array_map( 'intval', $parsed_args['selected_cats'] );	} elseif ( $post_id ) {	$args['selected_cats'] = wp_get_object_terms( $post_id, $taxonomy, array_merge( $args, array( 'fields' => 'ids' ) ) );	} else {	$args['selected_cats'] = array();	}	if ( is_array( $parsed_args['popular_cats'] ) ) {	$args['popular_cats'] = array_map( 'intval', $parsed_args['popular_cats'] );	} else {	$args['popular_cats'] = get_terms(	array(	'taxonomy' => $taxonomy,	'fields' => 'ids',	'orderby' => 'count',	'order' => 'DESC',	'number' => 10,	'hierarchical' => false,	)	);	}	if ( $descendants_and_self ) {	$categories = (array) get_terms(	array(	'taxonomy' => $taxonomy,	'child_of' => $descendants_and_self,	'hierarchical' => 0,	'hide_empty' => 0,	)	);	$self = get_term( $descendants_and_self, $taxonomy );	array_unshift( $categories, $self );	} else {	$categories = (array) get_terms(	array(	'taxonomy' => $taxonomy,	'get' => 'all',	)	);	}	$output = '';	if ( $parsed_args['checked_ontop'] ) {	/* * Post-process $categories rather than adding an exclude to the get_terms() query * to keep the query the same across all posts (for any query cache). */	$checked_categories = array();	$keys = array_keys( $categories );	foreach ( $keys as $k ) {	if ( in_array( $categories[ $k ]->term_id, $args['selected_cats'], true ) ) {	$checked_categories[] = $categories[ $k ];	unset( $categories[ $k ] );	}	}	// Put checked categories on top.	$output .= $walker->walk( $checked_categories, 0, $args );	}	// Then the rest of them.	$output .= $walker->walk( $categories, 0, $args );	if ( $parsed_args['echo'] ) {	echo $output;	}	return $output; }

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_terms_checklist_args’, array|string $args, int $post_id ): Filters the taxonomy terms checklist arguments.

Uses	Description
Walker::walk()`wp-includes/class-wp-walker.php`	Displays array of elements hierarchically.
wp_get_object_terms()`wp-includes/taxonomy.php`	Retrieves the terms associated with the given object(s), in the supplied taxonomies.
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
current_user_can()`wp-includes/capabilities.php`	Returns whether the current user has the specified capability.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
get_taxonomy()`wp-includes/taxonomy.php`	Retrieves the taxonomy object of $taxonomy.
get_term()`wp-includes/taxonomy.php`	Gets all term data from database by term ID.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 5 more Show less

Used by	Description
wp_category_checklist()`wp-admin/includes/template.php`	Outputs an unordered list of checkbox input elements labeled with category names.
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
post_categories_meta_box()`wp-admin/includes/meta-boxes.php`	Displays post categories form fields.
WP_Posts_List_Table::inline_edit()`wp-admin/includes/class-wp-posts-list-table.php`	Outputs the hidden row displayed when inline editing

Changelog

Version	Description
4.4.0	Introduced the `$echo` argument.
3.0.0	Introduced.

User Contributed Notes

Skip to note 2 content

Mikko Saari 4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

Note that if the current user is not allowed to assign terms, the checkboxes in the form are disabled. This function is meant for admin-facing lists. Also, this function is not always defined. You can use

include ABSPATH . 'wp-admin/includes/template.php';

to make sure the function is defined.

Log in to add feedback

wp_terms_checklist( int $post_id, array|string $args = array() ): string

In this article