A.menu.xml - CUBA Platform. Developer’s Manual

Files of this type are used in the Web Client to define the structure of the application main menu.

XML schema is available at http://schemas.haulmont.com/cuba/7.2/menu.xsd

The file location is specified in the cuba.menuConfig application property. When you create a new project in Studio, it creates the web-menu.xml file in the root package of the web module, for example modules/web/src/com/company/sample/web-menu.xml.

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 element attributes:
- id – unique identifier of the element.
- caption - 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 main message pack.
- icon - icon of the menu element. See icon for details.
- insertBefore, insertAfter – determines whether the item should be inserted before or after a particular element or a menu item with the specified identifier. This attribute is used to insert an element to an appropriate place in the menu defined in the files of application components. Before and after elements cannot be used at the same time.
- stylename - defines a style name for the menu item. See Themes for details.
item element attributes:
- id – 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 in the main application window.
  <item id="sample_Foo.browse"/>
- caption - caption of the menu element. If not set, the caption will be determined by the rule explained below.
  <item id="sample_Foo.browse" caption="mainMsg://fooBrowseCaption"/>
- 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 in the main application window.
  <item id="foo1" screen="sample_Foo.browse"/> <item id="foo2" screen="sample_Foo.browse"/>
- 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.
  <item bean="sample_FooProcessor" beanMethod="processFoo"/>
- class - fully qualified name of a class which implements Runnable, Consumer<Map<String, Object>> or MenuItemRunnable interface. When the user clicks on the menu item, an instance of the specified class is created and its method is invoked.
  <item class="com.company.sample.web.FooProcessor"/>
- description - a text which is shown as a tooltip on mouse hover. You can also use localized messages from the main message pack.
  <item id="sample_Foo.browse" description="mainMsg://fooBrowseDescription"/>
- shortcut – a keyboard shortcut for this menu item. Possible modifiers – ALT, CTRL, SHIFT – are separated with “-”. For example:
  shortcut="ALT-C" shortcut="ALT-CTRL-C" shortcut="ALT-CTRL-SHIFT-C"
  Shortcuts can also be configured in application properties and then used in menu.xml file in the following way:
  shortcut="${sales.menu.customer}"
- openType – screen open mode, corresponds to the OpenMode enum: NEW_TAB, THIS_TAB, DIALOG. Default value is NEW_TAB.
- icon - icon of the menu element. See icon for details.
- insertBefore, insertAfter – determines 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 sub-elements:

properties – defines a set of properties to pass to the screen’s public setters. Each property is defined in the property element with name attribute which corresponds to a setter method, e.g. foo string property corresponds to the void setFoo(String value) 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 entity property.
- entityId – id of entity property.
- entityView – optional view for loading an entity property.
permissions – an element defining a set of permissions required to make the menu item available to the current user. This mechanism should only be used when item availability should be tied to a specific permission, or to more than one arbitrary permissions. In most cases, the standard capabilities of the security subsystem should be sufficient to manage the menu item availability based on screen identifiers.

The element should contain nested permission elements, each describing a single required permission. The menu item will only be accessible if all permissions are granted.

permission attributes:
- type – permission type. The following types are available for PermissionType: SCREEN, ENTITY_OP, ENTITY_ATTR, SPECIFIC, UI.
- target – an object checked for permission. Depends on permission type:
  - SCREEN – screen identifier, for example sales_Customer.lookup.
  - ENTITY_OP – a string formatted as {entity_name}:{op}, where {op} – read, create, update, delete. For example: sales_Customer:create.
  - ENTITY_ATTR – a string formatted as {entity_name}:{attribute}, for example sales_Customer:name.
  - SPECIFIC – specific permission identifier, for example sales.runInvoicing.
  - UI – path to a visual component of a screen.

Example of a menu file:

<menu-config xmlns="http://schemas.haulmont.com/cuba/menu.xsd">

    <menu id="sales" insertBefore="administration">
        <item id="sales_Order.lookup"/>

        <separator/>

        <item id="sales_Customer.lookup" openType="DIALOG"/> (1)

        <item screen="sales_CustomerInfo">
            <properties>
                <property name="stringParam" value="some string"/> (2)
                <property name="customerParam" (3)
                          entityClass="com.company.demo.entity.Customer"
                          entityId="0118cfbe-b520-797e-98d6-7d54146fd586"/>
            </properties>
        </item>

        <item screen="sales_Customer.edit">
            <properties>
                <property name="entityToEdit" (4)
                          entityClass="com.company.demo.entity.Customer"
                          entityId="0118cfbe-b520-797e-98d6-7d54146fd586"
                          entityView="_local"/>
            </properties>
        </item>
    </menu>

</menu-config>

1	- open the screen in dialog window.
2	- invoke `setStringParam()` method passing `some string` to it.
3	- invoke `setCustomerParam()` method passing an entity instance loaded by the given id.
4	- invoke `setEntityToEdit()` method of `StandardEditor` passing an entity instance loaded by the given id and view.

menu-config.sales=Sales
menu-config.sales_Customer.lookup=Customers

If the id is not set, the name of the menu element 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.

A.5. menu.xml