WordPress:Template Tags/wp list pages
Description
The Template Tag, wp_list_pages(), displays a list of WordPress WordPress:Pages as links. It is often used to customize the Sidebar or Header, but may be used in other WordPress:Templates as well.
This Template Tag is available for WordPress versions 1.5 and newer.
Usage
%%% <?php wp_list_pages('arguments'); ?> %%%
Examples
Default Usage
$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');
By default, the usage shows:
- All Pages and sub-pages are displayed (no depth restriction)
- Date created is not displayed
- Is not restricted to the child_of any Page
- No pages are excluded
- The title of the pages listed is "Pages"
- Results are echoed (displayed)
- Is not restricted to any specific author
- Sorted by Page Order then Page Title.
- Sorted in ascending order (not shown in defaults above)
- Pages displayed in a hierarchical indented fashion (not shown in defaults above)
- Includes all Pages (not shown in defaults above)
- Not restricted to Pages with specific meta key/meta value (not shown in defaults above)
wp_list_pages();
Hiding or Changing the List Heading
The default heading of the list ("Pages") of Pages generated by wp_list_pages can be hidden by passing a null or empty value to the title_li parameter. The following example displays no heading text above the list.
<ul>
<?php
wp_list_pages('title_li='); ?>
</ul>
In the following example, only Pages with IDs 9, 5, and 23 are included in the list and the heading text has been changed to the word "Poetry", with a heading style of <h2>:
<ul>
<?php
wp_list_pages('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>' ); ?>
</ul>
List Pages by Page Order
The following example lists the Pages in the order defined by the Page Order settings for each Page in the Write > Page administrative panel.
<ul>
<?php
wp_list_pages('sort_column=menu_order'); ?>
</ul>
If you wanted to sort the list by Page Order and display the word "Prose" as the list heading (in h2 style) on a Sidebar, you could add the following code to the sidebar.php file:
<ul>
<?php
wp_list_pages('sort_column=menu_order&title_li=<h2>' . __('Prose') . '</h2>' ); ?>
</ul>
Using the following piece of code, the Pages will display without heading and in Page Order:
<ul>
<?php
wp_list_pages('sort_column=menu_order&title_li='); ?>
</ul>
Sort Pages by Post Date
This example displays Pages sorted by (creation) date, and shows the date next to each Page list item.
<ul>
<?php
wp_list_pages('sort_column=post_date&show_date=created'); ?>
</ul>
Exclude Pages from List
Use the exclude parameter hide certain Pages from the list to be generated by wp_list_pages.
<ul>
<?php
wp_list_pages('exclude=17,38' ); ?>
</ul>
Include Pages in List
To include only certain Pages in the list, for instance, Pages with ID numbers 35, 7, 26 and 13, use the include parameter.
<ul>
<?php
wp_list_pages('include=7,13,26,35&title_li=<h2>' . __('Pages') . '</h2>' ); ?>
</ul>
List Sub-Pages (versions prior to Wordpress 2.0.1)
Put this inside the the_post() section of the page.php template of your WordPress theme after the_content(), or put it in a copy of the page.php template that you use for pages that have sub-pages:
<ul>
<?php
global $id;
// teensy bit insane, sorry
$date_format = '<\b\r /><\s\p\a\n '.
'\s\t\y\l\e="\f\o\n\t-\s\i\z\e: \s\m\a\l\l\e\r">'.
'\l\a\s\t\m\o\d Y-n-j</\s\p\a\n>';
wp_list_pages("title_li=&child_of=$id&show_date=modified
&date_format=$date_format"); ?>
</ul>
NOTE: This example does not work with Wordpress 2.0.1 or newer if placed in a page template because the global $id is not set. Use the following code
List Sub-Pages (Wordpress 2.0.1 or newer)
NOTE: Requires an HTML tag (either <ul> or <ol>) even if there are no subpages. Keep this in mind if you are using css to style the list.
<ul>
<?php
wp_list_pages('title_li=&child_of='.$post->ID.'&show_date=modified
&date_format=$date_format'); ?>
</ul>
The following example will generate a list only if there are child (Pages that designate the current page as a Parent) for the current Page:
<?php
$children = wp_list_pages('title_li=&child_of='.$post->ID.'&echo=0');
if ($children) { ?>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
List subpages even if on a subpage
The above examples will only show the children from the parent page, but not when actually on a child page. This code will show the child pages, and only the child pages, when on a parent or on one of the children.
- warning ** This code will not work if placed after a widget block in the sidebar.
<?php
if($post->post_parent)
$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
else
$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
if ($children) { ?>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
Markup and styling of page items
By default, wp_list_pages() generates a nested, unordered list of WordPress WordPress:Pages created with the Write > Page admin panel. You can remove the outermost item (li.pagenav) and list (ul) by setting the title_li parameter to an empty string.
All list items (li) generated by wp_list_pages() are marked with the class page_item. When wp_list_pages() is called while displaying a Page, the list item for that Page is given the additional class current_page_item.
<li class="pagenav"> Pages <ul> <li class="page_item current_page_parent"> [parent of the current page] <ul> <li class="page_item current_page_item"> [the current page] </li> </ul> </li> <li class="page_item"> [another page] </li> </ul> </li>
They can be styled with CSS selectors:
.pagenav { ... } .page_item { ... } .current_page_item { ... } .current_page_parent { ... }
Parameters
- sort_column (string)
- Sorts the list of Pages in a number of different ways. The default setting is sort alphabetically by Page title.
- 'post_title' - Sort Pages alphabetically (by title) - default
- 'menu_order' - Sort Pages by Page Order. N.B. Note the difference between Page Order and Page ID. The Page ID is a unique number assigned by WordPress to every post or page. The Page Order can be set by the user in the Write>Pages administrative panel. See the [[WordPress:#List Pages by Page Order|example]] below.
- 'post_date' - Sort by creation time.
- 'post_modified' - Sort by time last modified.
- 'ID' - Sort by numeric Page ID.
- 'post_author' - Sort by the Page author's numeric ID.
- 'post_name' - Sort alphabetically by Post slug.
Note: The sort_column parameter can be used to sort the list of Pages by the descriptor of any field in the wp_post table of the WordPress database. Some useful examples are listed here.
- sort_order (string)
- Change the sort order of the list of Pages (either ascending or descending). The default is ascending. Valid values:
- 'asc' - Sort from lowest to highest (Default).
- 'desc' - Sort from highest to lowest.
- exclude (string)
- Define a comma-separated list of Page IDs to be excluded from the list (example: 'exclude=3,7,31'). There is no default value. See the [[WordPress:#Exclude Pages from List|Exclude Pages from List]] example below.
- include (string)
- Only include certain Pages in the list generated by wp_list_pages. Like exclude, this parameter takes a comma-separated list of Page IDs. There is no default value. See the [[WordPress:#Include Pages in List|Include Pages in List]] example below.
- depth (integer)
- This parameter controls how many levels in the hierarchy of pages are to be included in the list generated by wp_list_pages. The default value is 0 (display all pages, including all sub-pages).
- 0 - Pages and sub-pages displayed in hierarchical (indented) form (Default).
- -1 - Pages in sub-pages displayed in flat (no indent) form.
- 1 - Show only top level Pages
- 2 - Value of 2 (or greater) specifies the depth (or level) to descend in displaying Pages.
- child_of (integer)
- Displays the sub-pages of a single Page only; uses the ID for a Page as the value. Defaults to 0 (displays all Pages).
- show_date (string)
- Display creation or last modified date next to each Page. The default value is the null value (do not display dates). Valid values:
- '' - Display no date (Default).
- 'modified' - Display the date last modified.
- 'xxx' - Any value other than modified displays the date (post_date) the Page was first created. See the [[WordPress:#Sort Pages by Post Date|example]] below.
- date_format (string)
- Controls the format of the Page date set by the show_date parameter (example: "l, F j, Y"). This parameter defaults to the date format configured in your WordPress options. See WordPress:Formatting Date and Time and the date format page on the php web site.
- title_li (string)
- Set the text and style of the Page list's heading. Defaults to '__('Pages')', which displays "Pages" (the __('') is used for localization purposes). If passed a null or empty value (''), no heading is displayed, and the list will not be wrapped with <ul>, </ul> tags. See the example for [[WordPress:#Hiding or Changing the List Heading|Headings]].
- echo (boolean)
- Toggles the display of the generated list of links or return the list as an HTML text string to be used in PHP. The default value is 1 (display the generated list items). Valid values:
- 1 (true) - default
- 0 (false)
- hierarchical
- (boolean) Display sub-Pages in an indented manner below their parent or list the Pages inline. The default is true (display sub-Pages indented below the parent list item). Valid values:
- 1 (true) - default
- 0 (false)
- meta_key
- (string) Only include the Pages that have this Custom Field Key (use in conjunction with the meta_value field).
- meta_value
- (string) Only include the Pages that have this Custom Field Value (use in conjuntion with the meta_key field).
Related
This article is [[WordPress::Category:Copyedits|marked]] as in need of editing. You can help Codex by editing it.