Languages: English • 日本語 (Add your language)
The Walker class was implemented in WordPress 2.1 to provide developers with a means to traverse tree-like data structures for the purpose of rendering HTML.
In terms of web development, a tree-like structure is an array or object with hierarchical data - such that it can be visually represented with a root element and subtrees of children.
Examples of WordPress objects with data that are structured in a "tree-like" way include navigational menus, page categories, and breadcrumbs.
Walker is an abstract class. In order to be useful the class must be extended and any necessary abstract methods defined (see "Abstract Methods" below for more).
The class itself simply "walks" through each node in a tree (e.g. an object or associative array) and executes an abstract function at each node. In order to take an action at one of these nodes, a developer must define those abstract methods within a custom child class.
Although the Walker class has many uses, one of the most common usages by developers is outputting HTML for custom menus (usually ones that have been defined using the Appearance → Menus screen in the Administration Screens).
Abstraction Note: The Walker class was created prior to PHP5 and so does not make use of PHP5's explicit abstraction keywords or features. In this case, the class and its methods are implicitly abstract (PHP4 compatible) and not explicitly abstract (PHP5 compatible). Developers are not required to implement any methods of the class, and may use or override only those methods that are needed. If you chose not to extend a specific abstract method, that method will simply do nothing.
Note that the properties of the Walker class are intended to be set by the extending class and probably should not vary over the lifetime of an instance.
'parent' and 'id'. The value of each key should be the names of the object properties that hold the parent id and item id, respectively.These methods are abstract and should be explicitly defined in the child class, as needed. Also note that $output is passed by reference, so any changes made to the variable within the following methods are automatically handled (no return, echo, or print needed).
These methods are defined by the parent class and may be called from within child methods as needed.
$max_depth argument uses 0, which will render every item in every branch, with no depth limit. You can also specify -1 to render all objects as a "flattened" single-dimensional list. Any other number will limit the depth that Walker will render in any branch. Any additional arguments passed to this method will be passed unchanged to the other methods.There are two general use-cases for the Walker class.
Some WordPress APIs and functions ( such as wp_nav_menu() ) allow developers to specify a custom Walker class as a callback. This is the most common usage of the Walker class by developers.
In this scenario, the class is automatically passed a tree of elements. When creating a custom walker for this scenario, you will generally only need to define the abstract methods needed to create the kind of structure you want. Everything else is handled automatically for you.
It is also possible to call your custom Walker classes manually. This is particularly useful for plugin developers.
In this scenario, you can initiate the walker by calling either the walk() or paged_walk() method of your child class, with the appropriate parameters.
This example would shows how you might set up the Walker's $db_fields property for handling a tree of page objects. Since we know the parent and id properties for all post objects (pages included), we just need to match those up using the Walker's $db_fields property. Like so...
<?php
class Walker_Page extends Walker {
var $db_fields = array (
'parent' => 'post_parent',
'id' => 'ID'
);
// define abstract methods here
}
This example shows one of the simplest (and most common) implementations of the walker class. In this case, the Walker will be used to generate a custom menu in combination with wp_nav_menu(). The first block shows the example Walker child class, the second block demonstrates how this class is utilized.
<?php
class Walker_Quickstart_Menu extends Walker {
// Tell Walker where to inherit it's parent and id values
var $db_fields = array(
'parent' => 'menu_item_parent',
'id' => 'db_id'
);
/**
* At the start of each element, output a <li> and <a> tag structure.
*
* Note: Menu objects include url and title properties, so we will use those.
*/
function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
$output .= sprintf( "\n<li><a href='%s'%s>%s</a></li>\n",
$item->url,
( $item->object_id === get_the_ID() ) ? ' class="current"' : '',
$item->title
);
}
}
Tip: In this case, you could choose to extend Walker_Nav_Menu instead of Walker, and then you wouldn't need to define $db_fields manually.
In order to utilize this custom walker class, you would call wp_nav_menu() (likely from within a theme file) and pass it a new instance of the custom Walker child class.
<ul>
<?php
wp_nav_menu(array(
'menu' => 2, //menu id
'walker' => new Walker_Quickstart_Menu() //use our custom walker
));
?>
</ul>
This example will cover how to initialize a custom Walker manually. In this example, our goal is to render the same menu as in the previous example. We will use the same Walker class as above, but without using the callback feature of wp_nav_menu().
<?php
// 1. Fetch the menu (we'll assume it has an id of 2)...
$menu = wp_get_nav_menu_object(2);
// 2. Create an empty $menu_items array
$menu_items = array();
// 3. Get menu objects (this is our tree structure)
if ( $menu && ! is_wp_error($menu) && empty($menu_items) ) {
$menu_items = wp_get_nav_menu_items( $menu );
}
// 4. Create a new instance of our walker...
$walk = new Walker_Quickstart_Menu();
// 5. Walk the tree and render the returned output as a one-dimensional array
print_r( $walk->walk( $menu_items, -1 ) );
Walker is located in wp-includes/class-wp-walker.php