wp_dropdown_pages() WordPress Function
The wp_dropdown_pages() function allows you to create a drop-down list of pages in your Wordpress site. This can be useful if you want to create a navigation menu or a list of pages that can be linked to from other pages on your site.
wp_dropdown_pages( array|string $args = '' ) #
Retrieves or displays a list of pages as a dropdown (select list).
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 codeCollapse full source codeView on TracView 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. |