What it is
FrontNavigation extensions are used to add new tabs to the front end navigation system, tying in directly with the menu manager in the AdminCP. Navigation tabs can show or hide based on permissions and other criteria, activate (or not) based on custom factors, and can support submenus as well.
How to use
Most front navigation extensions are fairly simple, and represent a single link to an area of the site. We will start by outlining how these work: you will need 5 basic methods for this type of front navigation extension.
/**
* Get Type Title which will display in the AdminCP Menu Manager
*
* @return string
*/
public static function typeTitle()
The typeType() shows the title for this type of menu entry and is primarily used in the AdminCP menu manager. A language string value should be returned typically.
/**
* Can the currently logged in user access the content this item links to?
*
* @return bool
*/
public function canAccessContent()
The canAccessContent() method allows you to dynamically check if the current viewing member an access the page or not. Often this will come down to checking if the member can access the module or not, however you can perform whatever checks you want, returning TRUE if the member can access the tab and FALSE if not.
/**
* Get Title
*
* @return string
*/
public function title()
The title() method returns the tab title to display on the front end.
/**
* Get Link
*
* @return \IPS\Http\Url
*/
public function link()
The link() method, as you might expect, returns the link that the tab should point to. A full \IPS\Http\Url object should be returned.
/**
* Is Active?
*
* @return bool
*/
public function active()
The active() method returns TRUE to indicate that the user is currently viewing this tab, and FALSE otherwise. Most often, this is accomplished by checking which application, module and controller the user is viewing. For example:
/**
* Is Active in the online users list?
*
* @return bool
*/
public function active()
{
return \IPS\Dispatcher::i()->application->directory === 'core' and \IPS\Dispatcher::i()->module->key === 'online';
}
While the above methods represent the 5 most common methods to define, the extension supports some other capabilities as well.
/**
* Children
*
* @param bool $noStore If true, will skip datastore and get from DB (used for ACP preview)
* @return array
*/
public function children( $noStore=FALSE )
The children() method returns an array of child elements for the menu item, used to create a submenu. The sole parameter passed to this method is a boolean flag to indicate whether or not the child items should be loaded directly from the database, bypassing caching.
/**
* Permissions can be inherited?
*
* @return bool
*/
public static function permissionsCanInherit()
By default permissions can be inherited by menu items (e.g. if you cannot access any menu items, do not show the tab), however you can disable this if you wish by overriding this method and returning FALSE.
/**
* Allow multiple instances?
*
* @return string
*/
public static function allowMultiple()
By default, only one instance of a menu item is available to set up (so you cannot create two 'Gallery' tabs by choosing Gallery in the menu manager), however if your menu class would benefit from supporting multiple instances this method can be overridden and return TRUE. This is used for the base generic Menu front navigation extension, for instance, as you may want to create multiple menus.
/**
* Get configuration fields
*
* @param array $configuration The existing configuration, if editing an existing item
* @param int $id The ID number of the existing item, if editing
* @return array
*/
public static function configuration( $existingConfiguration, $id = NULL )
If your menu requires special configuration, you can define a static configuration() method to return an array of form helper elements to display in order to configure the menu.
/**
* Parse configuration fields
*
* @param array $configuration The values received from the form
* @return array
*/
public static function parseConfiguration( $configuration, $id )
If your menu requires special configuration, you can define a static parseConfiguration() method to process the form helper elements returned with the configuration() method described above.
/**
* Can this item be used at all?
* For example, if this will link to a particular feature which has been diabled, it should
* not be available, even if the user has permission
*
* @return bool
*/
public static function isEnabled()
As the docblock states, you can return FALSE from the isEnabled() method if you need to completely disable the menu item regardless of user permissions.
It is worth noting that FrontNavigation extensions extend \IPS\core\FrontNavigation\FrontNavigationAbstract so it is worth taking a look at this class to understand the methods being extended and how they interact if there is any confusion.
Report Document