Skip to main content

Custom Menus

While Mango provides a fully customizable sidebar menu through the Edit Menu page, there are cases where you need a custom in-page navigation menu -- for example, a toolbar at the top of your custom pages or a tab-style navigation within a specific section of your application. Mango supports two approaches for building custom menus: a simple embed method and a more advanced approach using userModule.js.

Simple Menu Embed Method​

The simplest approach is to create a dedicated menu page and embed it on each page that needs it.

Step 1: Create the Menu Page​

Create a new custom page using the Page Editor that contains only your menu markup. For example, a horizontal button bar:

<div flex layout="column" layout-gt-md="row">
    <ma-button raised="true" icon="home" label="Home"
               palette="primary" ui-sref="Page1"></ma-button>
    <ma-button raised="true" label="Page 2"
               ui-sref="Page2"></ma-button>
    <ma-button raised="true" label="Page 3"
               ui-sref="Page3"></ma-button>
</div>

This menu links to three different pages. Each linked page needs to have a corresponding menu item with the matching ui-sref state name, but you can make those menu items invisible (hidden from the sidebar).

Step 2: Embed the Menu on Other Pages​

On each page that should display this menu, add the following code at the top, where the xid is the XID of the menu page you created:

<ma-ui-page-view xid="65a55f29-6efd-4bc8-85d4-48cb48194edf"></ma-ui-page-view>

Tip: To find the XID of a custom page, open it in the Page Editor or Dashboard Designer, click the view icon, and copy the XID from the URL.

Now you can edit the menu in one place, and the changes take effect on every page that embeds it.

Customizing the Menu Appearance​

You can style the menu using any Angular Material layout and CSS:

<div layout="row" layout-align="center center" style="background-color: #37474F; padding: 8px;">
    <ma-button raised="true" icon="dashboard" label="Overview"
               palette="primary" ui-sref="Dashboard"></ma-button>
    <ma-button raised="true" icon="show_chart" label="Trends"
               ui-sref="Trends"></ma-button>
    <ma-button raised="true" icon="warning" label="Alarms"
               ui-sref="Alarms"></ma-button>
    <ma-button raised="true" icon="settings" label="Settings"
               ui-sref="Settings"></ma-button>
</div>

Advanced Approach: User Module with Nested States​

For a more sophisticated setup where the menu automatically appears on a group of pages without manually embedding it, you can use a userModule.js file to create a parent UI-Router state. Child pages are then nested inside this parent, and the menu appears automatically.

Step 1: Create the User Module​

Create a userModule.js file and add it from the UI Settings page. This registers a parent state that contains both your menu and a <div ui-view> element where child pages will render:

define(['angular', 'require'], function(angular, require) {
    'use strict';

    var userModule = angular.module('userModule', ['maUiApp']);

    userModule.config(['maUiMenuProvider', (maUiMenuProvider) => {
        maUiMenuProvider.registerMenuItems([{
            name: 'myApp',
            url: '/my-app',
            template: '<ma-ui-page-view xid="menu-page-xid"></ma-ui-page-view>' +
                      '<div ui-view></div>',
            menuText: 'My Application',
            abstract: true
        }]);
    }]);

    return userModule;
});

Key properties of the state definition:

PropertyDescription
nameThe unique state name. Child states will be prefixed with this (for example, myApp.home).
urlThe URL prefix for this state. Child pages will append their own URL segment.
templateContains the menu page embed and a <div ui-view> where child pages render.
abstractSet to true so this state cannot be navigated to directly -- users always go to a child state.
menuHiddenOptionally set to true to hide this parent item from the sidebar menu.

Step 2: Create Child Pages​

Create your custom pages as usual using the Page Editor or Dashboard Designer. When adding menu items for these pages, choose "My Application" as their parent item. The menu page will automatically be included above each child page.

URL Structure​

With this setup, your URLs will be structured as:

  • /ui/my-app/home -- The home child page
  • /ui/my-app/reports -- A reports child page
  • /ui/my-app/settings -- A settings child page

Each of these pages will display the embedded menu at the top, followed by the child page content.

Choosing Between Methods​

FeatureSimple EmbedUser Module
Setup complexityLow -- just copy-paste an embed tagHigher -- requires userModule.js
MaintenanceMust add embed tag to each pageAutomatic for all child pages
URL structureIndependent page URLsHierarchical URLs under a parent
Menu visibilityMust manually add to each pageAutomatically shown on all child pages
Best forSmall number of related pagesMulti-page applications with consistent navigation