Управление динамическими атрибутами - Платформа CUBA. Руководство по разработке приложений

3.9.1.1. Управление динамическими атрибутами

Управление категориями и описаниями атрибутов осуществляется с помощью экрана Administration → Dynamic Attributes. Данный экран отображает список категорий слева и список атрибутов выбранной категории справа.

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

Для того чтобы изменения в атрибутах и настройках видимости вступили в силу, необходимо нажать кнопку Применить изменения на экране со списком категорий. Изменения также можно применить через Administration → JMX Console, вызвав метод clearDynamicAttributesCache() JMX бина app-core.cuba:type=CachingFacade.

Ниже приведен пример экрана редактирования категории:

Рисунок 32. Экран редактирования категории

Секция Name localization отображается на экране редактирования категории, если приложение поддерживает более одного языка, и позволяет задать локализованное значение имени категории для каждой доступной локали.

Рисунок 33. Локализация имени категории

На вкладке Attributes Location вы можете настроить расположение каждого динамического атрибута внутри DynamicAttributesPanel.

Рисунок 34. Настройка расположения атрибутов

Укажите количество колонок в выпадающем списке Columns count. Перетащите атрибут из списка атрибутов в нужный столбец и нужную строку. Вы можете добавлять пустые ячейки и менять порядок отображения атрибутов. После внесения изменений нажмите на кнопку Save configuration.

Расположение атрибутов на панели DynamicAttributesPanel в редакторе сущности:

Редактор динамического атрибута позволяет задать имя, системный код, описание, тип значения, значение атрибута по умолчанию и скрипт валидации.

Рисунок 35. Редактор динамического атрибута

Для всех типов значения, кроме Boolean, доступно поле Width, позволяющее задать ширину поля в Form в пикселах или процентах. Если поле Width не заполнено, его значение по умолчанию равно 100%.

Для всех типов значения, кроме Boolean, также доступен чекбокс Is collection. Он позволяет создавать динамические атрибуты выбранного типа со множеством значений.

Для всех числовых типов значений: Double, Fixed-point number, Integer – доступны следующие поля:

Minimum value – при вводе значения атрибута просходит проверка, что значение должно быть больше или равно указанному минимальному значению.
Maximum value – при вводе значения атрибута просходит проверка, что значение должно быть меньше или равно указанному максимальному значению.

Для типа значения Fixed-point number доступно поле Number format pattern, в котором можно задать паттерн форматирования. Паттерн задается по правилам, описанным в DecimalFormat.

Для всех типов значений есть возможность указать скрипт валидации в поле Validation script для проверки значения, введенного пользователем. Логика валидации задается в скрипте Groovy. В случае неуспешной валидации Groovy скрипт должен вернуть сообщение об ошибке. В противном случае скрипт не должен возвращать ничего или может вернуть null. Проверяемое значение доступно в скрипте в переменной value. Для сообщения об ошибке используется Groovy строка, ключ $value может быть использован в сообщении для формирования результата.

Пример:

if (!value.startsWith("correctValue")) return "the value '\$value' is incorrect"

Для типа значения Enumeration множество значений перечисления задаётся в поле Enumeration в редакторе списка.

Рисунок 36. Редактор динамического атрибута для типа значений Enumeration

Каждое значение перечисления может быть локализовано на языки, доступные в приложении:

Рисунок 37. Локализация динамического атрибута для типа значений Enumeration

Для типов данных String, Double, Entity, Fixed-point number и Integer доступен чекбокс Lookup field. Если данный чекбокс установлен, то пользователь может выбирать значение атрибута из выпадающего списка. Список допустимых значений можно настроить на вкладке Calculated values and options. Для типа данных Entity настраиваются условия Where и Join.

Рассмотрим вкладку Calculated values and options. В поле Attribute depends on вы можете указать, от каких атрибутов зависит текущий атрибут. При изменении значения одного из этих атрибутов будет пересчитан либо скрипт для вычисления значения атрибута, либо скрипт для вычисления списка возможных значений.

Groovy скрипт для вычисления значения атрибута задается в поле Recalculation value script. Скрипт должен возвращать новое значение параметра. В скрипт передаются следующие переменные:

entity – редактируемая сущность;
dynamicAttributes – мэп, где key – код атрибута, value – значение динамического атрибута.

Рисунок 38. Скрипт пересчета значения

Пример скрипта пересчета значения, использующего мэп dynamicAttributes:

if (dynamicAttributes['PassengerNumberofseats'] > 9) return 'Bus' else return 'Passenger car'

Скрипт выполняется каждый раз после изменения значения одного из атрибутов, от которых зависит данный атрибут.

Если скрипт задан, то поле ввода для атрибута будет нередактируемым.

Пересчет значения атрибута работает только со следующими UI-компонентами: Form, DynamicAttributesPanel.

Поле Options type определяет тип загрузчика опций и является обязательным для заполнения, если на вкладке General был установлен чекбокс Lookup field. Если чекбокс не был установлен, то поле Options type является недоступным для заполнения.

Доступные типы загрузчика опций: Groovy, SQL, JPQL (только для типа данных Entity).

Загрузчик опций Groovy загружает список значений, используя скрипт Groovy. В скрипт передается переменная entity, по которой можно получить доступ к атрибутам сущности (включая динамические атрибуты). Пример скрипта для атрибута типа String:

Рисунок 39. Скрипт для загрузчика опций Groovy
Загрузчик опций SQL загружает список значений, используя скрипт SQL. Вы можете получить доступ к идентификатору сущности, используя переменную ${entity}. Чтобы получить доступ к параметрам сущности, используйте конструкцию ${entity.<field>}, где field – имя параметра сущности. Для доступа к динамическим атрибутам сущности используется префикс +, например, ${entity.+<field>}. Пример скрипта (здесь мы получаем доступ к сущности и динамическому атрибуту Categorytype):
```
select name from DYNAMICATTRIBUTESLOADER_TAG
where CUSTOMER_ID = ${entity}
and NAME = ${entity.+Categorytype}
```
Загрузчик опций JPQL применяется только для динамического атрибута типа Entity. JPQL условия задаются в полях Join Clause и Where Clause. Кроме того вы можете воспользоваться мастером созданий ограничений (Constraint Wizard). Мастер позволяет визуально задавать JPQL условия. В параметрах JPQL можно использовать переменные {entity} и {entity.<field>}.

Для всех типов значения поддерживается локализация имени атрибута на вкладке Localization:

Рисунок 40. Локализация динамического атрибута

Видимость атрибутов

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

Рисунок 41. Настройки видимости динамического атрибута

Кроме экрана можно также указать компонент, в котором атрибут должен появляться (например, для экранов, где несколько компонентов Form показывают поля одной и той же сущности).

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

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

Динамические атрибуты можно добавить в экран вручную. Для этого необходимо добавить атрибут dynamicAttributes="true" загрузчику сущности и использовать код динамического атрибута с префиксом + при привязке UI-компонентов к данным:

<data>
    <instance id="carDc" class="com.company.app.entity.Car" view="_local">
        <loader id="carDl" dynamicAttributes="true"/>
    </instance>
</data>
<layout>
    <form id="form"
          dataContainer="carDc">
        <!--...-->
        <textField property="+PassengerNumberofseats"/>
    </form>