WordPress at a glance

wp_list_pages() WP 1.0

Retrieve or display list of pages (or hierarchical post type items) in list (li) format.

  • See: get_pages()
  • Global. WP_Query. $wp_query
  • Since 4.7.0 Added the item_spacing argument.
Is the basis for: wp_page_menu()
Works based on: get_pages()
✈ 1 time = 0.014449s = extreme slow | 50000 times = 213.16s = extreme slow PHP 7.1.2, WP 4.7.3

No Hooks.

Return

String/null. HTML list of pages.

Usage

wp_list_pages( $args );
$args(array/string)

Array or string of arguments. Optional.

  • $child_of (int)
    Display only the sub-pages of a single page by ID.
    Default: 0 (all pages)

  • $authors (string)
    Comma-separated list of author IDs.
    Default: empty (all authors)

  • $date_format (string)
    PHP date format to use for the listed pages. Relies on the 'show_date' parameter.
    Default: value of 'date_format' option

  • $depth (int)
    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 (true/false)
    Whether or not to echo the list of pages.
    Default: true

  • $exclude (string)
    Comma-separated list of page IDs to exclude.
    Default: ''

  • $include (array)
    Comma-separated list of page IDs to include.
    Default: ''

  • $link_after (string)
    Text or HTML to follow the page link label.
    Default: null

  • $link_before (string)
    Text or HTML to precede the page link label.
    Default: null

  • $post_type (string)
    Post type to query for.
    Default: 'page'

  • $post_status (string/array)
    Comma-separated list or array of post statuses to include.
    Default: 'publish'

  • $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.
    Default: ''

  • $sort_column (string)
    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'.
    Default: 'post_title'

  • $title_li (string)
    List heading. Passing a null or empty value will result in no heading, and the list will not be wrapped with unordered list <ul> tags.
    Default: 'Pages'

  • $item_spacing (string)
    Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.
    Default: 'preserve'

  • $walker (Walker)
    Walker instance to use for listing pages.
    Default: empty (Walker_Page)

Default: ''

Code of wp_list_pages: wp-includes/post-template.php VER 5.0.1

<?php
function wp_list_pages( $args = '' ) {
	$defaults = array(
		'depth'        => 0,
		'show_date'    => '',
		'date_format'  => get_option( 'date_format' ),
		'child_of'     => 0,
		'exclude'      => '',
		'title_li'     => __( 'Pages' ),
		'echo'         => 1,
		'authors'      => '',
		'sort_column'  => 'menu_order, post_title',
		'link_before'  => '',
		'link_after'   => '',
		'item_spacing' => 'preserve',
		'walker'       => '',
	);

	$r = wp_parse_args( $args, $defaults );

	if ( ! in_array( $r['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// invalid value, fall back to default.
		$r['item_spacing'] = $defaults['item_spacing'];
	}

	$output = '';
	$current_page = 0;

	// sanitize, mostly to keep spaces out
	$r['exclude'] = preg_replace( '/[^0-9,]/', '', $r['exclude'] );

	// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array)
	$exclude_array = ( $r['exclude'] ) ? explode( ',', $r['exclude'] ) : array();

	/**
	 * Filters the array of pages to exclude from the pages list.
	 *
	 * @since 2.1.0
	 *
	 * @param array $exclude_array An array of page IDs to exclude.
	 */
	$r['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );

	// Query pages.
	$r['hierarchical'] = 0;
	$pages = get_pages( $r );

	if ( ! empty( $pages ) ) {
		if ( $r['title_li'] ) {
			$output .= '<li class="pagenav">' . $r['title_li'] . '<ul>';
		}
		global $wp_query;
		if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {
			$current_page = get_queried_object_id();
		} elseif ( is_singular() ) {
			$queried_object = get_queried_object();
			if ( is_post_type_hierarchical( $queried_object->post_type ) ) {
				$current_page = $queried_object->ID;
			}
		}

		$output .= walk_page_tree( $pages, $r['depth'], $current_page, $r );

		if ( $r['title_li'] ) {
			$output .= '</ul></li>';
		}
	}

	/**
	 * Filters the HTML output of the pages to list.
	 *
	 * @since 1.5.1
	 * @since 4.4.0 `$pages` added as arguments.
	 *
	 * @see wp_list_pages()
	 *
	 * @param string $output HTML output of the pages list.
	 * @param array  $r      An array of page-listing arguments.
	 * @param array  $pages  List of WP_Post objects returned by `get_pages()`
	 */
	$html = apply_filters( 'wp_list_pages', $output, $r, $pages );

	if ( $r['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

Related Functions

From tag: List (wp_list)

More from category: Pages

No comments
    Hello, !     Log In . Register