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

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 - это вложенный элемент 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>

Элемент menu может содержать дочерние элементы: items, separators и icon (для добавления пользовательской иконки).

Атрибуты элемента

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 ViewNavigationSupport viewNavigationSupport;

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

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

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

Элемент 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 может следовать имя экрана или имя бина и имя метода бина, разделенные символом #, в зависимости от наличия соответствующих атрибутов.