Site administrators can customise the contents of the Totara menu via the user interface and use plugins to define new menu items. Menu items can also be restricted to members of an Audience.
(This video is taken from the Dashboards and basic theming course in the Totara Academy, where you can access more resources and learning materials - including other videos).
Configure main menu options
Go to Site administration > Appearance > Main menu to display the configuration page listing existing menu items and their hierarchies.
The capability totara/core:editmainmenu controls access to the configuration pages.
- Select the Edit (pencil) icon next to a page to edit certain page settings.
- Re-order page items.
- Show/hide page items from the main screen.
The settings that can be edited are:
- Parent item: Select either Top for a top level menu item or another top level item. Currently only two levels are supported (top level or one level deep) so you cannot pick an item that has a parent itself.
- Menu title: This is the string that appears as the menu item name. If the multi-language filter is enabled, these can be multi-lingual strings.
- Visibility: Controls whether a menu item is shown or not. This is equivalent to clicking the eye to toggle visibility. You can select Use custom access rules to display the menu to users that meet access rules based on their role, audience, or preset role.
- Open link in new window: If checked, the link will open in a separate window.
To add a custom access rule to a menu:
- Select Site administration > Appearance > Main menu.
- Select Edit menu item.
- Select Use custom access rules under Visibility.
- Select the Access tab to define the access rule.
- Select whether all or any of the criteria need to be met to view the menu.
- Fill in the criteria for the role, audience, or preset rule.
- Select Save.
You can create custom menu items by clicking the Add new menu item button. Custom menu items can also be deleted.
You cannot delete ‘hard coded’ menu options but, from a user’s point of view, hiding them has the same effect.
When adding custom menu items you must specify a URL for the link as well as a title. The link can be a full URL (starting with http:// or https://), or you can make a link relative to your LMS URL by starting with a forward slash ' / '. For example, "/course/index.php" would point to "[your-lms-url]/course/index.php".
When defining custom menu item URLs, you can now include the following placeholders:
- ##userid## - Current user id.
- ##username## - Current username.
- ##useremail## - Current user email.
- ##courseid## - Current course ID.
They will be dynamically substituted for the appropriate value at the time when the page is viewed.
Plugin developers can also add Totara menu options as follows:
First, define a class that extends
\totara_core\totara\menu\item and put it in a file in "[your-module]/classes/menu/[your-menu-item].php".
For an example, see totara/core/classes/menu/myteam.php.
You are expected to implement the following methods:
protected function get_default_title()- Returns a string to be used from the menu item name if not customised.
protected function get_default_url()- Returns a string containing the URL to point to (absolute or relative to wwwroot if it starts with a slash).
You can choose to implement the following methods:
public function get_default_visibility()- Returns a menu visibility constant to set the visibility when first added. Default is menu::SHOW_WHEN_REQUIRED.
public function get_default_sortorder()- Returns an integer to indicate default location within the menu when first added. Default is add to the end.
protected function check_visibility()- Returns either menu::SHOW_ALWAYS or menu::HIDE_ALWAYS. Called if visibility is set to menu::SHOW_WHEN_REQUIRED. Defaults to menu::SHOW_ALWAYS.
protected function get_default_parent()- Returns the class name of another menu item to use as the parent. Defaults to 'root' meaning top level.
protected function get_default_targetattr()- Returns a string to be used in the link target attribute when first added. Defaults to menu::TARGET_ATTR_SELF (meaning same window).
Add a new file
[your-module]/db/totaramenu.php with the following:
See totara/core/totaramenu.php for an example.
Bump the version of your module to trigger a database upgrade. The new menu item will be detected and automatically added to the menu.