WordPress at a glance

wp_dropdown_categories() WP 1.0

Display or retrieve 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.

Возвращает

String. HTML dropdown list of categories.

Hooks from the function

Usage

wp_dropdown_categories( $args );
$args(array/string)

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.
    Default: ''

  • show_option_none(string)
    Text to display for showing no categories.
    Default: ''

  • option_none_value(string)
    Value to use when no category is selected.
    Default: ''

  • orderby(string)
    Which column to use for ordering categories. See get_terms() for a list of accepted values. (term_id).
    Default: 'id'

  • pad_counts(true/false)
    See get_terms() for an argument description.
    Default: false

  • show_count(true/false/int)
    Whether to include post counts. Accepts 0, 1, or their bool equivalents.

  • echo(true/false/int)
    Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.
    Default: 1

  • hierarchical(true/false/int)
    Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents.

  • depth(int)
    Maximum depth.

  • 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.
    Default: 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.

  • 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(true/false)
    True to skip generating markup if no categories are found.
    Default: false (create select element even if no categories are found)

  • required(true/false)
    Whether the <select> element should have the HTML5 'required' attribute.
    Default: false

Default: ''

Список изменений

С версии 2.1.0 Введена.
С версии 4.2.0 Introduced the value_field argument.
С версии 4.6.0 Introduced the required argument.

Code of wp_dropdown_categories() WP 5.5.1

wp-includes/category-template.php
<?php
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;
}

Related Functions

From tag: List (wp_list)

More from category: Categories

More from Template Tags: Taxonomies (category, tag)

No comments
    Log In . Register