Nav Menu Roles

FAQ

I don’t see Appearance > Menus. Where are the settings?

Block themes, such as Twenty Twenty-Five, use the Navigation block instead of classic menus, so WordPress hides Appearance > Menus.

Since version 3.0.0, the Nav Menu Roles settings are in the Site Editor instead:

1. Go to Appearance > Editor > Navigation and edit your menu.
2. Select a link or submenu.
3. In the block settings sidebar, open the “Nav Menu Roles” panel.

The settings work the same way as for classic menus. Hiding a submenu also hides all of the links inside it. Links generated automatically by the Page List block cannot be restricted.

Classic themes still use Appearance > Menus.

I don’t see the Nav Menu Roles options in Appearance > Menus?

Nav Menu Roles adds its options through the wp_nav_menu_item_custom_fields hook, which has been part of WordPress since 5.4. If a theme or plugin replaces the menu editor’s Walker and leaves that hook out, no plugin can add fields there.

To check, switch to a default theme and disable other plugins one at a time. If you find the conflict, ask its author to include the core wp_nav_menu_item_custom_fields hook. Visibility on the front end still works while the options are missing, so you can also switch themes temporarily to edit the settings, then switch back.

I’m using XYZ Membership plugin and I don’t see its “levels”?

There are apparently a few membership plugins out there that don’t use traditional WordPress roles/capabilities. My plugin will list any role registered in the traditional WordPress way. If your membership plugin is using some other system, then Nav Menu Roles won’t work with it out of the box. Since 1.3.5 I’ve added a filter called nav_menu_roles_item_visibility just before my code decides whether to show/hide a menu item. There’s also always been the nav_menu_roles filter which lets you modify the roles listed in the admin. Between these two, I believe you have enough to integrate Nav Menu Roles with any membership plugin.

Here’s an example where I’ve added a new pseudo role, creatively called “new-role”. The first function adds it to the menu item admin screen. The second function is pretty generic and won’t actually do anything because you need to supply your own logic based on the plugin you are using. Nav Menu Roles will save the new “role” info and add it to the item in an array to the $item->roles variable.

Existing Compatibility Plugins

1. Wishlists Memberships
2. WooCommerce Memberships

If your membership plugin is not listed here, you may be able to use the above bridge plugins as a template. Scroll down to the bottom of the main plugin file and you will see a section for “Helper Functions”. If you modify the 3 wrapper functions according to your membership plugin’s logic, the rest of the plugin should handle the integration with Nav Menu Roles.

Adding a new “role”

The roles in NMR are filterable distinct from the global $wp_roles. This allows for compatibility to be added between plugins that don’t use the core roles to determine access, like some membership plugins.

/**
 * Add custom roles to Nav Menu Roles menu list
 * param: $roles an array of all available roles, by default is global $wp_roles 
 * return: array
 */
function kia_new_roles( $roles ) {
  $roles['new-role-key'] = 'new-role';
  return $roles;
}
add_filter( 'nav_menu_roles', 'kia_new_roles' );

Note, if you want to add a WordPress capability the above is literally all you need. Because Nav Menu Roles checks whether a role has permission to view the menu item using current_user_can($role) you do not need to right a custom callback for thenav_menu_roles_item_visibility` filter.

In case you do need to check your visibility status against something very custom, here is how you’d go about it:

/**
  * Change visibility of each menu item
  * @param bool $visible
  * @param obj $item The complete menu object. Nav Menu Roles adds its info to the following keys {
  *         roles - Possible value: "in" (all logged in) | "out" (all logged out) | an array of specific roles, ex: [ "administrator", "editor" ]
  *         display_mode - Possible values: "show" (show if conditions met) | "hide" (hide if conditions met)
  * return boolean
  */
function kia_item_visibility( $visible, $item ) {
  if ( isset( $item->roles ) && is_array( $item->roles ) && in_array( 'new-role-key', $item->roles ) ) {
  /*  if ( // your own custom check on the current user versus 'new-role' status ) {
        $visible = true;
      } else {
        $visible = false;
    }
  */  }
  return $visible;
}
add_filter( 'nav_menu_roles_item_visibility', 'kia_item_visibility', 10, 2 );

Note that you have to generate your own if/then logic. I can’t provide free support for custom integration with another plugin. You may contact me to discuss hiring me, or I would suggest using a plugin that supports WordPress’ roles, such as Justin Tadlock’s Members.

Sort the roles alphabetically

Add the following snippet to your theme’s functions.php file:

/*
 * Sort the NMR roles
 * @param: $roles an array of all available roles with ID=>Name
 * @return: array
 */
function kia_sort_roles( $roles ) {
  if ( is_admin() ) {
    $array_lowercase = array_map( 'strtolower', $roles );
    array_multisort( $array_lowercase, SORT_ASC, SORT_STRING, $roles );
    return $roles;
  }
}
add_filter( 'nav_menu_roles', 'kia_sort_roles' );

The menu exploded? Why are all my pages displaying for logged out users?

If every item in your menu is configured to display to logged in users (either all logged in users, or by specific role), then when a logged out visitor comes to your site there are no items in the menu to display. wp_nav_menu() will then try check its fallback_cb argument… which defaults to wp_page_menu.

Therefore, if you have no items to display, WordPress will end up displaying ALL your pages!!

If you don’t want this, you must set the fallback argument to be a null string.

wp_nav_menu( array( 'theme_location' => 'primary-menu', 'fallback_cb' => '' ) );

You must do this for every effected instance of wp_nav_menu() in your theme templates. It is not possible for me to tell you where they are located, but header.php is a very common location for the main menu.

Alternatively, you could do this universally by adding the following snippet to your child theme’s function.php file or by adding it via the Code Snippets plugin:

/**
 * Disables the fallback page menu for all menus
 *
 * @param array $args Array of wp_nav_menu() arguments.
 * @return array
 */
function kia_nav_menu_args( $args ) {
  $args['fallback_cb'] = '';
  return $args;
}
add_filter( 'wp_nav_menu_args', 'kia_nav_menu_args' );

What happened to my menu roles on import/export?

The Nav Menu Roles plugin stores 1 piece of post meta to every menu item/post. This is exported just fine by the default Export tool.

However, the Import plugin only imports certain post meta for menu items. As of version 1.3, I’ve added a custom Importer to Nav Menu Roles as a work around.

How Do I Use the Custom Importer?

1. Go to Tools>Export, choose to export All Content and download the Export file
2. Go to Tools>Import on your new site and perform your normal WordPress import
3. Return to Tools>Import and this time select the Nav Menu Roles importer.
4. Use the same .xml file and perform a second import
5. No duplicate posts will be created but all menu post meta (including your Nav Menu Roles info) will be imported

Is Nav Menu Roles compatible with WPML ?

Yes. When you sync a menu with WPML’s WP Menus Sync, the translated menu items get the same role rules. A rule you change on a translated item stays when you sync again. Translated Navigation blocks keep their rules too.