wp_list_pages

Retrieve or display list of pages in list (li) format.

Description

(string|void) wp_list_pages( (string) $args = '' ); 

Returns (string|void)

HTML list of pages.

Parameters (1)

0. $args — Optional. (string) => ''
Array or string of arguments. Optional.

Options

  • child_of (int) => 0 (all pages)

    Display only the sub-pages of a single page by ID.

  • authors (string) => (all authors)

    Comma-separated list of author IDs.

  • date_format (string) => 'date_format'

    PHP date format to use for the listed pages. Relies on the show_date parameter.

  • depth (int) => 0

    Number of levels in the hierarchy of pages to include in the generated list. Accepts -1 (any depth), 0 (all pages), 1 (top-level pages only), and n (pages to the given n depth).

  • echo (bool) => true

    Whether or not to echo the list of pages.

  • exclude (string) => ''

    Comma-separated list of page IDs to exclude.

  • include (array) => null

    Comma-separated list of page IDs to include.

  • link_after (string) => null

    Text or HTML to follow the page link label.

  • link_before (string) => null

    Text or HTML to precede the page link label.

  • post_type (string) => 'page'

    Post type to query for.

  • post_status (string|array) => 'publish'

    Comma-separated list or array of post statuses to include.

  • show_date (string) => ''

    Whether to display the page publish or modified date for each page. Accepts modified or any other value. An empty value hides the date.

  • sort_column (string) => 'post_title'

    Comma-separated list of column names to sort the pages by. Accepts post_author,, post_date., post_title, post_name, post_modified, post_modified_gmt, menu_order, post_parent, ID, rand, or comment_count.

  • title_li (string) => 'Pages'

    List heading. Passing a null or empty value will result in no heading, and the list will not be wrapped with unordered list

      tags.

  • item_spacing (string) => 'preserve'

    Whether to preserve whitespace within the menu's HTML. Accepts preserve or discard..

array(

    /**
     * Display only the sub-pages of a single page by ID.
     *
     * @type int
     * @default 0 (all pages)
     */
    'child_of' => 0 (all pages),

    /**
     * Comma-separated list of author IDs.
     *
     * @type string
     * @default (all authors)
     */
    'authors' => (all authors),

    /**
     * PHP date format to use for the listed pages. Relies on the 'show_date' parameter.
     *
     * @type string
     * @default 'date_format'
     */
    'date_format' => 'date_format',

    /**
     * Number of levels in the hierarchy of pages to include in the generated list. Accepts -1 (any
     * depth), 0 (all pages), 1 (top-level pages only), and n (pages to the given n depth).
     *
     * @type int
     */
    'depth' => 0,

    /**
     * Whether or not to echo the list of pages.
     *
     * @type bool
     * @default true
     */
    'echo' => true,

    /**
     * Comma-separated list of page IDs to exclude.
     *
     * @type string
     * @default ''
     */
    'exclude' => '',

    /**
     * Comma-separated list of page IDs to include.
     *
     * @type array
     * @default null
     */
    'include' => null,

    /**
     * Text or HTML to follow the page link label.
     *
     * @type string
     * @default null
     */
    'link_after' => null,

    /**
     * Text or HTML to precede the page link label.
     *
     * @type string
     * @default null
     */
    'link_before' => null,

    /**
     * Post type to query for.
     *
     * @type string
     * @default 'page'
     */
    'post_type' => 'page',

    /**
     * Comma-separated list or array of post statuses to include.
     *
     * @type string|array
     * @default 'publish'
     */
    'post_status' => 'publish',

    /**
     * Whether to display the page publish or modified date for each page. Accepts 'modified' or any
     * other value. An empty value hides the date.
     *
     * @type string
     * @default ''
     */
    'show_date' => '',

    /**
     * Comma-separated list of column names to sort the pages by. Accepts 'post_author',
     * 'post_date', 'post_title', 'post_name', 'post_modified', 'post_modified_gmt',
     * 'menu_order', 'post_parent', 'ID', 'rand', or 'comment_count'.
     *
     * @type string
     * @default 'post_title'
     */
    'sort_column' => 'post_title',

    /**
     * List heading. Passing a null or empty value will result in no heading, and the list will not be
     * wrapped with unordered list `` tags.
     *
     * @type string
     * @default 'Pages'
     */
    'title_li' => 'Pages',

    /**
     * Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.
     *
     * @type string
     * @default 'preserve'
     */
    'item_spacing' => 'preserve'
);        


