wp_list_pages<\/a>()<\/code> and wp_list_categories<\/a>()<\/code>. They all extend a general Walker<\/code> class. We will extend the Walker_Nav_Menu<\/code> which is used for menus in WordPress.<\/p>\n\n\n\nBecause we extend another class we need only add the functions we wish to override. If a function does not exist in our class, WordPress will run the parent class’ (the class we extend) function instead. <\/p>\n\n\n\n
Preparation<\/h2>\n\n\n\n
You can add your walker class in your plugin files, theme’s function.php<\/code> or any PHP file included by functions.php<\/code> (for cleaner code). You start by defining your class by a name of your choosing (make sure the class name is unique, and this includes possible class names in WordPress core!) extending Walker_Nav_Menu<\/code>:<\/p>\n\n\n\nclass AWP_Menu_Walker extends Walker_Nav_Menu {\n\t\n}\n<\/pre>\n\n\n\nIn order to tell WordPress to use our walker, we define this in our wp_nav_menu<\/a>()<\/code> calls. This function is responsible for outputting a menu and you probably has at least one in your theme for the main menu.<\/p>\n\n\n\nIn the argument array to wp_nav_menu()<\/code> you add a new element with the key ‘walker’ and creates a new instance of your walker class like so:<\/p>\n\n\n\nwp_nav_menu([\n 'theme_location' => 'primary',\n 'menu_class' => 'main-menu',\n 'container' => 'nav',\n 'container_class' => 'header__main-nav',\n 'walker' => new AWP_Menu_Walker()<\/span>\n]);\n<\/pre>\n\n\n\nIf you refresh your site you should see no change. This is because our class does not override any of the parent’s functions, and thus WordPress simply runs the normal menu walker functions when outputting the menu, just like before we told it to use our walker. <\/p>\n\n\n\n
Overview of functions we can override in Walker_Nav_Menu<\/code><\/h2>\n\n\n\nThe following are functions you can add to your custom walker class to override the parenting class Walker_Nav_Menu<\/code> funtions:<\/p>\n\n\n\nThe first four are functions that are simply responsible for outputting, and they all require you to append to a string – the first parameter variable. It’s important to know that you don’t echo<\/code> anything out here, everything is supposed to be built up as a string.<\/p>\n\n\n\nstart_lvl<\/h3>\n\n\n\n
The function start_lvl<\/code> is responsible for outputting the HTML for the start of a new level. In short it should output the starting <ul><\/code>. <\/p>\n\n\n\nfunction start_lvl(&$output, $depth=0, $args=null) { }\n<\/pre>\n\n\n\nThe first parameter, $output<\/code> – passed by reference, is the string you’ll append your output to. $depth<\/code> is an integer signaling which level you’re at; 0 for top-level, 1 for direct child of top-level, and so on. $args<\/code> is an object of all arguments provided in wp_nav_menu()<\/code>.<\/p>\n\n\n\nend_lvl<\/h3>\n\n\n\n
The end_lvl<\/code> function is responsible for outputting the HTML for the end of a level. This is usually just the closing <\/ul><\/code>.<\/p>\n\n\n\nfunction end_lvl(&$output, $depth=0, $args=null) { }\n<\/pre>\n\n\n\nThe parameters are the exact same as for start_lvl<\/code> above.<\/p>\n\n\n\nstart_el<\/h3>\n\n\n\n
This function is responsible for outputting each element’s HTML. In short it should output the starting <li><\/code> and the <a><\/code> tag with the link title inside. <\/p>\n\n\n\nfunction start_el(&$output, $item, $depth=0, $args=null, $id=0) { }\n<\/pre>\n\n\n\nThe first argument, $output<\/code>, is as usual the string you’ll append the output to. The second argument, $item<\/code>, is the menu item object – and this is where you’ll fetch most of the data for outputting the menu item. If the menu link is a post menu item, you’d get the post object here. Regardless of menu type, you’ll also get some additional useful elements; such as classes<\/code>, url<\/code>, title<\/code>, and description<\/code>.<\/p>\n\n\n\nThe third argument, $depth<\/code>, is an integer telling you which level we’re at. Level 0 is top-level, 1 is direct child of top-level, and so on. The fourth argument, $args<\/code>, is an object of all arguments provided to wp_nav_menu()<\/code>. The fifth parameter, $id<\/code>, is the current menu item ID.<\/p>\n\n\n\nend_el<\/h3>\n\n\n\n
The end_el<\/code> function is responsible for outputting the closing of an element. Usually it would just output the <\/li><\/code> tag.<\/p>\n\n\n\nfunction end_el(&$output, $item, $depth=0, $args=null) { }\n<\/pre>\n\n\n\nThe arguments for end_el<\/code> are the same as start_el<\/code> above except that the function doesn’t have the fifth parameter, $id<\/code>. <\/p>\n\n\n\ndisplay_element<\/h3>\n\n\n\n
The function display_element<\/code> is an inherited function from the general Walker<\/code> class, and is the function responsible for traversing. This is the function that calls all of the above functions in turn. <\/p>\n\n\n\nI’m including this here because in some cases, for example if you want to prevent traversing a whole branch, you’d use this function for that.<\/p>\n\n\n\n
function display_element($element, &$children_elements, $max_depth, $depth, $args, &$output) { }\n<\/pre>\n\n\n\nThe first argument, $element<\/code>, is the menu item object – this is what is passed down as $item<\/code> in the above functions. The second argument, $children_elements<\/code> – passed by reference, contains all child elements this function will traverse. $max_depth<\/code>, the third argument, is an integer that signals how deep we should traverse, and the fourth argument, $depth<\/code>, is the depth we’re currently at. The fifth argument, $args<\/code>, is the arguments passed to the function that called the walker (for menus it would be the arguments provided to wp_nav_menu()<\/code>), and the final argument, $output<\/code> – passed by reference, is the output which is passed down as first argument in all of the above functions.<\/p>\n\n\n\nModifying the output of each element<\/h2>\n\n\n\n
In the overview above you should see that the function start_el()<\/code> is the one responsible for outputting the HTML for a single menu element. Let’s start by overriding this function in our walker class with a simple example.<\/p>\n\n\n\nExample: preventing adding links for ‘#’ elements<\/h3>\n\n\n\n
Let’s make sure that any ‘#<\/code>‘ links gets a <span><\/code> element instead of a link tag, to avoid refreshing the page. <\/p>\n\n\n\nclass AWP_Menu_Walker extends Walker_Nav_Menu {\n\tfunction start_el(&$output, $item, $depth=0, $args=[], $id=0) {\n\t\t$output .= \"<li class='\" . implode(\" \", $item->classes) . \"'>\";\n\n\t\tif ($item->url && $item->url != '#') {\n\t\t\t$output .= '<a href=\"' . $item->url . '\">';\n\t\t} else {\n\t\t\t$output .= '<span>';\n\t\t}\n\n\t\t$output .= $item->title;\n\n\t\tif ($item->url && $item->url != '#') {\n\t\t\t$output .= '<\/a>';\n\t\t} else {\n\t\t\t$output .= '<\/span>';\n\t\t}\n\t}\n}\n<\/pre>\n\n\n\nWe’ll start the element by appending a <li><\/code> tag to $output<\/code>. We want to make sure that WordPress’ default classes (for example ‘menu-item’, ‘menu-item-has-children’ etc), as well as classes entered manually in Menu editor gets added to our list element. We glue the classes provided as an array in $item->classes<\/code> using the PHP function implode<\/a>()<\/code> separating each element with a space.<\/p>\n\n\n\nAt line #5-9 and #13-17 we handle the conditional output of the wrapping element. We output a <a><\/code> tag, unless the element’s URL is ‘#<\/code>‘ in which case we provide a <span><\/code> tag instead. At line #11 we simply output the link’s text, which resides in $item->title<\/code>. <\/p>\n\n\n\nThis is all we need for making sure all menu elements that has ‘#<\/code>‘ as URL isn’t clickable!<\/p>\n\n\n\nIf you are doing this in a styled theme, keep in mind that you might lose some styling if the theme has styled the <a><\/code> tag directly. You can solve this by changing the styling and possibly adding a class to the span element.<\/p>\n\n\n\nExample: displaying menu item descriptions<\/h3>\n\n\n\n
As an example another thing you can do here is outputting the menu description. This exists, but is not activated as default. In WordPress Menu editor you need to click “Screen Options” in the top right, and check off for showing “Description”:<\/p>\n\n\n\n
![\"\"](\"https:\/\/awhitepixel.com\/wp-content\/uploads\/2019\/12\/wp-menu-screen-options-1024x387.png\")
<\/figure><\/div>\n\n\n\n![\"\"](\"https:\/\/awhitepixel.com\/wp-content\/uploads\/2019\/12\/wp-menu-carets.png\"){kind=icon}