模板标签/wp list pages

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

描述

以链接形式显示Pages列表。 主要用于自定义Sidebar 或者 Header, 不过,你也可以使用在其他 Templates 中。

用法

%%% ?php wp_list_pages( $args ); ? %%%

缺省

%%% ?php $args = 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' = , 'exclude_tree' = ); ? %%%

缺省值如下:

  • 显示全部页面和子页面 (不限制深度)
  • 不显示创建时间
  • 不限制使用子页面
  • 不去除某些id页面
  • 标题显示为 Pages __代表的是国际化翻译函数
  • 直接输出html代码而不是作为函数返回值代后处理
  • 不限制为某个作者
  • 页面排序为id不是标题
  • 顺序排列
  • 按层次输出 (not shown in defaults above)
  • 包含全部页面 (not shown in defaults above)
  • Not restricted to Pages with specific meta key/meta value (not shown in defaults above)
  • No Parent/Child trees excluded

Parameters

sort_column 
(string) Sorts the list of Pages in a number of different ways. The default setting is sort alphabetically by Page title.
  • tt'post_title'/tt - Sort Pages alphabetically (by title) - default
  • tt'menu_order'/tt - 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 WritePages administrative panel. See the example below.
  • tt'post_date'/tt - Sort by creation time.
  • tt'post_modified'/tt - Sort by time last modified.
  • tt'ID'/tt - Sort by numeric Page ID.
  • tt'post_author'/tt - Sort by the Page author's numeric ID.
  • tt'post_name'/tt - 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:
  • tt'asc'/tt - Sort from lowest to highest (Default).
  • tt'desc'/tt - Sort from highest to lowest.
exclude 
(string) Define a comma-separated list of Page IDs to be excluded from the list (example: tt'exclude=3,7,31'/tt). There is no default value. See the Exclude Pages from List example below.
exclude_tree 
(string) Define a comma-separated list of parent Page IDs to be excluded. Use this parameter to exclude a parent and all of that parent's child Pages. So tt'exclude_tree=5'/tt would exclude the parent Page 5, and its child (all descendant) Pages. (This parameter was added with Version 2.7)
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 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).
  • tt0/tt - Pages and sub-pages displayed in hierarchical (indented) form (Default).
  • tt-1/tt - Pages in sub-pages displayed in flat (no indent) form.
  • tt1/tt - Show only top level Pages
  • tt2/tt - 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. Note that the child_of parameter will also fetch grandchildren of the given ID, not just direct descendants. 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:
  • tt'nowiki/nowiki'/tt - Display no date (Default).
  • tt'modified'/tt - Display the date last modified.
  • tt'xxx'/tt - Any value other than modified displays the date (post_date) the Page was first created. See the example below.
