Экраны и пункты меню

Динамическая модель может генерировать UI-экраны для динамических сущностей и добавлять соответствующие пункты меню, так что определённая во время выполнения сущность сразу становится пригодной для использования в UI приложения без написания какого-либо Java- или XML-кода. Она также может переопределять существующие экраны статических сущностей, что является способом отображения динамических атрибутов, которые вы добавили к этим сущностям.

Экраны объявляются для каждой сущности в модели, в списке views сущности. Полный список полей экрана см. в разделе Справочник по YAML. Раздел Определение модели описывает определение самой модели данных. Добавление поведения экранам описано в разделе Обработчики UI.

Экраны для динамических сущностей

У динамической сущности нет собственных экранов, пока вы их не объявите. Чтобы сделать её видимой и редактируемой в UI, добавьте как минимум экран списка, экран деталей или оба. Каждый экран имеет type либо list, либо detail, либо read, и из этих объявлений фреймворк автоматически генерирует UI-экраны — дескриптор XML не требуется.

Пример ниже объявляет экран list для динамической сущности LoyaltyLevel. Окружающая модель также объявляет экран detail для той же сущности, так что сущность можно как просматривать, так и редактировать:

views:
  - type: "list"
    viewId: "LoyaltyLevel.list"
    viewRoute: "loyalty-levels"
    viewTitle:
      en: "Loyalty levels"
      de: "Treuestufen"
    templateParams:
      includeProperties: ["name", "discount"]
      excludeProperties: ["publicSummary"]
    resourceRoles:
      - "employee"
      - "manager"
    menuItem:
      parentMenu: "application"
      insertBefore: "Customer.list"
      icon: "vaadin:star"
      title:
        en: "Loyalty levels"
      resourceRoles:
        - "employee"
        - "manager"
    descriptor:
      template: "default"

descriptor экрана динамической сущности управляет тем, как создаётся его компоновка. Он может принимать одну из следующих форм:

  • Опущен или template: "default" — фреймворк строит экран из встроенного шаблона по умолчанию, который создаёт стандартную компоновку списка (таблица данных с обычными действиями) или деталей (форма редактора). Отсутствие descriptor имеет тот же эффект, что и указание шаблона по умолчанию.

  • template: "<resource path>" — экран рендерится из пользовательского шаблона экрана вместо шаблона по умолчанию.

  • source: "<XML>" — вы предоставляете XML экрана напрямую. Это даёт вам полный контроль над компоновкой, так же как и при написании обычного дескриптора экрана вручную.

Предоставление дескриптора в виде литерального XML — это способ определить произвольную компоновку, которую невозможно выразить с помощью шаблона по умолчанию — например, пользовательские компоненты, группировку или дополнительные действия. XML должен быть корректным дескриптором UI-экрана; дескриптор экрана списка должен содержать компонент выбора (по умолчанию dataGrid), а дескриптор экрана деталей должен содержать контейнер редактируемой сущности (по умолчанию entityDc). Точные правила и значения по умолчанию см. в справочнике по экранам.

Генерация XML из шаблона

Начиная с Jmix 3.1

Чтобы получить пользовательскую компоновку, не создавая XML с нуля, сгенерируйте его из шаблона, а затем отредактируйте. В диалоге экрана откройте вкладку Descriptor и нажмите Generate XML. Фреймворк рендерит выбранный шаблон или шаблон по умолчанию для текущего состояния сущности, помещает результат в исходный код дескриптора и переключает тип дескриптора на source. Если исходный код уже не пустой, вас попросят подтвердить, что он будет заменён.

XML генерируется из редактируемой модели, поэтому это можно сделать до применения модели. Сущности и атрибуты, добавленные после последнего применения, включаются в результат. Параметры шаблона, такие как excludeProperties, учитываются.

Объявление экрана для динамической сущности может также поместить экран в меню приложения путём добавления объекта menuItem. При применении модели пункт меню появляется наряду со сгенерированным экраном. menuItem в приведённом выше фрагменте демонстрирует типичные поля:

  • parentMenu — идентификатор родительского меню, под которым размещается пункт. Если меню с таким идентификатором не существует, с ним создаётся новое корневое меню.

  • insertBefore — необязательный идентификатор соседнего пункта меню; если он присутствует, новый пункт вставляется перед этим соседом, в противном случае он добавляется в конец.

  • title — подпись пункта меню в виде локализованного значения. Если опущена, используется заголовок экрана.

  • icon (начиная с Jmix 3.1) — иконка пункта меню, например vaadin:star. В диалоге экрана можно выбрать иконку из списка или ввести её идентификатор. Если иконка не найдена, пункт меню отображается без иконки.

  • resourceRoles — коды ролей, обладатели которых могут видеть и использовать пункт меню.

Переопределение экранов статических сущностей

Добавление динамического атрибута к статической сущности не помещает его автоматически на существующие экраны этой сущности. Чтобы отобразить динамический атрибут на экране, который уже существует в вашем приложении, переопределите дескриптор этого экрана из модели.

Объявление экрана статической сущности ссылается на зарегистрированный экран через viewId и предоставляет descriptor.source, содержащий XML, который расширяет (extends) исходный дескриптор. В XML вы добавляете только нужные вам компоненты — например, столбец для нового динамического атрибута. Пример ниже расширяет экран приложения Customer.list и добавляет столбец taxId в его customersDataGrid:

- viewId: "Customer.list"
  descriptor:
    source: |
      <?xml version="1.0" encoding="UTF-8" standalone="no"?>
      <view xmlns="http://jmix.io/schema/flowui/view"
            extends="com/company/sample/view/customer/customer-list-view.xml">
          <layout>
              <dataGrid id="customersDataGrid">
                  <columns>
                      <column property="taxId"/>
                  </columns>
              </dataGrid>
          </layout>
      </view>

Для переопределений экранов статических сущностей поддерживается только descriptor.source — поля template, route, title и меню, используемые для экранов динамических сущностей, здесь не разрешены. Переопределение изменяет только дескриптор экрана: сгенерированный контроллер является подклассом существующего, поэтому исходный маршрут и существующее поведение экрана сохраняются.

Объявление экрана статической сущности также может содержать обработчики. Если нужно только добавить поведение существующему экрану, объявите обработчики без descriptor. В этом случае XML экрана не изменяется.