Retrieves or displays a list of pages as a dropdown (select list).
Description
See also
Parameters
$args
array|stringoptional- Array or string of arguments to generate a page dropdown. See get_pages() for additional arguments.
depth
intMaximum depth. Default 0.child_of
intPage ID to retrieve child pages of. Default 0.selected
int|stringValue of the option that should be selected. Default 0.echo
bool|intWhether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.name
stringValue for the'name'
attribute of the select element.
Default'page_id'
.id
stringValue for the'id'
attribute of the select element.class
stringValue for the'class'
attribute of the select element. Default: none.
Defaults to the value of$name
.show_option_none
stringText to display for showing no pages. Default empty (does not display).show_option_no_change
stringText to display for "no change" option. Default empty (does not display).option_none_value
stringValue to use when no page is selected.value_field
stringPost field used to populate the'value'
attribute of the option elements. Accepts any valid post field. Default'ID'
.
More Arguments from get_pages( … $args )
Array or string of arguments to retrieve pages.
child_of
intPage ID to return child and grandchild pages of. Note: The value of$hierarchical
has no bearing on whether$child_of
returns hierarchical results. Default 0, or no restriction.sort_order
stringHow to sort retrieved pages. Accepts'ASC'
,'DESC'
. Default'ASC'
.sort_column
stringWhat columns to sort pages by, comma-separated. Accepts'post_author'
,'post_date'
,'post_title'
,'post_name'
,'post_modified'
,'menu_order'
,'post_modified_gmt'
,'post_parent'
,'ID'
,'rand'
,'comment*count'
.
'post*'
can be omitted for any values that start with it.
Default'post_title'
.hierarchical
boolWhether to return pages hierarchically. If false in conjunction with$child_of
also being false, both arguments will be disregarded.
Default true.exclude
int[]Array of page IDs to exclude.include
int[]Array of page IDs to include. Cannot be used with$child_of
,$parent
,$exclude
,$meta_key
,$meta_value
, or$hierarchical
.
meta_key
stringOnly include pages with this meta key.meta_value
stringOnly include pages with this meta value. Requires$meta_key
.
authors
stringA comma-separated list of author IDs.parent
intPage ID to return direct children of. Default -1, or no restriction.exclude_tree
string|int[]Comma-separated string or array of page IDs to exclude.
number
intThe number of pages to return. Default 0, or all pages.offset
intThe number of pages to skip before returning. Requires$number
.
Default 0.post_type
stringThe post type to query. Default'page'
.post_status
string|arrayA comma-separated list or array of post statuses to include.
Default'publish'
.
Default:
''
Source
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 dropdown.
*
* @since 2.1.0
* @since 4.4.0 `$parsed_args` and `$pages` added as arguments.
*
* @param string $output HTML output for dropdown 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;
}
Hooks
- apply_filters( ‘wp_dropdown_pages’,
string $output ,array $parsed_args ,WP_Post[] $pages ) Filters the HTML output of a list of pages as a dropdown.
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.
Make dropdown list multiple select
This is useful when you want to make multiple select or using with
select2.js
kinda things.In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() source code: