wp_terms_checklist

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

Description

wp_terms_checklist( (int) $post_id = 0, (array) $args = array() ); 

Taxonomy-independent version of wp_category_checklist().

Parameters (2)

0. $post_id — Optional. (int)
Post ID. Default 0.
1. $args — Optional. (array) => array()
Array or string of arguments for generating a terms checklist. Default empty array.

Options

  • descendants_and_self (int) => 0

    ID of the category to output along with its descendants.

  • selected_cats (array) => false

    List of categories to mark as checked.

  • popular_cats (array) => false

    List of categories to receive the popular-category class.

  • walker (object) => is a Walker_Category_Checklist instance

    Walker object to use to build the output.

  • taxonomy (string) => 'category'

    Taxonomy to generate the checklist for.

  • checked_ontop (bool) => true

    Whether to move checked items out of the hierarchy and to the top of the list.

array(

    /**
     * ID of the category to output along with its descendants.
     *
     * @type int
     */
    'descendants_and_self' => 0,

    /**
     * List of categories to mark as checked.
     *
     * @type array
     * @default false
     */
    'selected_cats' => false,

    /**
     * List of categories to receive the "popular-category" class.
     *
     * @type array
     * @default false
     */
    'popular_cats' => false,

    /**
     * Walker object to use to build the output.
     *
     * @type object
     * @default is a Walker_Category_Checklist instance
     */
    'walker' => is a Walker_Category_Checklist instance,

    /**
     * Taxonomy to generate the checklist for.
     *
     * @type string
     * @default 'category'
     */
    'taxonomy' => 'category',

    /**
     * Whether to move checked items out of the hierarchy and to the top of the list.
     *
     * @type bool
     * @default true
     */
    'checked_ontop' => true
);        


Usage

  1. if ( !function_exists( 'wp_terms_checklist' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/template.php'; 
  3.  
  4. // Optional. Post ID. Default 0. 
  5. $post_id = -1; 
  6.  
  7. // Optional. Array or string of arguments for generating a terms checklist. Default empty array. 
  8. $args = array( 
  9. 'descendants_and_self' => 0, 
  10. 'selected_cats' => false, 
  11. 'popular_cats' => false, 
  12. 'walker' => is a Walker_Category_Checklist instance, 
  13. 'taxonomy' => 'category', 
  14. 'checked_ontop' => true 
  15. ); 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = wp_terms_checklist($post_id, $args); 
  19.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/template.php  
  1. function wp_terms_checklist( $post_id = 0, $args = array() ) { 
  2. $defaults = array( 
  3. 'descendants_and_self' => 0,  
  4. 'selected_cats' => false,  
  5. 'popular_cats' => false,  
  6. walker => null,  
  7. 'taxonomy' => 'category',  
  8. 'checked_ontop' => true,  
  9. 'echo' => true,  
  10. ); 
  11.  
  12. /** 
  13. * Filters the taxonomy terms checklist arguments. 
  14. * @since 3.4.0 
  15. * @see wp_terms_checklist() 
  16. * @param array $args An array of arguments. 
  17. * @param int $post_id The post ID. 
  18. */ 
  19. $params = apply_filters( 'wp_terms_checklist_args', $args, $post_id ); 
  20.  
  21. $r = wp_parse_args( $params, $defaults ); 
  22.  
  23. if ( empty( $r[walker] ) || ! ( $r[walker] instanceof Walker ) ) { 
  24. $walker = new Walker_Category_Checklist; 
  25. } else { 
  26. $walker = $r[walker]; 
  27.  
  28. $taxonomy = $r['taxonomy']; 
  29. $descendants_and_self = (int) $r['descendants_and_self']; 
  30.  
  31. $args = array( 'taxonomy' => $taxonomy ); 
  32.  
  33. $tax = get_taxonomy( $taxonomy ); 
  34. $args['disabled'] = ! current_user_can( $tax->cap->assign_terms ); 
  35.  
  36. $args['list_only'] = ! empty( $r['list_only'] ); 
  37.  
  38. if ( is_array( $r['selected_cats'] ) ) { 
  39. $args['selected_cats'] = $r['selected_cats']; 
  40. } elseif ( $post_id ) { 
  41. $args['selected_cats'] = wp_get_object_terms( $post_id, $taxonomy, array_merge( $args, array( 'fields' => 'ids' ) ) ); 
  42. } else { 
  43. $args['selected_cats'] = array(); 
  44. if ( is_array( $r['popular_cats'] ) ) { 
  45. $args['popular_cats'] = $r['popular_cats']; 
  46. } else { 
  47. $args['popular_cats'] = get_terms( $taxonomy, array( 
  48. 'fields' => 'ids',  
  49. 'orderby' => 'count',  
  50. 'order' => 'DESC',  
  51. 'number' => 10,  
  52. 'hierarchical' => false 
  53. ) ); 
  54. if ( $descendants_and_self ) { 
  55. $categories = (array) get_terms( $taxonomy, array( 
  56. 'child_of' => $descendants_and_self,  
  57. 'hierarchical' => 0,  
  58. 'hide_empty' => 0 
  59. ) ); 
  60. $self = get_term( $descendants_and_self, $taxonomy ); 
  61. array_unshift( $categories, $self ); 
  62. } else { 
  63. $categories = (array) get_terms( $taxonomy, array( 'get' => 'all' ) ); 
  64.  
  65. $output = ''; 
  66.  
  67. if ( $r['checked_ontop'] ) { 
  68. // 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) 
  69. $checked_categories = array(); 
  70. $keys = array_keys( $categories ); 
  71.  
  72. foreach ( $keys as $k ) { 
  73. if ( in_array( $categories[$k]->term_id, $args['selected_cats'] ) ) { 
  74. $checked_categories[] = $categories[$k]; 
  75. unset( $categories[$k] ); 
  76.  
  77. // Put checked cats on top 
  78. $output .= call_user_func_array( array( $walker, 'walk' ), array( $checked_categories, 0, $args ) ); 
  79. // Then the rest of them 
  80. $output .= call_user_func_array( array( $walker, 'walk' ), array( $categories, 0, $args ) ); 
  81.  
  82. if ( $r['echo'] ) { 
  83. echo $output; 
  84.  
  85. return $output;