Many if not all plugin and theme developers of the popular WordPress software are familiar with the wp_list_pages function. However very few individuals are aware of the Walker classes of WordPress and how they can be extended to customize your page lists with unique and custom functionality. The following article is going to attempt to familiarize you with the underlying Walker Classes and show a brief example of how to extend the Page Walker to output a custom sitemap.

What is the WordPress Walker Class?

To begin with the first question we need to answer is simply what is a Walker Class? In WordPress a Walker Class contains all the functionality needed to render an HTML representation of a collection of WordPress Objects. Where these objects could include Tags, Posts, Pages, Comments, and etc. To put it in plain english the walker is what creates the end HTML that will be displayed when calling a function. Without knowing it by calling the wp_list_pages function you are actually having the Walker_Page class render the final HTML based on your provided options.

A Walker class has 5 basic api methods that are used and will need to be extended based on your goal.

• walk

  This function steps through the array of elements and calls the necessary start/end_lvl and start/end_el functions for each. The basic logic is as follows:

  1. If the element is a child of the previous element it calls start_lvl.
  2. For each element call start_el followed by end_el.
  3. If the element is no longer a child element then it calls end_lvl.

• start_lvl

  concatenates the HTML element opening tag that will contain child elements to the output.

• end_lvl

  concatenates the HTML element closing tag that contains the child elements to the output.

• start_el

  concatenates the HTML representation of the object minus the closing HTML tag to the output.

• end_el

  concatenates the HTML closing tag element of the object. to the output.

Creating your own Walker

The WordPress Walkers are contained in the core WordPress files and as a developer of a theme or plugin you want to define your walker in your own code base. For example if you are a theme developer you need to define your Walker in your Theme Functions file (functions.php). This way as new versions of WordPress come out your code does not get overwritten and you are also not asking users of your theme to modify WordPress core installation files.

To create a new Walker it is easiest and usually most time effective to extend a Walker already defined by WordPress. For our example of building a Sitemap Walker we will start by extending the Walker_Page class.

class Walker_Sitemap extends Walker_page {
  // code 
}

Now that we have created our Walker_Sitemap Walker class we need to override the display functions to display our sitemap. In this example we are adding a page description that will be outputted with the page title. Instead of utilizing the WordPress functionality to get a snippet of a page I chose to output a custom meta field called description.

function start_el(&$output, $page, $depth, $args, $current_page) {
		if ( $depth )
			$indent = str_repeat("t", $depth);
		else
			$indent = '';

		extract($args, EXTR_SKIP);

		$output .= $indent . '
' . $link_before . apply_filters( 'the_title', $page->post_title, $page->ID ) . $link_after . '
';

                $description = get_post_meta($page->ID, 'description', true);

                if( ! empty( $description ) ) {
			$output .= '
' . $description . '
';
                }		

	}

As you can see in the code what we have done is simply overwritten the start_el function of the Walker_Page class with our desired HTML output. We have made it so that in addition to outputting the page link we are also outputting a div element that contains the pages description if it exists for the current page.
If wanted you could override the other Walker functions to change the container elements from a list (UL) to a DIV or any other desired HTML elements.

Using your newly created Walker

Now that you have created your Walker in your Theme Functions file the logical next step is to use it. This is done by calling the appropriate WordPress function passing in an instance of your Walker class. In our example we are outputting a sitemap which contains Pages and so we will be calling the wp_list_pages and passing in the parameter walker with an instance of Walker_Sitemap.

$sWalker = new Walker_Sitemap();
wp_list_pages( array( 'exclude' => $post->ID, 'title_li' => null, 'walker' => $sWalker ) );

You many want to note the exclusion of the current Page in the options. This is so that the sitemap page does not show up in the website’s sitemap as the visitor is already there and does not need a link to it.

Take Away

There are a million different uses that Walkers could be used for in WordPress. The next time you find yourself iterating through a collection of pages, posts, tags, or similar objects ask yourself if a Walker could save you time and effort by handling the iteration so you can focus on the output.