wp_terms_checklist( int $post_id, array|string $args = array() ): string
Outputs an unordered list of checkbox input elements labelled with term names.
Contents
Description
Taxonomy-independent version of wp_category_checklist() .
Parameters
-
$post_id
int Optional -
Post ID. Default 0.
-
$args
array|string Optional -
Array or string of arguments for generating a terms checklist.
descendants_and_self
intID 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
WalkerWalker object to use to build the output. Default empty which results in a Walker_Category_Checklist instance being used.taxonomy
stringTaxonomy to generate the checklist for. Default'category'
.checked_ontop
boolWhether to move checked items out of the hierarchy and to the top of the list. Default true.echo
boolWhether 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
File: wp-admin/includes/template.php
.
View all references
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;
}
Hooks
-
apply_filters( 'wp_terms_checklist_args',
array|string $args ,int $post_id ) -
Filters the taxonomy terms checklist arguments.
Changelog
Version | Description |
---|---|
4.4.0 | Introduced the $echo argument. |
3.0.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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.