WordPress at a glance

wp_terms_checklist() WP 3.0.0

Displays/retrieve the UL list of checkbox input elements input type="checkbox" labelled with term names.

Taxonomy-independent version of wp_category_checklist().

To work on the front-end, you need to connect the file:

require_once ABSPATH .'/wp-admin/includes/template.php';
✈ 1 time = 0.000455s = fast | 50000 times = 10.85s = slow
Hooks from the function
Return

null/string. If echo argument is set to true, displays HTML code, otherwise returns the HTML.

Usage pattern

wp_terms_checklist( $post_id, [
	'descendants_and_self' => 0,
	'selected_cats'        => false,
	'popular_cats'         => false,
	//'walker'               => null,
	'taxonomy'             => 'category',
	'checked_ontop'        => true,
	'echo'                 => true,
] );

Usage

wp_terms_checklist( $post_id, $args );
$post_id(int)
Post ID.
Default: 0
$args(array/string)

Array or string of arguments for generating a terms checklist.

  • $descendants_and_self (int)
    ID of the category to output along with its descendants.

  • $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 (object)
    Walker object to use to build the output.
    Default: Walker_Category_Checklist instance

  • $taxonomy (string)
    Taxonomy to generate the checklist for.
    Default: 'category'

  • $checked_ontop (true/false)
    Whether to move checked items out of the hierarchy and to the top of the list.
    Default: true

  • $echo (true/false)
    Whether to echo the generated markup. False to return the markup instead of echoing it.
    Default: true

Default: empty array

Examples

#1 Get the checklist of taxonomy elements

Let's say we have taxonomy wpfunc and we need to list the checkboxes of element 51 and all its children elements. Also, specify dedicated and popular items.

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

$args = [
	'descendants_and_self' => 51,
	'selected_cats'        => array(219, 52),
	'popular_cats'         => array(219, 52),
	'taxonomy'             => 'wpfunc',
	'checked_ontop'        => true
];

echo '<ul>';
wp_terms_checklist( 0, $args );
echo '</ul>';

Displays:

<ul>
	<li id='wpfunc-52' class="popular-category">
		<label class="selectit"><input value="52" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-52" checked='checked' /> Comments</label>
	</li>

	<li id='wpfunc-219' class="popular-category">
		<label class="selectit"><input value="219" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-219" checked='checked' /> Comment pagination</label>
	</li>

	<li id='wpfunc-51'>
		<label class="selectit"><input value="51" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-51" /> Comments, Pings...</label>
		<ul class='children'>
			<li id='wpfunc-218'>
				<label class="selectit"><input value="218" type="checkbox" name="tax_input[wpfunc][]" id="in-wpfunc-218" /> Comments Loop</label>
			</li>
		</ul>
	</li>
</ul>

Changelog

Since 3.0.0 Introduced.
Since 4.4.0 Introduced the $echo argument.

Code of wp terms checklist: wp-admin/includes/template.php WP 5.2.2

<?php
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 $args    An array of arguments.
	 * @param int   $post_id The post ID.
	 */
	$params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );

	$r = wp_parse_args( $params, $defaults );

	if ( empty( $r['walker'] ) || ! ( $r['walker'] instanceof Walker ) ) {
		$walker = new Walker_Category_Checklist;
	} else {
		$walker = $r['walker'];
	}

	$taxonomy             = $r['taxonomy'];
	$descendants_and_self = (int) $r['descendants_and_self'];

	$args = array( 'taxonomy' => $taxonomy );

	$tax              = get_taxonomy( $taxonomy );
	$args['disabled'] = ! current_user_can( $tax->cap->assign_terms );

	$args['list_only'] = ! empty( $r['list_only'] );

	if ( is_array( $r['selected_cats'] ) ) {
		$args['selected_cats'] = $r['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( $r['popular_cats'] ) ) {
		$args['popular_cats'] = $r['popular_cats'];
	} else {
		$args['popular_cats'] = get_terms(
			$taxonomy,
			array(
				'fields'       => 'ids',
				'orderby'      => 'count',
				'order'        => 'DESC',
				'number'       => 10,
				'hierarchical' => false,
			)
		);
	}
	if ( $descendants_and_self ) {
		$categories = (array) get_terms(
			$taxonomy,
			array(
				'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( $taxonomy, array( 'get' => 'all' ) );
	}

	$output = '';

	if ( $r['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'] ) ) {
				$checked_categories[] = $categories[ $k ];
				unset( $categories[ $k ] );
			}
		}

		// Put checked cats on top
		$output .= call_user_func_array( array( $walker, 'walk' ), array( $checked_categories, 0, $args ) );
	}
	// Then the rest of them
	$output .= call_user_func_array( array( $walker, 'walk' ), array( $categories, 0, $args ) );

	if ( $r['echo'] ) {
		echo $output;
	}

	return $output;
}

Related Functions

From tag: List (wp_list)

More from category: Taxonomies (Categories, Tags)

vladlu 100vlad.lu
Editors: kama 100
No comments
    Hello, !     Log In . Register