WordPress walker documentation


Updated on: September 15, 2020 in Wordpress by

Walker

A class for displaying various tree-like structures.

Description #Description

Extend the Walker class to use it, see examples below. Child classes do not need to implement all of the abstract methods in the class. The child only needs to implement the methods that are needed.


Top ↑

More Information #More Information

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.

Tree-Like Structures #Tree-Like Structures

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.

Top ↑

Role of Walker #Role ofWalker

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.

Top ↑

Methods & Properties #Methods & Properties

Top ↑

Properties #Properties

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.$db_fieldsRequired. Because Walker can take any type of tree object, you need to specify what object properties the Walker class should treat as parent id and item id (usually these are the names of database fields, hence the property name). This property must be an associative array with two keys: '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.$tree_typeOptional. The Walker class itself makes no use of this value, although it may be useful to developers. Internally, WordPress’s own extended Walker classes will set this to values like ‘category’ or ‘page’.$max_pagesOptional. The maximum number of pages walked by the paged walker.

Top ↑

Abstract Methods #Abstract Methods

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).start_lvl( &$output, $depth = 0, $args = array() )“Start Level”. This method is run when the walker reaches the start of a new “branch” in the tree structure. Generally, this method is used to add the opening tag of a container HTML element (such as <ol>, <ul>, or <div>) to $output.end_lvl( &$output, $depth = 0, $args = array() )“End Level”. This method is run when the walker reaches the end of a “branch” in the tree structure. Generally, this method is used to add the closing tag of a container HTML element (such as </ol>, </ul>, or </div>) to $output.start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 )“Start Element”. Generally, this method is used to add the opening HTML tag for a single tree item (such as <li>, <span>, or <a>) to $output.end_el( &$output, $object, $depth = 0, $args = array() )“End Element”. Generally, this method is used to add any closing HTML tag for a single tree item (such as </li>, </span>, or </a>) to $output. Note that elements are not ended until after all of their children have been added.

Top ↑

Public Methods #Public Methods

These methods are defined by the parent class and may be called from within child methods as needed.walk($elements, $max_depth)This method can be used to initialize the Walker class. It takes an array of elements ordered so that children occur below their parents. The $max_depth parameter is an integer that specifies how deep into the tree structure the walker should render. By default, the $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.paged_walk( $elements, $max_depth, $page_num, $per_page )This method can be used to initialize the Walker class. This function works like walk() but allows for pagination. $page_num specifies the current page to render while $per_page specifies the number of items to show per page. Any additional arguments passed to this method will be passed unchanged to the other methods.get_number_of_root_elements( $elements )Counts the number of top-level items (no children or descendants) in the provided array, and returns that count.unset_children( $e, &$children_elements )Removes all the children for a specified top-level element.

Top ↑

Private Methods #Private Methods

display_element( $element, &$children_elements, $max_depth, $depth=0, $args, &$output )This method should be considered private and should not be called directly. Use walk() instead.

Top ↑

Usage #Usage

There are two general use-cases for the Walker class.

Top ↑

Usage as a Callback #Usage as a Callback

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.

Top ↑

Custom Usage #Custom Usage

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.