Конфигурация меню

MenuConfig - это особый класс, который загружает структуру главного меню на основе файла, указанного в свойстве jmix.ui.menu-config.

Используйте Дизайнер меню Studio, чтобы определить структуру меню.

При создании нового проекта в Studio, генерируется файл menu.xml, который определяет структуру главного меню приложения.

<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>

Существует два режима загрузки файлов, определяющих структуру меню: составной (по умолчанию) и одиночный. Используйте свойство jmix.ui.composite-menu, чтобы переключать эти режимы.

Давайте подробно рассмотрим файл menu.xml.

menu-config - это корневой элемент XML. Элементы menu-config образуют структуру дерева, где элементы menu являются ветвями, а элементы item и separator - листьями.

menu - это вложенный элемент menu-config. Он имеет следующие атрибуты:

  • id - уникальный идентификатор элемента.

  • title - заголовок элемента menu. Если не указан, заголовок определяется по правилу, объясненному ниже.

  • description - текстовое описание, отображаемое во всплывающей подсказке при наведении мыши. Вы можете использовать локализованные сообщения из пакета сообщений.

  • icon - значок элемента menu.

  • classNames - определяет имя класса для элемента меню.

  • opened - определяет, будет ли элемент menu изначально развернут. Значение по умолчанию - false.

Например:

<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 - это вложенный элемент menu. Для каждого элемента можно установить атрибуты, свойства, параметры маршрута и параметры запроса.

Атрибуты следующие:

  • id - уникальный идентификатор элемента. Если не указаны атрибуты view или bean, идентификатор используется для указания на представление с этим id. Когда пользователь нажимает на элемент меню, соответствующее представление открывается на главном экране.

    <item id="Department.list"/>

  • title - заголовок элемента item. Вы можете использовать локализованные сообщения из пакета сообщений. Если не указан, заголовок будет определен по правилу, объясненному ниже.

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

  • description - текстовое описание, отображаемое во всплывающей подсказке при наведении мыши. Вы можете использовать локализованные сообщения из пакета сообщений.

  • view - идентификатор экрана. Он может использоваться для включения одного экрана в меню несколько раз. Когда пользователь нажимает на элемент меню, открывается соответствующий экран на главном экране.

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

  • bean - имя бина. Должно использоваться вместе с beanMethod. Когда пользователь нажимает на элемент меню, вызывается указанный метод.

    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();
    }
}

    Вы можете передавать параметры из элемента меню в метод бина, используя вложенный элемент properties. Например:

    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 - горячая клавиша для этого элемента меню. Возможные модификаторы - ALT, CTRL, SHIFT - разделяются символом "-". Например:

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

    Горячие клавиши также можно настроить в файле application.properties, а затем использовать в файле menu.xml следующим образом:

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

  • icon - значок элемента item.

  • className - определяет имя класса для элемента меню.

Свойства элемента меню

Элемент item может иметь свойства, которые передаются бинам. Вложенный элемент properties является контейнером для таких свойств, которые определены в дочерних элементах property. Элемент property может иметь следующие атрибуты:

  • name - имя свойства.

  • value - значение, которое нужно установить для этого свойства.

Параметры маршрута

Элемент item может объявлять параметры маршрута внутри своего дочернего элемента routeParameters.

Маршрут, который определяет URL-путь к экрану, может включать параметр маршрута. Один из примеров такого параметра - это идентификатор конкретного экземпляра сущности, передаваемый в экран деталей. Следующий элемент меню открывает экран деталей для определенного отдела:

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

Параметры запроса URL

Элемент item может объявлять один или несколько параметров запроса внутри своего дочернего элемента urlQueryParameters.

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

Параметры запроса представляют собой пары имя-значение, прикрепленные к концу URL после вопросительного знака (?). Несколько параметров запроса объединяются в строку запроса с использованием амперсанда (&). Приведенный выше пример создаст элемент меню, указывающий на следующий URL:

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

Определение заголовка меню

Если атрибут title не задан, заголовок элемента menu или item определяется как комбинация префикса menu-config и идентификатора элемента. Получившаяся строка может использоваться как ключ, который определяет заголовок в пакете сообщений. Например:

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

Если id для пункта меню не указан, для задания ему заголовка в пакете сообщений за префиксом menu-config может следовать имя экрана или имя бина и имя метода бина, разделенные символом #, в зависимости от наличия соответствующих атрибутов.