Repository files navigation

Hate the WordPress NavWalker?Me too.

Navi is a developer-friendly alternative to the NavWalker. Easily build your WordPress menus using an iterable object inside of a template/view.

• PHP >= 8.0

Install via Composer:

$ composer require log1x/navi

Download thelatest release.zip and install intowp-content/plugins.

Building your menu can be done by passing your menu location toNavi::make()->build():

useLog1x\Navi\Navi;$menu = Navi::make()->build('primary_navigation');

By default,build() usesprimary_navigation if no menu location is specified.

Retrieving an array of menu items can be done usingall():

if ($menu->isNotEmpty()) {return$menu->all();}

By default, Navi removes the default WordPress classes from menu items such asmenu-item andcurrent-menu-item giving you full control over your menu markup while still passing through custom classes.

If you would like these classes to be included on your menu items, you may callwithDefaultClasses() before building your menu:

$menu = Navi::make()->withDefaultClasses()->build();

In some situations, plugins may add their own classes to menu items. If you would like to prevent these classes from being added, you may pass an array of partial strings towithoutClasses() match against when building.

$menu = Navi::make()->withoutClasses(['shop-'])->build();

When building the navigation menu, Navi retains the menu object and makes it available using theget() method.

By default,get() returns the rawwp_get_nav_menu_object() allowing you to access it directly.

$menu->get()->name;

Optionally, you may pass akey anddefault to call a specific object key with a fallback when the value is blank:

$menu->get('name','My menu title');

If your menu item is linked to a page object (e.g. not a custom link) – you can retrieve the ID of the page using theobjectId attribute.

Below is an example of getting the post type of the current menu item:

$type =get_post_type($item->objectId)

In a scenario where you need to access a custom field attached directly to your menu item – you can retrieve the ID of the menu item using theid attribute.

Below we'll get a label override field attached to our menuusing ACF – falling back to the default menu label if the field is empty.

$label =get_field('custom_menu_label',$item->id) ?:$item->label;

If you are using Navi alongsideAcorn (e.g. Sage), you may generate a usable view component using Acorn's CLI:

$ wp acorn navi:make Menu

Once generated, you may use theview component in an existing view like so:

<x-menu name="footer_navigation" />

To list all registered locations and their assigned menus, you can use the list command:

$ wp acorn navi:list

When callingbuild(), Navi will retrieve the WordPress navigation menu assigned to the passed location and build out an array containing the menu items.

An example of the menu output can be seen below:

array [5 => {    +"active": true    +"activeAncestor": false    +"activeParent": false    +"classes":"example"    +"dbId":5    +"description": false    +"id":5    +"label":"Home"    +"object":"page"    +"objectId":"99"    +"parent": false    +"slug":"home"    +"target":"_blank"    +"title": false    +"type":"post_type"    +"url":"https://sage.test/"    +"xfn": false    +"order":1    +"parentObjectId": false    +"children": false  }6 => {    +"active": false    +"activeAncestor": false    +"activeParent": false    +"classes": false    +"dbId":6    +"description": false    +"id":6    +"label":"Sample Page"    +"object":"page"    +"objectId":"100"    +"parent": false    +"slug":"sample-page"    +"target": false    +"title": false    +"type":"post_type"    +"url":"https://sage.test/sample-page/"    +"xfn": false    +"order":2    +"parentObjectId": false    +"children": array [7 => {        +"active": false        +"activeAncestor": false        +"activeParent": false        +"classes": false        +"dbId":7        +"description": false        +"id":7        +"label":"Example"        +"object":"custom"        +"objectId":"101"        +"parent":6        +"slug":"example"        +"target": false        +"title": false        +"type":"custom"        +"url": "#"        +"xfn": false        +"order":3        +"parentObjectId":100        +"children": array [          ...        ]      }    ]  }]

If you discover a bug in Navi, pleaseopen an issue.

Contributing whether it be through PRs, reporting an issue, or suggesting an idea is encouraged and appreciated.

Navi is provided under theMIT License.