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 Attributes
menu
is a nested element of menu-config
. It has the following attributes:
-
id
— a unique identifier of the element. -
title
— a title of themenu
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 themenu
element. -
classNames
— defines a class name for the menu item. -
opened
— defines whether themenu
element is initially expanded. The default value isfalse
.
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 noview
orbean
, attribute is specified, theid
is used to point to a view with thisid
. When the user clicks on the menu item, the corresponding view opens on the main screen.<item id="Department.list"/>
-
title
— a title of theitem
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 withbeanMethod
. 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 ViewNavigationSupport viewNavigationSupport; public void browseCities() { viewNavigationSupport.navigate(CityListView.class); } }
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 themenu.xml
file in the following way:menu.xml<item view="City.list" id="cities4" shortcutCombination="${sample.menu.city}"/>
application.propertiessample.menu.city=ALT-SHIFT-C
-
icon
— an icon of theitem
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:
<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.
<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:
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.