WordPress at a glance

wp_dropdown_pages() WP 1.0

Retrieve or display list of pages as a dropdown (select list).

  • Since 4.2.0 The $value_field argument was added.
  • Since 4.3.0 The $class argument was added.
Hooks from function:
Return

String. HTML content, if not displaying.

Usage

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

Array or string of arguments to generate a pages drop-down element.

  • $depth (int)
    Maximum depth.

  • $child_of (int)
    Page ID to retrieve child pages of.

  • $selected (int/string)
    Value of the option that should be selected.

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

  • $name (string)
    Value for the 'name' attribute of the select element.
    Default: 'page_id'

  • $id (string)
    Value for the 'id' attribute of the select element.

  • $class (string)
    Value for the 'class' attribute of the select element. Default: none.
    Default: value of $name

  • $show_option_none (string)
    Text to display for showing no pages.
    Default: empty (does not display)

  • $show_option_no_change (string)
    Text to display for "no change" option.
    Default: empty (does not display)

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

  • $value_field (string)
    Post field used to populate the 'value' attribute of the option elements. Accepts any valid post field.
    Default: 'ID'

Default: ''

Code of wp_dropdown_pages: wp-includes/post-template.php VER 5.0.1

<?php
function wp_dropdown_pages( $args = '' ) {
	$defaults = array(
		'depth' => 0, 'child_of' => 0,
		'selected' => 0, 'echo' => 1,
		'name' => 'page_id', 'id' => '',
		'class' => '',
		'show_option_none' => '', 'show_option_no_change' => '',
		'option_none_value' => '',
		'value_field' => 'ID',
	);

	$r = wp_parse_args( $args, $defaults );

	$pages = get_pages( $r );
	$output = '';
	// Back-compat with old system where both id and name were based on $name argument
	if ( empty( $r['id'] ) ) {
		$r['id'] = $r['name'];
	}

	if ( ! empty( $pages ) ) {
		$class = '';
		if ( ! empty( $r['class'] ) ) {
			$class = " class='" . esc_attr( $r['class'] ) . "'";
		}

		$output = "<select name='" . esc_attr( $r['name'] ) . "'" . $class . " id='" . esc_attr( $r['id'] ) . "'>\n";
		if ( $r['show_option_no_change'] ) {
			$output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n";
		}
		if ( $r['show_option_none'] ) {
			$output .= "\t<option value=\"" . esc_attr( $r['option_none_value'] ) . '">' . $r['show_option_none'] . "</option>\n";
		}
		$output .= walk_page_dropdown_tree( $pages, $r['depth'], $r );
		$output .= "</select>\n";
	}

	/**
	 * Filters the HTML output of a list of pages as a drop down.
	 *
	 * @since 2.1.0
	 * @since 4.4.0 `$r` and `$pages` added as arguments.
	 *
	 * @param string $output HTML output for drop down list of pages.
	 * @param array  $r      The parsed arguments array.
	 * @param array  $pages  List of WP_Post objects returned by `get_pages()`
 	 */
	$html = apply_filters( 'wp_dropdown_pages', $output, $r, $pages );

	if ( $r['echo'] ) {
		echo $html;
	}
	return $html;
}

Related Functions

From tag: List (wp_list)

More from category: Pages

No comments
    Hello, !     Log In . Register