Class Reference/Walker
Role of Walker
The Walker class provides developers with methods and "abstract" methods needed to easily traverse any complex (tree-like) objects for the purpose of rendering HTML.
Usage
Although the Walker class has many uses, one of the most common usages by developers is outputting HTML for highly customized menus (usually ones that have been defined using the WordPress Admin's Menus Screen).
This class is not used by itself, but must be extended. Many of it's methods are abstract* and therefore must be overridden by the developer.
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 it's 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 classes that are needed.
Methods & 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.
Also the method definitions of start_el, end_el, start_lvl, end_lvl only list one argument but are called using call_user_func_array and it is these arguments that are listed.
Properties
- $tree_type
- 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'.
- $db_fields
- An array with keys: parent and id. The value for these keys should be the name of the property in the objects walker will be applied to holding the id of the current object and parent object respectively.
- $max_pages
- The maximum number of pages walked by the paged walker.
Abstract Methods
These methods should be defined in the child class, as needed.
- start_lvl( &$output, $depth, $args )
- This method is abstract and must be defined by the developer in a child class. This method is run when the walker reaches a new "branch" in a tree structure. Generally, this method is used to output the opening tag of an HTML element (such as <ol>, <ul>, or <div>).
- end_lvl( &$output, $depth, $args )
- This method is abstract and must be defined by the developer in a child class. This method is run when the walker reaches the end of a "branch" in a tree structure. Generally, this method is used to output the closing tag of an HTML element (such as </ol>, </ul>, or </div>).
- start_el( &$output, $element, $depth, $args )
- This method is abstract. Classes extending Walker should define this function to return $output concatenated with the markup starting an element.
- end_el( &$output, $element, $depth, $args )
- This method is abstract. Classes extending Walker should define this function to return $output concatenated with the markup ending an element. Note that elements are not ended until after all of their children have been added.
Public Methods
These methods are defined by the parent class and may be called from within child methods as needed.
- walk($elements, $max_depth)
- Takes an array of elements ordered so that children occur below their parents and an integer $to_depth. A non-zero $to_depth caps the maximum depth to which the method will descend. If $to_depth is -1 the array is processed as if it was flat (no element is the child of another). Any additional arguments passed to walk will be passed unchanged to the other methods walk calls. walk steps through the array $elements one by one. Each time an element is the child of the prior element walk calls start_lvl. Every time an element is processed walk calls start_el and then end_el. Each time an element is no longer below one of the current parents walk calls end_lvl.
- paged_walk( $elements, $max_depth, $page_num, $per_page )
- Given an array of hierarchical elements, the maximum depth, a specific page number, and number of elements per page, this function first determines all top level root elements belonging to that page, then lists them and all of their children in hierarchical order.
- get_number_of_root_elements( $elements )
- Returns the number of elements in a given object.
- unset_children( $e, &$children_elements )
- Unsets all the children for a given top-level element.
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.
Examples
Property Usage Example
class Walker_Page extends Walker {
var $tree_type = 'page';
var $db_fields = array (
'parent' => 'post_parent',
'id' => 'ID'
);
// OTHER CODE...
}
Thus the Walker_Page class expects that if page is a page object then page->post_parent will give the id of that page's parent and page->ID will give the id of that page.
Version
The Walker class was implemented in WordPress 2.1.
External Resources
Related
