Menu Configuration

MenuConfig is a special class that loads the main menu structure based on a file specified in the jmix.ui.menu-config property.

Use Studio menu designer to define the menu structure.

When you create a new project in Studio, it generates the menu.xml file that defines the structure of the application main menu.

<menu-config xmlns="http://jmix.io/schema/flowui/menu">
    <menu id="main-menu"
          title="msg://com.company.onboarding/menu.application.title"
          description="Application menu items"
          opened="true"
          icon="DOT_CIRCLE"
          classNames="application-menu">
        <item id="Department.list"/>
        <separator/>
        <item view="City.list" id="cities"/>
    </menu>
</menu-config>

There are two modes of loading files that define menu structure: composite (default) and single. Use the jmix.ui.composite-menu property to switch these modes.

Let’s consider the menu.xml file in detail.

menu-config is the root XML element. Elements of menu-config form a tree structure where menu elements are branches and item and separator elements are leaves.

menu is a nested element of menu-config. It has the following attributes:

  • id — a unique identifier of the element.

  • title — a title of the menu element. If not set, the title is determined by the rule explained below.

  • description — a text description to be shown as tooltip on mouse hover. You can use localized messages from the message bundle.

  • icon — an icon of the menu element.

  • classNames — defines a class name for the menu item.

  • opened — defines whether the menu element is initially expanded. The default value is false.

For example:

<menu id="main-menu"
      title="msg://com.company.onboarding/menu.application.title"
      description="Application menu items"
      opened="true"
      icon="DOT_CIRCLE"
      classNames="application-menu">
    <item id="Department.list"/>
    <separator/>
    <item view="City.list" id="cities"/>
</menu>

Item Attributes

item is a nested element of menu. For each item you can set attributes, properties, route and query parameters.

The attributes are as follows:

  • id — a unique identifier of the element. If no view or bean, attribute is specified, the id is used to point to a view with this id. When the user clicks on the menu item, the corresponding view opens on the main screen.

    <item id="Department.list"/>

  • title — a title of the item element. You can use localized messages from the message bundle. If not set, the title will be determined by the rule explained below.

    <item view="User.list" title="msg://com.company.onboarding.view.user/UserListView.title"/>

  • description — a text description to be shown as tooltip on mouse hover. You can use localized messages from the message bundle.

  • view — a view identifier. It can be used to include one screen into the menu multiple times. When the user clicks on the menu item, the corresponding screen will be opened on the main screen.

    <item view="City.list" id="cities1"/>
<item view="City.list" id="cities2"/>

  • bean — a bean name. Must be used together with beanMethod. When the user clicks on the menu item, the specified method is invoked.

    menu.xml
    <item bean="MenuBean"
      beanMethod="browseCities"
      title="Show Cities"/>
    MenuBean.java
    @Component("MenuBean")
public class MenuBean {
    @Autowired
    private ViewNavigators viewNavigators;

    public void browseCities() {
        viewNavigators.view(CityListView.class)
                .navigate();
    }
}

    You can pass parameters from the menu item to the bean method using the properties nested element. For example:

    menu.xml
    <item bean="MenuBean" beanMethod="openLink"
      id="openBeanWithParams" title="External Link">
    <properties>
        <property name="url" value="https://jmix.io"/>
    </properties>
</item>
    MenuBean.java
    @Component("MenuBean")
public class MenuBean {

    public void openLink(Map<String, Object> parameters) {
        String url = (String) parameters.get("url");
        if (url == null) {
            return;
        }
        UI.getCurrent().getPage().open(url);
    }
}

  • shortcutCombination — a keyboard shortcut for this menu item. Possible modifiers — ALT, CTRL, SHIFT — are separated with “-”. For example:

    <item view="City.list"
      id="cities3"
      shortcutCombination="ALT-C"/>

    Shortcuts can also be configured in the application.properties file and then used in the menu.xml file in the following way:

    menu.xml
    <item view="City.list"
      id="cities4"
      shortcutCombination="${sample.menu.city}"/>
    application.properties
    sample.menu.city=ALT-SHIFT-C

  • icon — an icon of the item element.

  • className — defines a class name for the menu item.

Item Properties

An item element can have properties to be passed to beans. The nested properties element is a container for such properties, which are defined in the property child elements. A property element can have the following attributes:

  • name — property name.

  • value — value to be set for this property.

Route Parameters

An item element can declare route parameters inside its child routeParameters element.

The route that defines the URL path of a view can include a route parameter. One example of such a parameter would be the id of a specific entity instance passed to a detail view. The following menu item opens a detail view for a particular department:

menu.xml
<item view="Department.detail" title="HR Department">
    <routeParameters>
        <parameter name="id" value="9b77a432-1610-5147-ff93-e7ee27c26e09"/>
    </routeParameters>
</item>

URL Query Parameters

An item element can declare one or multiple query parameters inside its child urlQueryParameters element.

menu.xml
<item view="City.list" title="Query Parameters">
    <urlQueryParameters>
        <parameter name="page" value="3"/>
        <parameter name="sort" value="desc"/>
    </urlQueryParameters>
</item>

Query parameters are name-value pairs attached to the end of a URL after a question mark (?). Multiple query parameters are joined together into a query string with an ampersand (&). The example above will create a menu item pointing at the following URL:

https://example.com/cities?page=3&sort=desc

Defining Menu Title

If the title attribute is not set, the title of a menu or item element is defined as a combination of the menu-config prefix and the element’s id. The resulting string can be used as the key that defines a title in the message bundle. For example:

messages.properties
menu-config.Departments.list = Departments
menu-config.cities = Cities

If menu item id is not set, to define a title for such menu item the menu-config prefix may be followed by the view name, or bean name and bean method name, separated by #, depending on which of these attributes are present.