WordPress Version: 6.1
/**
* Displays or retrieves the HTML dropdown list of categories.
*
* 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.
*
* @since 2.1.0
* @since 4.2.0 Introduced the `value_field` argument.
* @since 4.6.0 Introduced the `required` argument.
* @since 6.1.0 Introduced the `aria_describedby` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct()
* for information on additional accepted arguments.
*
* @type string $show_option_all Text to display for showing all categories. Default empty.
* @type string $show_option_none Text to display for showing no categories. Default empty.
* @type string $option_none_value Value to use when no category is selected. Default empty.
* @type string $orderby Which column to use for ordering categories. See get_terms() for a list
* of accepted values. Default 'id' (term_id).
* @type bool $pad_counts See get_terms() for an argument description. Default false.
* @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents.
* Default 0.
* @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
* bool equivalents. Default 1.
* @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool
* equivalents. Default 0.
* @type int $depth Maximum depth. Default 0.
* @type int $tab_index Tab index for the select element. Default 0 (no tabindex).
* @type string $name Value for the 'name' attribute of the select element. Default 'cat'.
* @type string $id Value for the 'id' attribute of the select element. Defaults to the value
* of `$name`.
* @type string $class Value for the 'class' attribute of the select element. Default 'postform'.
* @type int|string $selected Value of the option that should be selected. Default 0.
* @type string $value_field 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'.
* @type string|array $taxonomy Name of the taxonomy or taxonomies to retrieve. Default 'category'.
* @type bool $hide_if_empty True to skip generating markup if no categories are found.
* Default false (create select element even if no categories are found).
* @type bool $required Whether the `<select>` element should have the HTML5 'required' attribute.
* Default false.
* @type Walker $walker Walker object to use to build the output. Default empty which results in a
* Walker_CategoryDropdown instance being used.
* @type string $aria_describedby The 'id' of an element that contains descriptive text for the select.
* Default empty string.
* }
* @return string HTML dropdown list of categories.
*/
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, 'aria_describedby' => '');
$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' : '';
$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr($parsed_args['aria_describedby']) . '"' : '';
if (!$parsed_args['hide_if_empty'] || !empty($categories)) {
$output = "<select {$required} name='{$name}' id='{$id}' class='{$class}'{$tab_index_attribute}{$aria_describedby_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' === (string) $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;
}