wp_dropdown_pages

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

Description

(string) wp_dropdown_pages( (string) $args = '' ); 

Returns (string)

HTML content, if not displaying.

Parameters (1)

0. $args — Optional. (string) => ''
Array or string of arguments to generate a pages drop-down element.

Options

  • depth (int) => 0

    Maximum depth.

  • child_of (int) => 0

    Page ID to retrieve child pages of.

  • selected (int|string) => ''

    Value of the option that should be selected.

  • echo (bool|int) => 1

    Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.

  • name (string) => 'page_id'

    Value for the name attribute of the select element.

  • id (string) => ''

    Value for the id attribute of the select element.

  • class (string) => 'to the value of $name'

    Value for the class attribute of the select element. Default: none.

  • show_option_none (string) => (does not display)

    Text to display for showing no pages.

  • show_option_no_change (string) => (does not display)

    Text to display for no change option.

  • option_none_value (string) => ''

    Value to use when no page is selected.

array(

    /**
     * Maximum depth.
     *
     * @type int
     */
    'depth' => 0,

    /**
     * Page ID to retrieve child pages of.
     *
     * @type int
     */
    'child_of' => 0,

    /**
     * Value of the option that should be selected.
     *
     * @type int|string
     * @default ''
     */
    'selected' => '',

    /**
     * Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents.
     *
     * @type bool|int
     * @default 1
     */
    'echo' => 1,

    /**
     * Value for the 'name' attribute of the select element.
     *
     * @type string
     * @default 'page_id'
     */
    'name' => 'page_id',

    /**
     * Value for the 'id' attribute of the select element.
     *
     * @type string
     * @default ''
     */
    'id' => '',

    /**
     * Value for the 'class' attribute of the select element. Default: none.
     *
     * @type string
     * @default 'to the value of $name'
     */
    'class' => 'to the value of $name',

    /**
     * Text to display for showing no pages.
     *
     * @type string
     * @default (does not display)
     */
    'show_option_none' => (does not display),

    /**
     * Text to display for "no change" option.
     *
     * @type string
     * @default (does not display)
     */
    'show_option_no_change' => (does not display),

    /**
     * Value to use when no page is selected.
     *
     * @type string
     * @default ''
     */
    'option_none_value' => ''
);        


Usage

  1. if ( !function_exists( 'wp_dropdown_pages' ) ) { 
  2. require_once ABSPATH . WPINC . '/post-template.php'; 
  3.  
  4. // Optional. Array or string of arguments to generate a pages drop-down element. 
  5. $args = array( 
  6. 'depth' => 0, 
  7. 'child_of' => 0, 
  8. 'selected' => '', 
  9. 'echo' => 1, 
  10. 'name' => 'page_id', 
  11. 'id' => '', 
  12. 'class' => 'to the value of $name', 
  13. 'show_option_none' => (does not display), 
  14. 'show_option_no_change' => (does not display), 
  15. 'option_none_value' => '' 
  16. ); 
  17.  
  18. // NOTICE! Understand what this does before running. 
  19. $result = wp_dropdown_pages($args); 
  20.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/post-template.php  
  1. function wp_dropdown_pages( $args = '' ) { 
  2. $defaults = array( 
  3. 'depth' => 0, 'child_of' => 0,  
  4. 'selected' => 0, 'echo' => 1,  
  5. 'name' => 'page_id', 'id' => '',  
  6. 'class' => '',  
  7. 'show_option_none' => '', 'show_option_no_change' => '',  
  8. 'option_none_value' => '',  
  9. 'value_field' => 'ID',  
  10. ); 
  11.  
  12. $r = wp_parse_args( $args, $defaults ); 
  13.  
  14. $pages = get_pages( $r ); 
  15. $output = ''; 
  16. // Back-compat with old system where both id and name were based on $name argument 
  17. if ( empty( $r['id'] ) ) { 
  18. $r['id'] = $r['name']; 
  19.  
  20. if ( ! empty( $pages ) ) { 
  21. $class = ''; 
  22. if ( ! empty( $r['class'] ) ) { 
  23. $class = " class='" . esc_attr( $r['class'] ) . "'"; 
  24.  
  25. $output = "<select name='" . esc_attr( $r['name'] ) . "'" . $class . " id='" . esc_attr( $r['id'] ) . "'>\n"; 
  26. if ( $r['show_option_no_change'] ) { 
  27. $output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n"; 
  28. if ( $r['show_option_none'] ) { 
  29. $output .= "\t<option value=\"" . esc_attr( $r['option_none_value'] ) . '">' . $r['show_option_none'] . "</option>\n"; 
  30. $output .= walk_page_dropdown_tree( $pages, $r['depth'], $r ); 
  31. $output .= "</select>\n"; 
  32.  
  33. /** 
  34. * Filters the HTML output of a list of pages as a drop down. 
  35. * @since 2.1.0 
  36. * @since 4.4.0 `$r` and `$pages` added as arguments. 
  37. * @param string $output HTML output for drop down list of pages. 
  38. * @param array $r The parsed arguments array. 
  39. * @param array $pages List of WP_Post objects returned by `get_pages()` 
  40. */ 
  41. $html = apply_filters( 'wp_dropdown_pages', $output, $r, $pages ); 
  42.  
  43. if ( $r['echo'] ) { 
  44. echo $html; 
  45. return $html;