wp_dropdown_pages( array|string $args = '' )
Retrieve or display a list of pages as a dropdown (select list).
Contents
Description Description
See also See also
Parameters Parameters
- $args
-
(array|string) (Optional) Array or string of arguments to generate a page dropdown. See
get_pages()for additional arguments.- 'depth'
(int) Maximum depth. Default 0. - 'child_of'
(int) Page ID to retrieve child pages of. Default 0. - 'selected'
(int|string) Value of the option that should be selected. Default 0. - 'echo'
(bool|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. Defaults to the 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. - 'value_field'
(string) Post field used to populate the 'value' attribute of the option elements. Accepts any valid post field. Default 'ID'.
Default value: ''
- 'depth'
Return Return
(string) HTML dropdown list of pages.
Source Source
File: wp-includes/post-template.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',
);
$parsed_args = wp_parse_args( $args, $defaults );
$pages = get_pages( $parsed_args );
$output = '';
// Back-compat with old system where both id and name were based on $name argument.
if ( empty( $parsed_args['id'] ) ) {
$parsed_args['id'] = $parsed_args['name'];
}
if ( ! empty( $pages ) ) {
$class = '';
if ( ! empty( $parsed_args['class'] ) ) {
$class = " class='" . esc_attr( $parsed_args['class'] ) . "'";
}
$output = "<select name='" . esc_attr( $parsed_args['name'] ) . "'" . $class . " id='" . esc_attr( $parsed_args['id'] ) . "'>\n";
if ( $parsed_args['show_option_no_change'] ) {
$output .= "\t<option value=\"-1\">" . $parsed_args['show_option_no_change'] . "</option>\n";
}
if ( $parsed_args['show_option_none'] ) {
$output .= "\t<option value=\"" . esc_attr( $parsed_args['option_none_value'] ) . '">' . $parsed_args['show_option_none'] . "</option>\n";
}
$output .= walk_page_dropdown_tree( $pages, $parsed_args['depth'], $parsed_args );
$output .= "</select>\n";
}
/**
* Filters the HTML output of a list of pages as a drop down.
*
* @since 2.1.0
* @since 4.4.0 `$parsed_args` and `$pages` added as arguments.
*
* @param string $output HTML output for drop down list of pages.
* @param array $parsed_args The parsed arguments array.
* @param WP_Post[] $pages Array of the page objects.
*/
$html = apply_filters( 'wp_dropdown_pages', $output, $parsed_args, $pages );
if ( $parsed_args['echo'] ) {
echo $html;
}
return $html;
}
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 4.3.0 | The $class argument was added. |
| 4.2.0 | The $value_field argument was added. |
| 2.1.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() source code:
$dropdown_args = array( 'post_type' => $post->post_type, 'exclude_tree' => $post->ID, 'selected' => $post->post_parent, 'name' => 'parent_id', 'show_option_none' => __('(no parent)'), 'sort_column' => 'menu_order, post_title', 'echo' => 0, ); ... $pages = wp_dropdown_pages( $dropdown_args );Feedback
to make “post_type” work you have to set “hierarchical” to true at the custom post type creation args — By The Three —
For this to work for custom post types, you must set
in the custom post type’s settings when you register_post_type that you are getting the dropdown for.
If you don’t want the custom post type to truly be hierarchical, ensure the
'supports'arg doesn’t include'page-attributes'Dropdown with submit button
Displays a hierarchical page dropdown list in HTML form with a submit button.
<li id="pages"> <h2><?php _e('pages:'); ?></h2> <form action="<?php bloginfo('url'); ?>" method="get"> <?php wp_dropdown_pages(); ?> <input type="submit" name="submit" value="view" /> </form> </li>Make dropdown list multiple select
This is useful when you want to make multiple select or using with
select2.jskinda things.add_filter( 'wp_dropdown_pages', 'wporg_domain_make_multiple_select_pages' ); function wporg_domain_make_multiple_select_pages( $output ) { return str_replace( '<select ', '<select multiple="multiple" ', $output ); }