Cheat Sheet: Wordpress link-listing functions
One of the benefits of using a CMS like Wordpress is the ability to build navigation links dynamically in addition to displaying content (like blog posts) dynamically. With dynamic navigation, adding something like a page or category in your Wordpress control panel will do two things: (1) as expected, it will publish that new content and make it available at a URL, and (2) it will add a hyperlink to your navigation that links to that new URL.
wp_list_pages()
The Starter Kit theme is already using wp_list_pages() (look inside nav.php). Like many PHP functions, wp_list_pages() accepts a number of arguments that you can specify to control the output. What may be new to you is that rather than accept these paramaters as a series of comma-separated values, the function requires an associative array. Often we store this array in a variable called $args, then pass it in when we run the function. Here’s the canonical example showing some of the most common options:
<?php
// store our options in an associative array called $args
// this is a regular associative array -- the line breaks just make it easier to read
$args = array(
'depth' => 0,
'show_date' => '',
'date_format' => get_option('date_format'),
'child_of' => 0,
'exclude' => '3,5' // don't list pages with IDs 3 and 5
'include' => '',
'title_li' => '', // you must specify an empty string like this to keep Wordpress from inseting "Pages: " before your list. annyoing.
'echo' => 1,
'authors' => '',
'sort_column' => 'menu_order, post_title', //we can control the output order by editing Page Attributes > Order in each page. Or we could just set this as post_title and have it sort alphabetically
'link_before' => '',
'link_after' => '',
'walker' => '' );
// now run the function, passing in $args as the argument
// Wordpress will wrap each link in an <li> tag and attach a bunch of classes (which it thinks might be useful to each <li>)
wp_list_pages($args);
?>
Note that all of these values have defaults set, and so you can safely leave them out of your arguments array if you don’t need to alter them (this is the advantage of collecting all the options in an associative array). Check out the defaults by reading about wp_list_pages in the Wordpress Codex.
Here’s some example output that wp_list_pages() might produce:
<li class="page_item page-item-126"><a href="http://example.com/new-page/">New page</a></li>
<li class="page_item page-item-5"><a href="http://example.com/about/">About</a></li>
<li class="page_item page-item-7"><a href="http://example.com/contact/">Contact</a></li>
<li class="page_item page-item-30"><a href="http://example.com/colophon/">Colophon</a></li>
Since this is just a series of <li> tasg with links inside them, it’s up to you to make sure you wrap them in a <ul> and perhaps a <nav> tag in your template.
wp_list_categories()
As we reviewed last class, category pages are those pages that looks omething like http://example.com/category/news and are controlled by the category.php file.
Like wp_list_pages(), wp_list_categories() simply outputs links. It’s without having to write them manually. If in the future you add a category to your blog, wp_list_categories() will update accordingly.
Here’s an example with some of the common options in use:
$args = array(
'show_option_all' => '',
'orderby' => 'name',
'order' => 'ASC',
'show_last_update' => 0,
'style' => 'list', // setting to 'none' would list them without li tags but with <br /> tags after each one
'show_count' => 1, // lets show the number of posts in each category
'hide_empty' => 1,
'use_desc_for_title' => 1,
'child_of' => 0,
'exclude' => '',
'include' => '',
'hierarchical' => false, // don't list sub-categories
'title_li' => '', // no heading please
'show_option_none' => '',
'echo' => 1,
'depth' => 0,
'current_category' => 0,
'pad_counts' => 0 );
// no run the function
wp_list_categories( $args );
This might produce output like this:
<li class="cat-item cat-item-8"><a href="http://watkinswebdev.com/jmuspratt/demo/category/essays/" title="Longer format writing on design, the web, and pineapples.">Essays</a> (2)</li>
<li class="cat-item cat-item-1"><a href="http://watkinswebdev.com/jmuspratt/demo/category/news/" title="Short updates on current events.">News</a> (12)</li>
<li class="cat-item cat-item-10"><a href="http://watkinswebdev.com/jmuspratt/demo/category/quick-links/" title="View all posts filed under Quick Links">Quick Links</a> (2)</li>
Once again, make sure that this output is wrapped in <ul> tags to keep your HTML valid.