Usage

  1. if ( !function_exists( 'wp_list_pages' ) ) { 
  2. require_once ABSPATH . WPINC . '/post-template.php'; 
  3.  
  4. // Array or string of arguments. Optional. 
  5. $args = array( 
  6. 'child_of' => 0 (all pages), 
  7. 'authors' => (all authors), 
  8. 'date_format' => 'date_format', 
  9. 'depth' => 0, 
  10. 'echo' => true, 
  11. 'exclude' => '', 
  12. 'include' => null, 
  13. 'link_after' => null, 
  14. 'link_before' => null, 
  15. 'post_type' => 'page', 
  16. 'post_status' => 'publish', 
  17. 'show_date' => '', 
  18. 'sort_column' => 'post_title', 
  19. 'title_li' => 'Pages', 
  20. 'item_spacing' => 'preserve' 
  21. ); 
  22.  
  23. // NOTICE! Understand what this does before running. 
  24. $result = wp_list_pages($args); 
  25.  

Defined (1)

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

/wp-includes/post-template.php  
  1. function wp_list_pages( $args = '' ) { 
  2. $defaults = array( 
  3. 'depth' => 0,  
  4. 'show_date' => '',  
  5. 'date_format' => get_option( 'date_format' ),  
  6. 'child_of' => 0,  
  7. 'exclude' => '',  
  8. 'title_li' => __( 'Pages' ),  
  9. 'echo' => 1,  
  10. 'authors' => '',  
  11. 'sort_column' => 'menu_order, post_title',  
  12. 'link_before' => '',  
  13. 'link_after' => '',  
  14. 'item_spacing' => 'preserve',  
  15. walker => '',  
  16. ); 
  17.  
  18. $r = wp_parse_args( $args, $defaults ); 
  19.  
  20. if ( ! in_array( $r['item_spacing'], array( 'preserve', 'discard' ), true ) ) { 
  21. // invalid value, fall back to default. 
  22. $r['item_spacing'] = $defaults['item_spacing']; 
  23.  
  24. $output = ''; 
  25. $current_page = 0; 
  26.  
  27. // sanitize, mostly to keep spaces out 
  28. $r['exclude'] = preg_replace( '/[^0-9, ]/', '', $r['exclude'] ); 
  29.  
  30. // Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array) 
  31. $exclude_array = ( $r['exclude'] ) ? explode( ', ', $r['exclude'] ) : array(); 
  32.  
  33. /** 
  34. * Filters the array of pages to exclude from the pages list. 
  35. * @since 2.1.0 
  36. * @param array $exclude_array An array of page IDs to exclude. 
  37. */ 
  38. $r['exclude'] = implode( ', ', apply_filters( 'wp_list_pages_excludes', $exclude_array ) ); 
  39.  
  40. // Query pages. 
  41. $r['hierarchical'] = 0; 
  42. $pages = get_pages( $r ); 
  43.  
  44. if ( ! empty( $pages ) ) { 
  45. if ( $r['title_li'] ) { 
  46. $output .= '<li class="pagenav">' . $r['title_li'] . '<ul>'; 
  47. global $wp_query; 
  48. if ( is_page() || is_attachment() || $wp_query->is_posts_page ) { 
  49. $current_page = get_queried_object_id(); 
  50. } elseif ( is_singular() ) { 
  51. $queried_object = get_queried_object(); 
  52. if ( is_post_type_hierarchical( $queried_object->post_type ) ) { 
  53. $current_page = $queried_object->ID; 
  54.  
  55. $output .= walk_page_tree( $pages, $r['depth'], $current_page, $r ); 
  56.  
  57. if ( $r['title_li'] ) { 
  58. $output .= '</ul></li>'; 
  59.  
  60. /** 
  61. * Filters the HTML output of the pages to list. 
  62. * @since 1.5.1 
  63. * @since 4.4.0 `$pages` added as arguments. 
  64. * @see wp_list_pages() 
  65. * @param string $output HTML output of the pages list. 
  66. * @param array $r An array of page-listing arguments. 
  67. * @param array $pages List of WP_Post objects returned by `get_pages()` 
  68. */ 
  69. $html = apply_filters( 'wp_list_pages', $output, $r, $pages ); 
  70.  
  71. if ( $r['echo'] ) { 
  72. echo $html; 
  73. } else { 
  74. return $html;