Description Description
The ‘hierarchical’ argument, which is disabled by default, will override the depth argument, unless it is true. When the argument is false, it will display all of the categories. When it is enabled it will use the value in the ‘depth’ argument.
Parameters Parameters
- $args
-
(array|string) (Optional) Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct() for information on additional accepted arguments.
- ‘show_option_all’
(string) Text to display for showing all categories. - ‘show_option_none’
(string) Text to display for showing no categories. - ‘option_none_value’
(string) Value to use when no category is selected. - ‘orderby’
(string) Which column to use for ordering categories. See get_terms() for a list of accepted values. Default ‘id’ (term_id). - ‘pad_counts’
(bool) See get_terms() for an argument description. Default false. - ‘show_count’
(bool|int) Whether to include post counts. Accepts 0, 1, or their bool equivalents. Default 0. - ‘echo’
(bool|int) Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1. - ‘hierarchical’
(bool|int) Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents. Default 0. - ‘depth’
(int) Maximum depth. Default 0. - ‘tab_index’
(int) Tab index for the select element. Default 0 (no tabindex). - ‘name’
(string) Value for the ‘name’ attribute of the select element. Default ‘cat’. - ‘id’
(string) Value for the ‘id’ attribute of the select element. Defaults to the value of$name. - ‘class’
(string) Value for the ‘class’ attribute of the select element. Default ‘postform’. - ‘selected’
(int|string) Value of the option that should be selected. Default 0. - ‘value_field’
(string) Term field that should be used to populate the ‘value’ attribute of the option elements. Accepts any valid term field: ‘term_id’, ‘name’, ‘slug’, ‘term_group’, ‘term_taxonomy_id’, ‘taxonomy’, ‘description’, ‘parent’, ‘count’. Default ‘term_id’. - ‘taxonomy’
(string|array) Name of the category or categories to retrieve. Default ‘category’. - ‘hide_if_empty’
(bool) True to skip generating markup if no categories are found. Default false (create select element even if no categories are found). - ‘required’
(bool) Whether the<select>element should have the HTML5 ‘required’ attribute. Default false.
Default value: ”
- ‘show_option_all’
Return Return
(string) HTML dropdown list of categories.
More Information More Information
If you want to allow users to select multiple values, use wp_category_checklist().
The wp_dropdown_cats filter is applied to the output string before it is echoed/returned.
Source Source
File: wp-includes/category-template.php
|
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 |
function wp_dropdown_categories( $args = '' ) { $defaults = array( 'show_option_all' => '', 'show_option_none' => '', 'orderby' => 'id', 'order' => 'ASC', 'show_count' => 0, 'hide_empty' => 1, 'child_of' => 0, 'exclude' => '', 'echo' => 1, 'selected' => 0, 'hierarchical' => 0, 'name' => 'cat', 'id' => '', 'class' => 'postform', 'depth' => 0, 'tab_index' => 0, 'taxonomy' => 'category', 'hide_if_empty' => false, 'option_none_value' => -1, 'value_field' => 'term_id', 'required' => false, ); $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0; // Back compat. if ( isset( $args['type'] ) && 'link' === $args['type'] ) { _deprecated_argument( __FUNCTION__, '3.0.0', sprintf( /* translators: 1: "type => link", 2: "taxonomy => link_category" */ __( '%1$s is deprecated. Use %2$s instead.' ), '<code>type => link</code>', '<code>taxonomy => link_category</code>' ) ); $args['taxonomy'] = 'link_category'; } // Parse incoming $args into an array and merge it with $defaults. $parsed_args = wp_parse_args( $args, $defaults ); $option_none_value = $parsed_args['option_none_value']; if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) { $parsed_args['pad_counts'] = true; } $tab_index = $parsed_args['tab_index']; $tab_index_attribute = ''; if ( (int) $tab_index > 0 ) { $tab_index_attribute = " tabindex="$tab_index""; } // Avoid clashes with the 'name' param of get_terms(). $get_terms_args = $parsed_args; unset( $get_terms_args['name'] ); $categories = get_terms( $get_terms_args ); $name = esc_attr( $parsed_args['name'] ); $class = esc_attr( $parsed_args['class'] ); $id = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name; $required = $parsed_args['required'] ? 'required' : ''; if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) { $output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>n"; } else { $output = ''; } if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) { /** * Filters a taxonomy drop-down display element. * * A variety of taxonomy drop-down display elements can be modified * just prior to display via this filter. Filterable arguments include * 'show_option_none', 'show_option_all', and various forms of the * term name. * * @since 1.2.0 * * @see wp_dropdown_categories() * * @param string $element Category name. * @param WP_Term|null $category The category object, or null if there's no corresponding category. */ $show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null ); $output .= "t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>n"; } if ( ! empty( $categories ) ) { if ( $parsed_args['show_option_all'] ) { /** This filter is documented in wp-includes/category-template.php */ $show_option_all = apply_filters( 'list_cats', $parsed_args['show_option_all'], null ); $selected = ( '0' === strval( $parsed_args['selected'] ) ) ? " selected='selected'" : ''; $output .= "t<option value='0'$selected>$show_option_all</option>n"; } if ( $parsed_args['show_option_none'] ) { /** This filter is documented in wp-includes/category-template.php */ $show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null ); $selected = selected( $option_none_value, $parsed_args['selected'], false ); $output .= "t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>n"; } if ( $parsed_args['hierarchical'] ) { $depth = $parsed_args['depth']; // Walk the full depth. } else { $depth = -1; // Flat. } $output .= walk_category_dropdown_tree( $categories, $depth, $parsed_args ); } if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) { $output .= "</select>n"; } /** * Filters the taxonomy drop-down output. * * @since 2.1.0 * * @param string $output HTML output. * @param array $parsed_args Arguments used to build the drop-down. */ $output = apply_filters( 'wp_dropdown_cats', $output, $parsed_args ); if ( $parsed_args['echo'] ) { echo $output; } return $output;} |
Changelog Changelog
| Version | Description |
|---|---|
| 4.6.0 | Introduced the required argument. |
| 4.2.0 | Introduced the value_field argument. |
| 2.1.0 | Introduced. |