1. Documentation
  2. API
  3. Backend
  4. Classes
  5. NavigationManager

Backend\Classes\NavigationManager

Source: ~/modules/backend/classes/NavigationManager.php

Manages the backend navigation.

Protected properties

protected array $callbacks

Cache of registration callbacks.

protected array $items

List of registered items.

protected $contextSidenavPartials

protected $contextOwner

protected $contextMainMenuItemCode

protected $contextSideMenuItemCode

protected static $mainItemDefaults

protected static $sideItemDefaults

protected System\Classes\PluginManager $pluginManager

protected static $instance

Public methods

public void __clone()

public void __wakeup()

public void addMainMenuItem(string $owner, string $code, array $definitions)

Dynamically add a single main menu item

Parameters
  • string $owner
  • string $code
  • array $definitions

public void addMainMenuItems(string $owner, array $definitions)

Dynamically add an array of main menu items

Parameters
  • string $owner
  • array $definitions

public void addSideMenuItem(string $owner, string $code, string $sideCode, array $definitions)

Dynamically add a single side menu item

Parameters
  • string $owner
  • string $code
  • string $sideCode
  • array $definitions

public void addSideMenuItems(string $owner, string $code, array $definitions)

Dynamically add an array of side menu items

Parameters
  • string $owner
  • string $code
  • array $definitions

public static void forgetInstance()

Forget this singleton's instance if it exists

public void getActiveMainMenuItem()

Returns the currently active main menu item

public mixed getContext()

Returns information about the current navigation context.

public mixed getContextSidenavPartial(string $owner, string $mainMenuItemCode)

Returns the side navigation partial for a specific main menu previously registered with the registerContextSidenavPartial() method.

Parameters
  • string $owner - Specifies the navigation owner in the format Vendor/Module.
  • string $mainMenuItemCode - Specifies the main menu item code.

public static void instance()

Create a new instance of this singleton.

public boolean isMainMenuItemActive(mixed $item)

Determines if a main menu item is active.

Parameters
  • mixed $item - Specifies the item object.

public boolean isSideMenuItemActive(mixed $item)

Determines if a side menu item is active.

Parameters
  • mixed $item - Specifies the item object.

public array listMainMenuItems()

Returns a list of the main menu items.

public void listSideMenuItems($owner=NULL, $code=NULL)

Returns a list of side menu items for the currently active main menu item. The currently active main menu item is set with the setContext methods.

Parameters
  • $owner
  • $code

public void registerCallback(callable $callback)

Registers a callback function that defines menu items. The callback function should register menu items by calling the manager's registerMenuItems method. The manager instance is passed to the callback function as an argument. Usage:

BackendMenu::registerCallback(function ($manager) {
    $manager->registerMenuItems([...]);
});
Parameters
  • callable $callback - A callable function.

public void registerContextSidenavPartial(string $owner, string $mainMenuItemCode, string $partial)

Registers a special side navigation partial for a specific main menu. The sidenav partial replaces the standard side navigation.

Parameters
  • string $owner - Specifies the navigation owner in the format Vendor/Module.
  • string $mainMenuItemCode - Specifies the main menu item code.
  • string $partial - Specifies the partial name.

public void registerMenuItems(string $owner, array $definitions)

Registers the back-end menu items. The argument is an array of the main menu items. The array keys represent the menu item codes, specific for the plugin/module. Each element in the array should be an associative array with the following keys:

  • label - specifies the menu label localization string key, required.
  • icon - an icon name from the Font Awesome icon collection, required.
  • url - the back-end relative URL the menu item should point to, required.
  • permissions - an array of permissions the back-end user should have, optional. The item will be displayed if the user has any of the specified permissions.
  • order - a position of the item in the menu, optional.
  • counter - an optional numeric value to output near the menu icon. The value should be a number or a callable returning a number.
  • counterLabel - an optional string value to describe the numeric reference in counter.
  • sideMenu - an array of side menu items, optional. If provided, the array items should represent the side menu item code, and each value should be an associative array with the following keys:
    • label - specifies the menu label localization string key, required.
    • icon - an icon name from the Font Awesome icon collection, required.
    • url - the back-end relative URL the menu item should point to, required.
    • attributes - an array of attributes and values to apply to the menu item, optional.
    • permissions - an array of permissions the back-end user should have, optional.
    • counter - an optional numeric value to output near the menu icon. The value should be a number or a callable returning a number.
    • counterLabel - an optional string value to describe the numeric reference in counter.
Parameters
  • string $owner - Specifies the menu items owner plugin or module in the format Author.Plugin.
  • array $definitions - An array of the menu item definitions.

public void removeMainMenuItem($owner, $code)

Removes a single main menu item

Parameters
  • $owner
  • $code

public void removeSideMenuItem($owner, $code, $sideCode)

Removes a single main menu item

Parameters
  • $owner
  • $code
  • $sideCode

public void setContext(string $owner, string $mainMenuItemCode, string $sideMenuItemCode=NULL)

Sets the navigation context. The function sets the navigation owner, main menu item code and the side menu item code.

Parameters
  • string $owner - Specifies the navigation owner in the format Vendor/Module
  • string $mainMenuItemCode - Specifies the main menu item code
  • string $sideMenuItemCode - Specifies the side menu item code

public void setContextMainMenu(string $mainMenuItemCode)

Specifies a code of the main menu item in the current navigation context.

Parameters
  • string $mainMenuItemCode - Specifies the main menu item code

public void setContextOwner(string $owner)

Sets the navigation context. The function sets the navigation owner.

Parameters
  • string $owner - Specifies the navigation owner in the format Vendor/Module

public void setContextSideMenu(string $sideMenuItemCode)

Specifies a code of the side menu item in the current navigation context. If the code is set to TRUE, the first item will be flagged as active.

Parameters
  • string $sideMenuItemCode - Specifies the side menu item code

Protected methods

protected void __construct()

Constructor.

protected array filterItemPermissions(User $user, array $items)

Removes menu items from an array if the supplied user lacks permission.

Parameters
  • User $user - A user object
  • array $items - A collection of menu items

protected void init()

Initialize this singleton.

protected void loadItems()

Loads the menu items from modules and plugins

protected string makeItemKey(object $item, $code)

Internal method to make a unique key for an item.

Parameters
  • object $item
  • $code