Summery Summery
Output an unordered list of checkbox input elements labelled with term names.
Syntax Syntax
Description Description
Taxonomy-independent version of wp_category_checklist().
Parameters Parameters
- $post_id
-
(Optional) Post ID. Default 0.
- $args
-
(Optional) 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 is a Walker_Category_Checklist instance. - '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 value: array()
- 'descendants_and_self'
Return Return
(string) HTML list of input elements.
Source Source
File: wp-admin/includes/template.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 ); $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; }
Advertisement
Changelog Changelog
Version | Description |
---|---|
4.4.0 | Introduced the $echo argument. |
3.0.0 | Introduced. |