Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Talk:Function Reference/wp list pages

This is awesome, but it needs more. Can this be used as a sitemap or more specific list which can be narrowed down with the parameters, like with categories or specific dates? And how specifically can this be used? For those of us who would like to run it through some paces, we need a little more info.

Lorelle 03:00, 25 Jan 2005 (GMT)
You can use this to created a nested unordered list (ul) of your pages, with the parameters given. Not sure what you mean by category. Could you try various things out and document the results ? :) I am not too sure what youa re looking for. Yes, it is possible to do funky stuff with the parameters that are listed. Remember that all this can change before 1.5 is released. Please leave a note for any specific information you need. Running through all the possible ways the tags can be used is difficult due to the large number of permutations and combinations in which the parameters can be used, and so the parameters are defined, for clarity and conciseness. The examples are only potshots at frequently-used combinations of parameters.
Carthik 06:17, 25 Jan 2005 (GMT)

By category, I mean a list of links in a specific category re: wp_list_pages('category=1') or something like that. When I get back to my office and off the road in another two weeks, I'll give these a try and see what happens. But if anyone else can come up with some tries before that - help is welcome!

Lorelle 16:57, 2 Feb 2005 (GMT)

The categories feature you mention isn't available with wp_list_pages. A good question though. wp_list_pages lists only those Pages created in Write->Write Pages (Write Page SubPanel). It doesn't know anything about other pages. This, again, is the difference between web pages and WordPress Pages (note capitalization). In the sense of "web page", page refers generically to any site on the web. In the sense of "WordPress Pages", Page refers to a very specific feature available in WP 1.3+.
To get a list of Links (Links as in Blogroll) from a specific category, try Template Tags/wp_get_links. This can display all the links from a specific Link Category. A list of links (links as in <a href="">) to all of the Posts in a specific Category is trickier. You'll need The Loop or some plugin. I imagine the forums have some clever solution. --MDAWaffe
I'll look into the wp_get_links, though all I can see there is how to get links from the Link Manager not categories...but I'll double check next.
Regarding this nutso thing of page and Page, I'm not sure how the group has decided to tell the difference between the two as a united front other than capitalization, but everywhere we have a Page tag, the difference between a page tag and Page tag needs to be better emphasized. Possibly putting it in a link every time to the Page explanation page? I looked at it several times before I got the clue that this wasn't for normal pages.
Lorelle 01:05, 6 Feb 2005 (GMT)
I wasn't clear. Sorry. wp_get_links gets links from Link Categories (one term: two words). In other words, the Link Manager. To get links to Categories (as in Post Categories) use Template Tags/wp_list_cats. To get links to Posts from some category... you'll need a clever Loop or a nice plugin. --MDAWaffe 10:57, 10 Feb 2005 (GMT)

Ah, here is some confusion. The example is:

Example 2

Displays no heading for list.

<?php wp_list_pages('title_li= '); ?> 

Example 3

Displays no heading for list, and list is not wrapped in <li><ul>, </ul></li> tags.

<?php wp_list_pages('title_li='); ?>

But I don't see a real change between the two example codes. So will php wp_listpages('title_li= ') give us no headings and the second one, with no space between the li and the apostrophe, give us a list without the li and ul? They basically look the same except for the space. Is something left out?

Lorelle 17:01, 2 Feb 2005 (GMT)

Thanks for clarifying the space in the tag.

Lorelle 04:57, 4 Feb 2005 (GMT)

Sure thing. Actually I forgot to look at the Discussion Page before editing (oops!) and didn't see your comment. Guess we were both thinking along the same lines :) --MDAWaffe 05:48, 4 Feb 2005 (GMT)

Testing this page in the real world

I've been working on using this tag on my test site and I'm having some problems with some of the examples. Basically, it takes a lot of work to understand some of them. If they showed what the results might look like before the actual code, that would help.

I learned that the title_li= must be the LAST argument on the list. If you put it in the middle, it won't work right. Has anyone tried it in the middle of the arguments and had it work?

I'm having a heck of a time with the fact that the UL is embedded along with the LI. From what I understand on other similar tags, and as outlined in the example, the tag is put in place surrounded by opening and closing UL. This implies that the code results in just LI tags. Yet, when I do that, and include another tag above it, like this:

/* beginning of sidebar links */
   <li><?php _e('Connect the Dots'); ?>
      <ul id="pageslist">
         <li><a title="Lorelle's Blog " href="index.php?cat=7">Blog</a></li>
         <?php wp_list_pages('exclude=497&depth=1&&sort_column=menu_order&title_li= '); ?>
	<li id="related"><?php _e('Related Articles'); ?>
               <ul><?php related_posts(10, 10, '<li>', '</li>', '', '', false, false); ?>

Instead of all of the pages including the single link under one title, I get something that looks like this:

  • Connect the Dots
    • Lorelle's Blog
      • About Us
      • What's New
      • Contact Us
    • Related Articles

This is a prime example of how this tag will be used and if we are explaining this to folks, we need to explain that this tag looks and works differently from the other tags that list without their own UL. It works this way with the related_posts tag shown in the code above. Is there an arguments that determines if the UL is used or not?

Just trying to make this article as helpful as possible for the real world use. Lorelle 20:00, 23 Feb 2005 (GMT)

Anyone? Lorelle 02:28, 5 Mar 2005 (UTC)
You want to use the example that does not wrap the output in <li><ul>.
/* beginning of sidebar links */
   <li><?php _e('Connect the Dots'); ?>
      <ul id="pageslist">
         <li><a title="Lorelle's Blog " href="index.php?cat=7">Blog</a></li>
         <?php wp_list_pages('exclude=497&depth=1&sort_column=menu_order&title_li='); ?>
	<li id="related"><?php _e('Related Articles'); ?>
               <ul><?php related_posts(10, 10, '<li>', '</li>', '', '', false, false); ?>
In the above, I've taken out the space after title_li=. I've also removed an extra & that wasn't doing anything (nor was it hurting anything).
Yes, you can have title_li in the middle:
wp_list_pages('exclude=497&depth=1&title_li= &sort_column=menu_order');
Is this not clear in the article? --MDAWaffe 07:17, 5 Mar 2005 (UTC)
It may be clear but I tried it from different angles in the "real world" and couldn't get it to work unless the title_li was on the end. And my solution to the above problem turned out to be removing the UL/LI reference but it only works because I don't have any indentions in that layout. If I did I'd actually have:
  • Connect the Dots
    • Lorelle's Blog

About Us
What's New
Contact Us

  • Related Articles
If anyone tries this, we'll hear about it on the forums.
And thanks for the fixes. I looked for links within the article but obviously hadn't scrolled down far enough.
Lorelle 18:52, 5 Mar 2005 (UTC)

more control over separators?

In other tags, like wp_list_cats(), you can control the separators between the different items, like instead of having LI tags, you can choose to have "/" or "+" or whatever as a separator. Is it possible to do the same with wp_list_pages? (and i am not talking about just the header)

Contextual page list

To get a contextual listing of subpages for the current page from within the Loop:

<?php if (is_page()) { ?>
             global $id; 
             wp_list_pages('child_of=' . $id . '&title_li=');
<?php } ?>

I'm using this to put a listing of sub-pages in a sidebar.

--Eads 17:11, 5 May 2005 (UTC)

  1. Could this be included on the main article?
  2. Is there a way that child_of option could be expanded so that siblings can be listed and appear on the child pages? then it can be used in a persistent menu. It seems requested several times, and one may not always need the complexity of the fold-pages plugin. example Qs from support:

Nearlythere 17:21, 13 Jul 2005 (UTC)


sort_column=time_modifed/created no longer works in 1.5.1. I think post_modified and post_date work, but I'm not 100% positive they'll sort correctly. --MDAWaffe - Talk 04:20, 10 May 2005 (UTC)

Using wp_list_pages twice in one template produces problems

I am trying to use the wp_list_pages tag twice within the same template to produce to distinct lists of pages under different titles. Below is the code I am using:

<?php wp_list_pages('exclude=2,3,4,5,6,7,8,9,10,11,12,13&title_li=' ); ?>

<?php wp_list_pages('exclude=31&title_li=' ); ?>

[NOTE: I have excluded the titles to isolate the problem]

The problem is that both tags generate the list of pages indicated for the first tag. If I switch the order of the tags, then the list of pages generated for both tags becomes the pages indicated in what was the second tag but is now the first.

Anyone have a thought on how to fix this?


Support questions are best handled on the WordPress support forums, but this is a known problem I believe resolved in the most recent versions of WordPress. -Kaf 18:36, 3 Jun 2005 (UTC)

Exclude List

It appears that the comment on the doc page regarding the requirement of having the exclude page id numbers in ascending order i.e. (1,2,3,4,10,20,30,40) as opposed to having a random order i.e. (4,40,2,1,20,3,10,30) is actually not an issue. Having looked at the source it appears the SQL that is generated is simply creating AND ID <> [ID] over and over again. This requirement seems to be unnecessary and I think this should be removed from the documentation.

Comments? -Tim Gallagher 29 Jan 2007

Multiple Parameters

Thankfully, I found it looking through the sections here, but a mention of how to use multiple parameters would be useful. I was attempting to use commas as I thought had been suggested.

I had tried to use

 <?php wp_list_pages('exclude=34' 'title_li=<h2>' . __('Other Pages'). '</h2>'); ?> 

which resulted in the title being ignored, or when transposed, the exclusion was ignored. I only found here that I have to use & to connect parameters, giving me

<?php wp_list_pages('exclude=35&title_li=<h2>' . __('Other Pages'). '</h2>'); ?>

I'd have saved a solid hour if there was a mention of that in the article, it seems like there should be, it's a critical piece of information.--ZekeDMS

Has the default sort column changed?

It appears to me that in 2.5.1 and 2.6 (and perhaps earlier) the default sort order is not 'title', but 'menu_order'.

For 2.6 see http://wp0806.sgtst.com/ with the default theme and the list of pages in the sidebar generated with the code:


and the list of pages shown as:

   * Page #10
   * Another #20
   * About #30

where the numbers above are the page orders assigned in the Write > Page panel. But see http://wordpress.org/support/topic/190220?replies=4 where this is not working this way for a newbie.

--Converting2wp 17:36, 22 July 2008 (UTC)