wp_dropdown_pages( array|string $args = '' )
Retrieve or display a list of pages as a dropdown (select list).
Contents
Description
See also
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
(string) HTML dropdown list of pages.
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. See wp_dropdown_pages() * for information on accepted arguments. * @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 View on GitHub
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
You must log in before being able to contribute a note or feedback.
Dropdown with submit button
Displays a hierarchical page dropdown list in HTML form with a submit button.
Make dropdown list multiple select
This is useful when you want to make multiple select or using with
select2.js
kinda things.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'
In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() source code:
Top ↑
Feedback
to make “post_type” work you have to set “hierarchical” to true at the custom post type creation args — By The Three —