Codex tools: Log in / create account
The Template Tag, wp_list_pages(), displays a list of WordPress Pages as links. It is often used to customize the Sidebar or Header, but may be used in other Templates as well.
This Template Tag is available for WordPress versions 1.5 and newer.
<?php wp_list_pages('arguments'); ?>
$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:
wp_list_pages();
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>
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>
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>
Use the exclude parameter to hide certain Pages from the list to be generated by wp_list_pages.
<ul>
<?php wp_list_pages('exclude=17,38' ); ?>
</ul>
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>
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;
wp_list_pages("title_li=&child_of=$id&show_date=modified
&date_format=$date_format"); ?>
</ul>
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 instead.
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 } ?>
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.
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 } ?>
By default, wp_list_pages() generates a nested, unordered list of 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 { ... }
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.
bloginfo,
bloginfo_rss,
get_bloginfo,
get_bloginfo_rss,
wp_title,
get_archives,
wp_get_archives,
get_calendar,
get_posts,
wp_list_pages,
wp_dropdown_pages,
wp_loginout,
wp_register,
query_posts,
rss_enclosure
This article is marked as in need of editing. You can help Codex by editing it.