wp_dropdown_pages()

You are here:

wp_dropdown_pages( array|string $args =  )

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

Description Description

See also See also

  • get_pages()

Top ↑

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: ”


Top ↑

Return Return

(string) HTML dropdown list of pages.


Top ↑

Source Source

File: wp-includes/post-template.php

1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
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;
}


Top ↑

Changelog Changelog

Changelog
VersionDescription
4.3.0The $class argument was added.
4.2.0The $value_field argument was added.
2.1.0Introduced.
Was this article helpful?
Dislike 0
Views: 2

Cart

Log in

Create an Account
Back to Top