UI Constraints

Дополнение UI Constraints позволяет управлять видимостью и доступностью компонентов пользовательского интерфейса с помощью декларативных политик, определенных в ресурсных ролях.

Например, кнопку можно сделать неактивной, таблицу данных скрыть и так далее.

Любой UI-компонент или действие может управляться через UI Constraints, даже если компонент не связан с моделью данных и не зависит от операций с сущностями и политик атрибутов сущности. Единственное условие — у компонента должен быть ID.

Данная функциональность избавляет от необходимости писать код для анализа ролей пользователя или конкретных разрешений и управления состоянием компонентов в экранах приложения. Она также позволяет точно настраивать управление доступом во время выполнения, редактируя роли в экранах Security → Resource roles.

Установка

Это дополнение требует Enterprise подписки. Если у вас нет подписки, см. раздел Enterprise Trial, чтобы узнать, как получить пробную версию.

Для автоматической установки через Jmix Marketplace следуйте инструкциям в разделе Дополнения.

Для ручной установки выполните следующие шаги.

Настройте доступ к премиум-репозиторию.
- Добавьте премиум-репозиторий в свой build.gradle:
  repositories { // ... maven { url = 'https://global.repo.jmix.io/repository/premium' credentials { username = rootProject['premiumRepoUser'] password = rootProject['premiumRepoPass'] } } }
- Добавьте учетные данные премиум-репозитория в ~/.gradle/gradle.properties:
  premiumRepoUser=123456123456 premiumRepoPass=abcdefabcdef
  Получите учетные данные репозитория из вашего лицензионного ключа: первая часть ключа перед тире – это имя пользователя репозитория, часть после тире – пароль. Например, если ваш ключ выглядит как 123456-abcdef abcdef, имя пользователя – 123456, а пароль – abcdef abcdef.

Добавьте зависимости в build.gradle:

implementation 'io.jmix.uiconstraints:jmix-uiconstraints-starter'

Использование

Дополнение UI Constraints предоставляет UI component policies (политики компонентов UI), которые можно указать в ресурсных ролях как на этапе разработки с использованием аннотированных Java-интерфейсов, так и во время выполнения через экраны управления ролями.

Аннотация @UiComponentPolicy, используемая в Java-интерфейсах, описана ниже.

Редактор ролей времени выполнения доступен через основной пункт меню Security → Resource roles. После включения дополнения UI Constraints в проект, выпадающий список политик будет содержать элемент UI component policy:

Редактор политик компонентов UI позволяет указать целевой экран, выбрать существующие компоненты из выпадающего списка и задать действие политики и эффект:

В отличие от политик сущностей и атрибутов сущностей, политика компонентов UI является «запрещающей», то есть она может сделать компонент интерфейса или действие только менее видимыми или доступными, чем они были до применения политики. Например, если атрибут сущности виден благодаря политике атрибута сущности, политика компонента UI может сделать соответствующий компонент интерфейса невидимым, если указано действие VISIBLE с эффектом DENY. Дополнительная информация об эффектах приведена ниже.

Политики компонентов UI применяются в конце процесса открытия экрана, после отправки ReadyEvent. К этому моменту инициализация экрана завершена и другие политики применены.

Аннотация UiComponentPolicy

Аннотация @UiComponentPolicy позволяет определять политики компонентов UI в интерфейсах ресурсных ролей на этапе разработки.

Пример:

package com.company.demo.security;

import com.company.demo.view.customer.CustomerDetailView;
import com.company.demo.view.customer.CustomerListView;
import io.jmix.security.role.annotation.ResourceRole;
import io.jmix.uiconstraints.annotation.UiComponentPolicy;
import io.jmix.uiconstraints.annotation.UiComponentPolicyAction;
import io.jmix.uiconstraints.annotation.UiComponentPolicyEffect;

@ResourceRole(name = "EmployeeRole", code = EmployeeRole.CODE, scope = "UI")
public interface EmployeeRole {
    String CODE = "employee-role";

    @UiComponentPolicy(
            viewClass = CustomerListView.class,
            componentIds = {"customersDataGrid.importCustomersAction"},
            action = UiComponentPolicyAction.ENABLED,
            effect = UiComponentPolicyEffect.DENY
    )
    @UiComponentPolicy(
            viewClass = CustomerDetailView.class,
            componentIds = {"commentsPane"},
            action = UiComponentPolicyAction.VISIBLE,
            effect = UiComponentPolicyEffect.DENY
    )
    void customers();
}

Атрибуты аннотации @UiComponentPolicy описаны ниже.

viewClass и viewId

Политика компонента UI определяется для компонентов внутри экрана. Экран может быть указан либо атрибутом viewClass, либо атрибутом viewId.

componentIds

Каждая аннотация @UiComponentPolicy может определять политики для одного или нескольких компонентов экрана. Их идентификаторы должны быть перечислены в атрибуте componentIds. Политика может применяться к компонентам следующих типов:

Визуальный компонент (textField, button, vbox, div и др.) на данном экране. Например: firstNameField, importButton.
Действие, принадлежащее данному экрану. Например: save.
Действие, принадлежащее компоненту экрана. Например: userGrid.edit.
Компонент или действие, находящееся внутри фрагмента. Например: addressFragment.cityField.

action

Политика компонента UI поддерживает два типа действий:

VISIBLE — управляет видимостью компонента.
ENABLED — управляет доступностью компонента. Если компонент поддерживает состояние только для чтения, он будет установлен в состояние «только для чтения». В противном случае компонент будет отключен (disabled).

effect

Атрибут effect может иметь два значения: ALLOW и DENY.

По умолчанию, если политики компонентов UI не применены, все UI-компоненты на экране имеют свое начальное состояние видимости и доступности. Компоненты, связанные с данными, видимы и доступны, если существует соответствующая политика атрибута сущности.

Если в политике компонента интерфейса указан эффект DENY, это скрывает или отключает UI-компонент или действие. Это стандартный случай использования политики компонента UI.

Эффект ALLOW можно использовать, если требуется переопределить эффект другой политики компонента UI, примененной к тому же компоненту другой ролью. Например, если пользователю уже назначена роль А, и эта роль запрещает доступ к определенному компоненту интерфейса, использование роли B с эффектом ALLOW восстановит доступ к этому компоненту.

Эффект ALLOW не может отобразить или включить компонент, который был скрыт или отключен в его начальном состоянии или из-за отсутствия разрешающей политики сущности или атрибута сущности.