MenuConfig

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/ui/menu">
    <menu id="application"
          caption="msg://ui.ex2/menu.application"
          description="Application menu items"
          expanded="true"
          icon="VIEW_ACTION"
          insertBefore="administration">
        <item id="User.browse"/>
        <separator/>
        <item screen="sample_CustomerScreen"
              caption="msg://ui.ex2.screen.customer/customerScreen.caption"/>
        <item screen="sample_City.browse" 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.

  • caption - a caption of the menu element. If not set, the caption will be determined by the rule explained below.

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

  • icon - an icon of the menu element. See Icons for details.

  • insertBefore, insertAfter - determine whether the item should be inserted before or after a particular element or a menu item with the specified identifier. These attributes are used to insert an item to the appropriate place in the menu defined in the files of add-ons. Do not use the insertBefore and insertAfter attributes at the same time.

  • stylename - defines a style name for the menu item. See Themes for details.

  • expanded - determines whether the menu element should be expanded when opening the main screen. The default value is false.

For example:

<menu id="application"
      caption="msg://ui.ex2/menu.application"
      description="Application menu items"
      expanded="true"
      icon="VIEW_ACTION"
      insertBefore="administration">
</menu>

Item Attributes

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

  • id - a unique identifier of the element. If no screen, bean, class attributes are defined, the id is used to point to a screen with the same id. When the user clicks on the menu item, the corresponding screen will be opened on the main screen.

    <item id="User.browse"/>
  • caption - a caption of the item element. If not set, the caption will be determined by the rule explained below.

    <item screen="sample_CustomerScreen"
          caption="msg://ui.ex2.screen.customer/customerScreen.caption"/>
  • description - a text which is shown as a tooltip on mouse hover. You can also use localized messages from the message bundle.

  • screen - a screen 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 screen="sample_City.browse" id="cities"/>
    <item screen="sample_City.browse" id="cities2"/>
  • bean - a bean name. Must be used together with beanMethod. When the user clicks on the menu item, the method of the bean is invoked.

    menu.xml
    <item bean="sample_MenuBean"
          beanMethod="showCityBrowse"
          caption="Show Cities"/>
    MenuBean.java
    @Component("sample_MenuBean")
    public class MenuBean {
        @Autowired
        private ScreenBuilders screenBuilders;
    
        public void showCityBrowse(){
            final Screen frameOwner = AppUI.getCurrent()
                    .getTopLevelWindowNN().getFrameOwner();
            screenBuilders.screen(frameOwner)
                    .withScreenClass(CityBrowse.class)
                    .build()
                    .show();
        }
    }

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

    menu.xml
    <item bean="sample_MenuBean" beanMethod="openLink"
          id="openBeanWithParams" caption="OpenBeanWithParams">
        <properties>
            <property name="url" value="https://jmix.io"/>
        </properties>
    </item>
    MenuBean.java
    @Component("sample_MenuBean")
    public class MenuBean {
    
        @Autowired
        private ObjectProvider<WebBrowserTools> webBrowserToolsProvider;
    
        public void openLink(Map<String, Object> parameters) {
            String url = (String) parameters.get("url");
            if (url == null) {
                return;
            }
    
            webBrowserToolsProvider.getObject().showWebPage(
                    url, ParamsMap.of("target", "_blank"));
        }
    }
  • class - a fully qualified name of a class that implements the MenuItemRunnable interface. When the user clicks on the menu item, an instance of the specified class is created and its method is invoked.

    menu.xml
    <item class="ui.ex2.app.CustomMenu" id="jmix" caption="Open page"/>
    CustomMenu.java
    public class CustomMenu implements MenuItemRunnable, ApplicationContextAware {
    
        private ApplicationContext applicationContext;
    
        public void openLink(String url) {
            applicationContext.getBean(WebBrowserTools.class)
                    .showWebPage(url, ParamsMap.of("target", "_blank"));
        }
    
        @Override
        public void run(FrameOwner origin, MenuItem menuItem) {
            if (menuItem.getId().equals("jmix")) {
                openLink("https://jmix.io");
            } else {
                openLink("https://google.com");
            }
        }
    
        @Override
        public void setApplicationContext(ApplicationContext applicationContext)
                throws BeansException {
            this.applicationContext = applicationContext;
        }
    }
  • shortcut - a keyboard shortcut for this menu item. Possible modifiers - ALT, CTRL, SHIFT - are separated with “-”. For example:

    <item screen="sample_City.browse"
          id="cities3"
          shortcut="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 screen="sample_City.browse"
          id="cities4"
          shortcut="${sample.menu.city}"/>
    application.properties
    sample.menu.city=ALT-CTRL-C
  • The openMode attribute defines how a screen will be opened. It corresponds to the OpenMode enumeration with the values: NEW_TAB, DIALOG, NEW_WINDOW. Default value is NEW_TAB.

    <item screen="sample_City.browse"
          id="cities5"
          openMode="DIALOG"/>
  • icon - an icon of the item element. See Icons for details.

  • insertBefore, insertAfter - determine whether the item should be inserted before or after a particular element or a menu item with the specified identifier.

  • resizable - only relevant to the DIALOG screen open mode. Controls window resizing ability. Possible values − true, false. By default, the main menu does not affect the ability to resize dialog windows.

  • stylename - defines a style name for the menu item. See Themes for details.

Item Properties

properties is a nested element of item. It defines a set of properties to pass to the screen’s public setters. Each property is defined in the property element with the name attribute, which corresponds to a setter method. The setters are invoked by the framework between sending AfterInitEvent and BeforeShowEvent.

property attributes:

  • name - property name.

  • value - property value for non-entity properties.

  • entityClass - class of the entity property.

  • entityId - id of the entity property.

  • entityFetchPlan - optional fetch plan for loading an entity property.

For example, the filterVisible boolean property in menu.xml corresponds to the void setFilterVisible(Boolean value) method in the screen controller:

menu.xml
<item screen="sample_City.browse" id="cities6">
    <properties>
        <property name="filterVisible" value="false"/>
    </properties>
</item>
CityBrowse.java
public void setFilterVisible(Boolean value){
    isFilterVisible = value;
}

See the example with the entity property:

<item screen="User.edit" caption="User screen">
    <properties>
        <property name="user"
                  entityClass="ui.ex2.entity.User"
                  entityId="60885987-1b61-4247-94c7-dff348347f93"
                  entityFetchPlan="_base"/>
    </properties>
</item>

Defining Menu Caption

If the caption attribute is not specified, the localized name of a menu or item element is defined in the following way: the menu-config prefix with a dot at the end is added to the element identifier; the resulting string is used as a key for the message bundle. For example:

messages.properties
menu-config.User.browse = Users
menu-config.cities = Cities

If the id is not set, the caption will be generated from the class name (if the class attribute is set), or the bean name and the bean method name (if the bean attribute is set). Therefore, setting the id attribute is recommended.