date_format 
(string) Controls the format of the Page date set by the show_date parameter (example: ttnowikil, F j, Y/nowiki/tt). This parameter defaults to the date format configured in your WordPress options. See 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 tt'__('Pages')'/tt, which displays Pages (the tt__(#039;#039;)/tt is used for localization purposes). If passed a null or empty value (tt#039;#039;/tt), no heading is displayed, and the list will not be wrapped with ttlt;ul, lt;/ul/tt tags. See the example for 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:
  • tt1 (True)/tt - default
  • tt0 (False)/tt
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).
link_before 
(string) Sets the text or html that proceeds the link text inside a tag. (This parameter was added with Version 2.7)
link_after 
(string) Sets the text or html that follows the link text inside a tag. (This parameter was added with Version 2.7)
authors 
(string) Only include Pages authored by the authors in this comma-separated list of author IDs. If no authors are specified, all authors are included.
number 
(integer) Sets the number of Pages to display. This causes the SQL LIMIT value to be defined. Default to no LIMIT. (This parameter was added with Version 2.8)
offset 
(integer) Then number of Pages to pass over (or displace) before collecting the set of Pages. Default is no OFFSET. (This parameter was added with Version 2.8)

Examples

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.

preul ?php wp_list_pages('title_li='); ? /ul/pre

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 ttnowikih2/nowiki/tt:

preul

 ?php wp_list_pages('include=5,9,23title_li=h2' . __('Poetry') . '/h2' ); ?

/ul/pre

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.

preul

 ?php wp_list_pages('sort_column=menu_order'); ?

/ul/pre

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:

preul

 ?php wp_list_pages('sort_column=menu_ordertitle_li=h2' . __('Prose') . '/h2' ); ?

/ul/pre

Using the following piece of code, the Pages will display without heading and in Page Order:

preul

 ?php wp_list_pages('sort_column=menu_ordertitle_li='); ?

/ul/pre

Sort Pages by Post Date

This example displays Pages sorted by (creation) date, and shows the date next to each Page list item.

preul

 ?php wp_list_pages('sort_column=post_dateshow_date=created'); ?

/ul/pre

Exclude Pages from List

Use the exclude parameter to hide certain Pages from the list to be generated by wp_list_pages.  !-- Note: Page numbers must be in ascending order (i.e. tt'exclude=17,38'/tt and not tt'exclude=38,17'/tt). Note this isn't true at least as 2.1.3 --

preul

 ?php wp_list_pages('exclude=17,38' ); ?

/ul/pre

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. !--Note: Page numbers must be in ascending order (i.e. tt'include=7,13,26,35'/tt and not tt'include=35,7,26,13'/tt). this does not seem to be true at least at 2.1.3--

preul

 ?php wp_list_pages('include=7,13,26,35title_li=h2' . __('Pages') . '/h2' ); ?
 /ul

/pre

List Sub-Pages

Versions prior to Wordpress 2.0.1 :

Put this inside the ttthe_post()/tt section of the page.php template of your WordPress theme after ttthe_content()/tt, or put it in a copy of the page.php template that you use for pages that have sub-pages:

preul

 ?php
 global $id;
 wp_list_pages(title_li=child_of=$idshow_date=modified
 date_format=$date_format); ?

/ul/pre

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.

Wordpress 2.0.1 or newer :

NOTE: Requires an HTML tag (either ttnowikiul/nowiki/tt or ttnowikiol/nowiki/tt) even if there are no subpages. Keep this in mind if you are using css to style the list.

preul

 ?php
 wp_list_pages('title_li=child_of='.$post-ID.'show_date=modified
 date_format=$date_format'); ?
 /ul

/pre

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:

pre?php

 $children = wp_list_pages('title_li=child_of='.$post-ID.'echo=0');
 if ($children) { ?
 ul
 ?php echo $children; ?
 /ul
 ?php } ?

/pre

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.

This code will not work if placed after a widget block in the sidebar.


pre?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 } ?

/pre

As an alternative, this code in a sidebar.php, displays only top level Pages, but when viewing a Page that has children (or is a child) it displays only children of that parent.

  • When visiting main page, all top level pages are listed in the sidebar.
  • When visiting a top level page with no children, all top level pages are listed.
  • When visiting a top level page with children, just the children pages, and descendant pages, are listed.
  • When visiting a child page, just the children, and descendant pages, of that parent, are listed.

pre ?php $output = wp_list_pages('echo=0depth=1title_li=h2Top Level Pages /h2' ); if (is_page( )) {

 $page = $post-ID;
 if ($post-post_parent) {
   $page = $post-post_parent;
 }
 $children=wp_list_pages( 'echo=0child_of=' . $page . 'title_li=' );
 if ($children) {
   $output = wp_list_pages ('echo=0child_of=' . $page . 'title_li=h2Child Pages/h2');
 }

} echo $output; ? /pre

List whole subpages

This is how to get the whole subpages list

pre ?php if(!$post-post_parent){ // will display the subpages of this top level page $children = wp_list_pages(title_li=child_of=.$post-ID.echo=0); }else{ // diplays only the subpages of parent level //$children = wp_list_pages(title_li=child_of=.$post-post_parent.echo=0);

if($post-ancestors) { // now you can get the the top ID of this page // wp is putting the ids DESC, thats why the top level ID is the last one $ancestors = end($post-ancestors); $children = wp_list_pages(title_li=child_of=.$ancestors.echo=0); // you will always get the whole subpages list } }

if ($children) { ? ul ?php echo $children; ? /ul ?php } ? /pre

Markup and styling of page items

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 (ttli.pagenav/tt) and list (ttul/tt) by setting the vartitle_li/var parameter to an empty string.

All list items (ttli/tt) generated by wp_list_pages() are marked with the class ttpage_item/tt. When wp_list_pages() is called while displaying a Page, the list item for that Page is given the additional class ttcurrent_page_item/tt.

preli class=pagenav Pages [title_li]

 ul
   !-- Output starts here if 'title_li' parameter is empty --
   li class=page-item-2 page_item current_page_ancestor current_page_parent
     [parent of the current Page]
     ul
       li class=page-item-21 page_item current_page_item
         [the current Page]
       /li
     /ul
   /li
   li class=page-item-3 page_item
     [another Page]
   /li
 /ul

/li/pre

They can be styled with CSS selectors:

pre.pagenav { … } /* the outermost list item; contains whole list */ .page-item-2 { … } /* item for Page ID 2 */ .page_item { … } /* any Page item */ .current_page_item { … } /* the current Page */ .current_page_parent { … } /* parent of the current Page */ .current_page_ancestor { … } /* any ancestor of the current Page */ /pre

Notes

Changelog

  • Since: 1.5.0
  • 2.7 : Added the codelink_before/code, codelink_after/code and codeexclude_tree/code parameters.
  • 2.8 : Added the codenumber/code and codeoffset/code parameters.

Source File

ttwp_list_pages()/tt is located in onlyincludecodewp-includes/post-template.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn.

Related

wp_list_authors, wp_list_categories, wp_list_pages, wp_list_bookmarks, wp_list_comments, wp_get_archives, wp_page_menu, wp_dropdown_pages, wp_dropdown_categories, wp_dropdown_users

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude

includeonlydiv style=clear:both; background-color:#EEEEFF; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;This article is marked as in need of editing. You can help Codex by editing it./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude