This series on Getting the Most Out of Your WordPress Template Tags is meant to help you speed up and, even more so, improve your use of WordPress Template Tags.

The following tag is suggested (and provided) for use in WordPress blogs in order to generate a list of the pages of a blog:

<?php wp_list_pages(); ?>

Of course it is possible to manually list and link each page of your blog. But this is not ideal. Today we look at the wp_list_pages tag.

The Basics

There are a number of ways that I’m used to seeing wp_list_pages used. Now just because we’re used to seeing them doesn’t mean they are the best ways. Let’s take a look at how it could be, what the result turns out to be, and then look to what we want to begin doing.

The (Usually) Standard

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

The above code produces a very simple list without any header. Without title_li= in the parenthesis the list would print with an <h2> that says Pages. Since we are looking to use this tag for our main menu, we don’t want any header. So this is the most basic way to begin, and it will return the following:

Note: The tag must be wrapped in <ul> </ul> in order to validate. The function does not generate the wrapping <ul> tags.

The Exclude / Include Argument

<?php wp_list_pages('title_li=&include=1,2,4'); ?>

In some cases we run across themes which do not handle many pages in the main menu. One way of managing this issue is to drop include= into the template tag. In the example above, only pages with the IDs 1, 2 and 4 will be included in the main menu. All others will still exist, but they won’t be listed.

Another way of dealing with having too many pages to fit into your theme’s main menu area is to use the exclude argument. This performs the opposite function of the include argument. Whatever post IDs you list will be excluded from the list.

<?php wp_list_pages('title_li=&exclude=1,2,4'); ?>

In the above example pages 1, 2 and 4 would not be included in the list of pages.

Note: The ampersand (&) must be used in between arguments in a template tag.

Little-Used Arguments

The three arguments listed above (title_li, include, exclude) are fairly basic. Let’s look at some stuff that isn’t used often, and see what sort of things there are to gain from them.

List Depth

Use this one for dealing with Subpages. Let’s say you have a theme that doesn’t support Subpages in a menu very well. Take UrbanGrunge, for example, a recent addition to the WordPress Theme Viewer. In the screenshot below you can see that our Subpages don’t look great when they’re used in the UrbanGrunge theme.

As you can see, the theme pushes our Subpage down a level. It looks odd, not to mention the fact that it makes our last few menu items unreadable. This author didn’t prepare the theme for Subpage. Let’s fix it.

The current code:

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

With our addition:

<?php wp_list_pages('title_li=&depth=1'); ?>

Our addition, depth=1, tells the tag to only generate the first level of menu items. All subpages are ignored.

This fixes the major problems in our menu. With a little more tweaking (probably by excluding a page or two) this menu would look great!

List Order

I use this one constantly. For anyone who has ever wanted to list their menu in a very specific manner (a good thing to do) this argument is made for just that. While there are a number of options for this argument, the one most useful to us is menu_order.

<?php wp_list_pages ('title_li= &list_column=menu_order'); ?>

This sets the menu order to line up with the order of the pages that you determine. How do you determine the order yourself, you ask? You enter them on the Dashboard under Write / Edit Page:

The pages will order from lowest to highest: 1, 2, 3, 4, etc.

Suggestions for Developers

I would suggest a default setting of the following:

<?php wp_list_pages('title_li=&depth=1&sort_column=menu_order'); ?>

This meets a large number of users’ default needs. Most user don’t use headings for their page listings, and most would prefer to order their page items a certain way themselves. Cutting down the depth to 1 just lowers the possibility of a user being disappointed with your theme as soon as they activate it.

Notes:

• Further information on this tag can be found in its page of the WordPress Codex.

Did you enjoy this post? Then it might be worth your time to subscribe via RSS using your Feedreader or, if you prefer, via email.