<menuitem/>

Description

Helium provides a top level menu within Helium applications. The menu items for these menus are specified using the menu item element. Menu items provide a user interface entry point to the application by providing access to the view in which the menu item is specified. As part of this element, the user role that has access to the menu item needs to be specified as well as the label for the menu item. The label is specified using a key to a lang file entry and is required.

In addition the menu item icon can be specified using the icon attribute. This icon needs to satisfy the following:

Be placed in the web-app/images folder
Preferably be a png image with an alpha channel and alpha background instead of white (where applicable)
Have a width of 40 pixels and height of 30 pixels. Higher resolution images can be used but the aspect ratio should not differ from a 40 x 30 pixel image

Further more, the position of the menu item in the menu can be set by specifying the index in the menu as a value for the order attribute.

A view can have more than one menu item given that the menu items are specified for different roles. Having more than one menu item on a view allows the same view to be accessible from different user roles with the possibility of using different positions in the menu and using different icons for the different roles.

If a view should be accessible by a menu item for more than one role, but still use the same menu item position and icon, more than one role can be specified for a single menu item.

If an icon and menu item position is not specified, Helium will use a default icon and menu item position.

Basic Example

Default menu item icon

 <menuitem label="menu_item.farmer_map">
    <userRole>System Admin</userRole>
</menuitem>

Menu item with custom icon and menu position

 <menuitem label="menu_item.farmer_map" icon="Globe" order="5">
    <userRole>System Admin</userRole>
</menuitem>

View with multiple menu items with different positions and icons

<menuitem label="menu_item.farmer_map" icon="Globe" order="5">
    <userRole>System Admin</userRole>
</menuitem>
        
<menuitem label="menu_item.farmer_map" icon="Map" order="3">
    <userRole>Shop Owner</userRole>
</menuitem>

View with single menu item for different user roles

 <menuitem label="menu_item.farmer_map" icon="Globe" order="5">
    <userRole>System Admin</userRole>
    <userRole>Shop Owner</userRole>
</menuitem>

Advanced Example

In addition to specifying the roles, label, icon and preferred order for a menu item in a static manner as shown in the basic example above, these values can also be dynamically specified using bindings. Bindings for each of these properties support binding to a function, unit variable or object attribute. The example above can be re-implemented dynamically as follows:

<menuitem>
    <dynamicUserRoles function="getRoles"/>
    <dynamicIcon function="getIcon"/>
    <dynamicLabel function="getLabel"/>
    <dynamicOrder function="getOrder"/>
</menuitem>

Backing unit functions used for bindings:

DSL_ROLES[] getRoles() {
    DSL_ROLES[] roles;
    roles.append(DSL_ROLES.System_Admin);
	roles.append(DSL_ROLES.Shop_Owner);
    return roles;
}

string getIcon() {
    return "Globe";
}

int getOrder() {
    return 5;
}

string getLabel() {
	return String:translate("menu_item.farmer_map");
}

Note the return value above for each binding. Invalid types will result in compile time errors. Note specifically the use of the DSL_ROLES built-in enumeration. This enumeration has values that represent each role in your application. For each role, the value is the role name as specified in the @Role annotation on the accompanying model object formatted to have white space replaced by underscores.

Keep in mind that the values for these bindings are executed before the main menu of your app loads and thus before any init function is executed. This means that you will not be able to make use of values set in an init function. The values for the bindings are only re-evaluated when the app is refreshed or reloaded from the browser.

Bindings for menu item properties are support from Helium 1.18 onwards.