Dynamic Properties (динамические свойства)
Dynamic Properties (DPS) — это механизм описания динамических форм и наборов полей в be5.
DPS — упорядоченный набор именованных свойств, где каждое свойство имеет имя (name),
тип (type), значение (value) и произвольные атрибуты (атрибуты управляют внешним
видом, поведением и валидацией поля в интерфейсе).
DPS используются в be5 для:
описания параметров операций (полей формы операции) —
GOperationSupport.params;описания форм сущностей и запросов (наборы колонок) —
DpsHelper;представления результатов SQL-запросов —
QRec;моделирования «живых» строк БД —
RecordModel.
Базовый API предоставляют классы модуля beanexplorer/beans
(артефакт com.developmentontheedge:beans): интерфейс DynamicPropertySet,
реализации DynamicPropertySetSupport/GDynamicPropertySetSupport,
единичное свойство DynamicProperty и набор констант-атрибутов BeanInfoConstants.
Оглавление
Иерархия классов — основные классы DPS API и их назначения
Типы свойств (TYPE) — Java-классы значений, файловые типы, вложенные формы
Атрибуты свойств — все атрибуты: базовые, тег-списки, группировка, валидация, спецконтролы
Как задаются свойства — Groovy-DSL, мапы, Java builder, DpsHelper
Как атрибуты потребляются — сериализация в JSON, проверка значений
Иерархия классов
| Класс | Модуль | Назначение |
|---|---|---|
DynamicPropertySet |
beanexplorer/beans |
Интерфейс — контракт набора динамических свойств |
AbstractDynamicPropertySet |
beanexplorer/beans |
Абстрактная базовая реализация |
DynamicPropertySetSupport |
beanexplorer/beans |
Основная (каноническая) реализация: add, edit, remove, moveTo, asMap, build(name, class), makeBetterDisplayName и т.д. |
DynamicPropertySetAsMap |
beanexplorer/beans |
Реализация, хранимая в Map |
DynamicPropertySetDecorator / DynamicPropertySetBlocked |
beanexplorer/beans |
Декораторы; Blocked — read-only обёртка |
DynamicProperty |
beanexplorer/beans |
Одно свойство: name, type, value, displayName + атрибуты (setAttribute, getAttribute) |
DynamicPropertyBuilder |
beanexplorer/beans |
Java-fluent builder для создания DynamicProperty |
GDynamicPropertySetSupport |
be5/base (com.developmentontheedge.be5.groovy) |
Groovy-DSL поверх DynamicPropertySetSupport: add { name = ... }, add(name, displayName) { ... }, edit(name) { ... }, доступ dps[name] = значение, dps._name = объект свойства, with { ... }, << (мапа), + (объединение) |
QRec |
be5/database |
DPS-представление одной строки результата SQL; типизированные доступы getString, getInt, getLong, getDate |
RecordModelBase<T> / RecordModel<T> |
be5/database-model |
DPS, привязанный к строке БД: запись значения — через update(name, value) (через EntityModel), setValue запрещён |
Типы свойств (TYPE)
Тип (TYPE) свойства определяет класс Java, в который приводится значение поля.
По умолчанию — String.class. Тип сериализуется в JSON-мета как имя класса
(Class.getSimpleName()) и используется клиентским UI для выбора контрола ввода.
| Тип | Класс | UI (React) | Примечание |
|---|---|---|---|
String |
java.lang.String |
Текстовый <input> |
Тип по умолчанию; многострочный — через EXTRA_ATTRS = ["inputType": "textArea"] |
Boolean |
java.lang.Boolean |
Checkbox | При READ_ONLY — disabled, а не readonly |
Short |
java.lang.Short |
Числовой <input type="number"> |
В VALIDATION_RULES автоматически добавляется step |
Integer |
java.lang.Integer |
Числовой <input type="number"> |
В VALIDATION_RULES автоматически добавляется step; для INTEGER-колонок DpsHelper добавляет range |
Long |
java.lang.Long |
Числовой <input type="number"> |
Аналогично Integer |
Double |
java.lang.Double |
Числовой <input type="number"> |
Аналогично |
Date |
java.sql.Date |
Контрол даты (DateTimePropertyInput) |
|
Time |
java.sql.Time |
Контрол времени (DateTimePropertyInput) |
|
Timestamp |
java.sql.Timestamp |
Контрол даты+времени (DateTimePropertyInput) |
|
File |
java.io.File |
<input type="file"> (FilePropertyInput) |
Загрузка как multipart-файл; см. Файловые типы |
Base64File |
com.developmentontheedge.be5.server.model.Base64File |
<input type="file"> (Base64FilePropertyInput) |
Загрузка в base64-JSON; см. Файловые типы |
GDynamicPropertySetSupport |
com.developmentontheedge.be5.groovy.GDynamicPropertySetSupport |
Скрытое поле с JSON-строкой | Вложенная форма (группа полей); см. Вложенные формы |
любой другой Class |
произвольный | Текстовый <input> |
Значение парсится в нужный тип при приёме запроса (JsonFactory.getSimpleValueFromJson) |
2.1. Файловые типы
File — multipart-загрузка
Клиентский UI рендерит как <input type="file"> (FilePropertyInput).
Значение отправляется как настоящий multipart-файл (а не base64-JSON).
На сервере такие запросы обрабатываются через FileUploadWrapper (модуль web),
который превращает multipart в Map<String, List<FileItem>>.
params.add("attachment", "Файл") {
TYPE = File // java.io.File
}
Base64File — base64-JSON
Base64File (be5/server/.../server/model/Base64File.java) — специальный тип свойства
для полей загрузки файлов. Клиентский UI рендерит его как <input type="file">
(Base64FilePropertyInput, при READ_ONLY — disabled), а отправляемое значение — JSON:
{"type":"Base64File","name":"<имя файла>","data":"data:<mime>;base64,<base64-данные>"}
Серверная сторона распарсивает такие значения автоматически (ParseRequestUtils.checkAndParseBase64File),
поэтому в операции значение поля приходит уже как объект Base64File:
Base64File file = (Base64File) ((DynamicPropertySet) parameters).getValue("picture");
file.getName(); // имя файла
file.getMimeTypes(); // MIME-тип
file.getData(); // байты файла
Определение такого поля в Java:
dps.add(new DynamicProperty("picture", "Picture", Base64File.class));
или в Groovy:
params.add("picture", "Файл") {
TYPE = Base64File // com.developmentontheedge.be5.server.model.Base64File
}
Мультизагрузка файлов (для обоих типов) — MULTIPLE_SELECTION_LIST = true
(multiple в <input type="file">).
2.2. Вложенные формы
Типом свойства может быть сам GDynamicPropertySetSupport — в этом случае значение поля
является вложенной формой (группой полей). Клиентский UI рендерит такое поле как скрытое
текстовое поле, содержащее JSON-строку (сериализованный DPS).
Атрибуты свойств
Атрибуты задаются на конкретное свойство. Ключи атрибутов — константы интерфейса
BeanInfoConstants (модуль beanexplorer/beans). В Groovy-DSL константы доступны
по имени (TAG_LIST_ATTR, CSS_CLASSES, …), в Java — через строковые ключи
("tag-list-attr") или BeanInfoConstants.TAG_LIST_ATTR.
Важно. В Groovy-closure (
dps.add { ... }) доступны только те атрибуты, для которых определены setter“ы в классеDPSAttributes(be5/base/.../groovy/meta/DPSAttributes.java):name,DISPLAY_NAME,TYPE,value,READ_ONLY,HIDDEN,RAW_VALUE,RELOAD_ON_CHANGE,RELOAD_ON_CLICK,RELOAD_ON_FOCUS_OUT,CAN_BE_NULL,MULTIPLE_SELECTION_LIST,PASSWORD_FIELD,LABEL_FIELD,TAG_LIST_ATTR,EXTRA_ATTRS,VALIDATION_RULES,COLUMN_SIZE_ATTR,INPUT_SIZE_ATTR,PLACEHOLDER,GROUP_ID,GROUP_NAME,GROUP_CLASSES,GROUP_INITIALLY_CLOSED,TAB_ID,TAB_NAME,TAB_CLASSES,DEFAULT_VALUE,CSS_CLASSES,STATUS,MESSAGE. Через Java (DynamicProperty.setAttribute/DynamicPropertyBuilder.attr) можно задать любой атрибут изBeanInfoConstants.
3.1. Базовые атрибуты
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
DISPLAY_NAME |
displayName |
String |
Отображаемое имя поля (метка над полем) |
DEFAULT_VALUE |
defaultValue |
Object |
Значение по умолчанию, если getter возвращает null |
READ_ONLY |
read-only |
boolean |
Поле только для чтения |
HIDDEN |
node-hidden |
boolean |
Скрыть поле из интерфейса |
CAN_BE_NULL |
can-be-null |
boolean |
Поле допускает пустое значение |
RAW_VALUE |
raw-value |
boolean |
Вставлять значение в разметку без экранирования (например, HTML-лейблы) |
STATUS |
status |
String |
Статус валидации, отображаемый в UI (например, "error") |
MESSAGE |
message |
String |
Сообщение, сопутствующее STATUS |
HELP_ID |
help-id |
String |
Идентификатор контекстной помощи |
TOOLTIP |
tooltip |
String |
Подсказка (tooltip) поля |
ORDER |
properties-order |
Object |
Явный порядок свойств |
CHILD_DISPLAY_NAME |
childDisplayName |
String |
Метод/имя для расчёта display-name элементов массива |
CHILD_READ_ONLY |
child-read-only |
boolean |
Элементы массива — только для чтения |
FORMAT_MASK |
format-mask |
String |
Формат строки значения |
NUMBER_FORMAT |
number-format |
String/NumberFormat |
Формат чисел (DecimalFormat или паттерн); "none" — без форматирования |
PLACEHOLDER |
placeholder |
String |
Текст-заглушка в поле ввода |
3.2. Тег-списки и выпадающие
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
TAG_LIST_ATTR |
tag-list-attr |
String[][] / Map / Object[] |
Варианты для выпадающего списка. Формат: пары [значение, подпись] (String[][]), мапа значение→подпись или просто массив значений |
MULTIPLE_SELECTION_LIST |
multiple-selection-list |
boolean |
Мультивыбор (список чекбоксов) |
USE_AUTOCOMPLETE |
use-autocomplete |
boolean |
Рендерить поле как autocomplete |
USE_SELECT2 |
use-select2 |
boolean |
Рендерить поле как select2 |
USE_CHOSEN |
use-chosen |
boolean |
Рендерить поле как chosen |
DYNAMIC_TAG_LIST_ATTR |
dynamic-tag-list-attr |
Object |
Динамический источник тегов (загружается асинхронно) |
NO_TAG_LIST |
no-tag-list |
boolean |
Явно отключить список тегов |
NO_TAG_LIST_SHRINK_ATTR |
no-tag-list-shrink-attr |
boolean |
Не «схлопывать» поле без списка тегов |
EXTERNAL_TAG_LIST |
external-tag-list |
String |
Внешний источник тегов (таблица) |
ORIG_PROPERTY_ENTITY_ATTR |
origEntity |
String |
Имя сущности-источника внешнего списка |
ORIG_PROPERTY_NAME_ATTR |
origName |
String |
Имя колонки-источника внешнего списка |
SKIP_L10N |
skip-localization-attr |
boolean |
Не локализовать подпись поля |
SKIP_SERVER_NULL_CHECK |
skip-server-null-check |
boolean |
Не проверять null на сервере |
Типичный источник тегов для операций — QueriesService (поле queries в
OperationSupport):
queries.getTagsFromSelectionView(tableName[, params])— стандартный выборочный view;queries.getTagsFromCustomSelectionView(tableName, queryName[, params])— пользовательский query из метаданных;queries.getTagsFromEnum(tableName, name)/getTagsFromEnum(columnDef)— перечисление (enum) колонки.
Все методы возвращают String[][] (пары [значение, подпись]), готовую к присваиванию
TAG_LIST_ATTR.
3.3. Группировка и вкладки
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
GROUP_ID |
group-id |
String |
Идентификатор группы (сворачиваемая панель формы) |
GROUP_NAME |
group-name |
String |
Заголовок группы |
GROUP_CLASSES |
group-classes |
String |
CSS-классы панели группы |
GROUP_INITIALLY_CLOSED |
group-initially-closed |
boolean |
Группа свёрнута изначально |
GROUPING_PROPERTY |
grouping |
Object |
Значение свойства используется для группировки наборов бин-объектов |
TAB_ID |
tab-id |
String |
Идентификатор вкладки |
TAB_NAME |
tab-name |
String |
Заголовок вкладки |
TAB_CLASSES |
tab-classes |
String |
CSS-классы вкладки |
CSS_CLASSES |
css-classes |
String |
CSS-классы для контрола самого поля (например, col-lg-6) |
3.4. Размеры и форматирование
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
INPUT_SIZE_ATTR |
input-size-attr |
Integer |
Размер поля ввода (size) |
COLUMN_SIZE_ATTR |
column-size-attr |
Integer |
Ширина в колонках |
NCOLUMNS_ATTR |
cols-attr |
Integer |
Число колонок (например, для textarea) |
NROWS_ATTR |
rows-attr |
Integer |
Число строк (например, для textarea) |
3.5. Поведение формы
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
RELOAD_ON_CHANGE |
reload-on-change |
boolean |
Пересылать форму при изменении значения поля |
RELOAD_ON_CLICK |
reload-on-click |
boolean |
Пересылать форму по клику на поле |
RELOAD_ON_FOCUS_OUT |
reload-on-focus-out* |
boolean |
Пересылать форму при потере фокуса (*Groovy-only, не входит в BeanInfoConstants) |
3.6. Специальные контролы и видимость
EXTRA_ATTRS — свободные HTML/JS-атрибуты
EXTRA_ATTRS (extra-attrs-attr) — не фиксированный набор: произвольные пары
[ключ, значение], которые передаются в HTML-разметку контрола поля как есть.
Формат значения — Map или String[][], в JSON-мета сериализуется как extraAttrs
(список пар).
Служебный ключ inputType (константа PROPERTY_INPUT_TYPE, строковый ключ "inputType")
определяет тип контрола:
| Значение | Где применяется | Описание |
|---|---|---|
textArea |
DpsHelper автоматически для колонок TEXT |
Многострочное поле ввода |
AsyncSelect |
Задаётся вручную | Асинхронный выпадающий список: варианты загружаются по запросу. Требует дополнительных пар entity (сущность) и query (имя запроса) |
button |
Задаётся вручную | Поле-кнопка. При таком типе Validator пропускает null-проверку значения |
radio |
Задаётся вручную | Рендерит TAG_LIST_ATTR как radio-кнопки, а не select |
WYSIWYG |
Задаётся вручную | Rich-text редактор (WYSIWYGPropertyInput) |
| произвольное | Через registerPropertyInput(name, component) |
Зарегистрированный кастомный React-компонент |
JavaScript-обработчики: любые пары вида [onchange, js], [onclick, js]
подставляются в контрол как HTML-атрибуты с JS-выражением,
например ["onchange", "this.form.submit()"].
Примеры:
// Groovy — Map
params.add("request", "Заявка на закупку") {
EXTRA_ATTRS = ["inputType": "AsyncSelect", "entity": "testtable"]
}
// Groovy — обработчики
params.add("status", "Статус") {
EXTRA_ATTRS = ["onchange": "this.form.submit()"]
}
// Java — builder
dps.add(new DynamicPropertyBuilder("request", String.class)
.extraAttrs(Map.of("inputType", "AsyncSelect", "entity", "testtable"))
.onchange("this.form.submit()")
.get());
Кто потребляет EXTRA_ATTRS:
Клиентский UI (React) — читает
extraAttrsиз JSON-мета: рендерит контрол поinputType, остальные пары подставляет как HTML-атрибуты поля.Validator(модульoperation) — читаетinputTypeизEXTRA_ATTRS, чтобы пропустить null-проверку дляbutton.DpsHelper(модульserver) — сам выставляетEXTRA_ATTRSсinputType=textAreaдляTEXT-колонок.
Прочие специальные контролы
| Атрибут | Строковый ключ | Тип | Описание |
|---|---|---|---|
LABEL_FIELD |
label-field |
boolean |
Рендерить как обычный текстовый лейбл, а не ввод |
PASSWORD_FIELD |
password-field |
boolean |
Поле пароля |
BUTTON_FIELD |
button |
boolean |
Поле-кнопка |
RICH_TEXT |
rich-text |
boolean |
Rich-текст редактор |
COLOR_PICKER |
color-picker |
boolean |
Выбор цвета |
CUSTOM_INPUT_TYPE_ATTR |
custom-input-type-attr |
Object |
Произвольный тип ввода |
CUSTOM_EDITOR_ATTR |
custom-editor-attr |
Object |
Произвольный редактор поля |
PSEUDO_PROPERTY |
pseudo-property |
boolean |
«Псевдо»-свойство (служебное, не колонка БД) |
SKIP_SMART_BOOLEAN_TRUNC_ATTR |
skip-smart-boolean-trunc-attr |
boolean |
Не обрезать «умные» булевы значения |
NO_WRAP_LABELS |
no-wrap-labels-attr |
boolean |
Не переносить строки в лейблах |
SEMANTIC_RULES |
semantic-rules |
Object |
Семантические правила поля |
ARRAY_ITEM_TEMPLATE |
arrayItemTemplate |
Object |
Шаблон элемента массива |
3.7. Валидация значений
Правила валидации задаются атрибутом VALIDATION_RULES (validation-rules)
как список объектов ValidationRules.Rule
(модуль operation, класс com.developmentontheedge.be5.operation.validation.ValidationRules).
Каждое правило сериализуется в JSON-мета как {"type": "<имя>", "attr": <параметры>} и
проверяется и на клиенте (маска ввода, range/step для чисел), и на сервере
(Validator в модуле operation).
| Правило | Метод | JSON | Описание |
|---|---|---|---|
range |
ValidationRules.range(min, max) или range(min, max, customMessage) |
{"type":"range","attr":{"min":"...","max":"..."}} |
Значение в диапазоне [min, max] |
step |
ValidationRules.step(value) или step(value, customMessage) |
{"type":"step","attr":"..."} |
Шаг/точность значения (для чисел) |
pattern |
ValidationRules.pattern(regex) или pattern(regex, customMessage) |
{"type":"pattern","attr":"<regex>"} |
Регулярное выражение; на клиенте при наличии pattern-правила UI использует react-maskedinput с этой маской |
unique |
ValidationRules.unique(tableName), unique(tableName, column, message) |
{"type":"unique","attr":{"tableName":"..."}} |
Уникальность значения в указанной таблице (проверка на сервере) |
mask |
(встроенный клиентский) | {"type":"mask","attr":"<маска>"} |
Маска ввода на клиенте (react-maskedinput) |
Предопределённые правила — ValidationRules.DefaultRules, доступные по имени:
| Правило | Описание |
|---|---|
ipPattern |
IP-адрес по маске 255.255.255.255 (4 октета, каждая 0–255) |
Примеры:
// Groovy — closure
params.add("amount", "Сумма") {
TYPE = Integer
VALIDATION_RULES = [
ValidationRules.range(1, 1000),
ValidationRules.step(1),
ValidationRules.unique("documents", "id", "Значение уже существует")
]
}
// Java — builder
dps.add(new DynamicPropertyBuilder("amount", Integer.class)
.attr("validation-rules", Arrays.asList(
ValidationRules.range(1L, 1000L),
ValidationRules.step(1L)
))
.get());
Кто потребляет VALIDATION_RULES:
Клиентский UI (React) — читает
validationRulesиз JSON-мета:range/stepдляNumberPropertyInput,pattern→react-maskedinput,mask→ маска ввода.Validator(модульoperation) — серверная проверка: null-проверка (с учётомCAN_BE_NULLиBUTTON_FIELDвEXTRA_ATTRS),range,step,pattern,unique, статус/сообщение ошибки записываются вSTATUS/MESSAGE.DpsHelper(модульserver) — автоматически выставляетrange/stepдля числовых (INTEGER/DECIMAL) колонок при сборке DPS из модели.
3.8. Иконки (Swing-интроспекция)
| Атрибут | Строковый ключ | Описание |
|---|---|---|
NODE_ICON_COLOR_16x16 |
node-icon: color16x16 |
Иконка 16×16, цветная |
NODE_ICON_COLOR_32x32 |
node-icon: color32x32 |
Иконка 32×32, цветная |
NODE_ICON_MONO_16x16 |
node-icon: mono16x16 |
Иконка 16×16, монохромная |
NODE_ICON_MONO_32x32 |
node-icon: mono32x32 |
Иконка 32×32, монохромная |
Как задаются свойства
4.1. Groovy-DSL (основной способ в операциях)
В Groovy-операциях, наследующих GOperationSupport, поле params — это
GDynamicPropertySetSupport. Варианты add:
class MyOperation extends GOperationSupport implements Operation
{
Object getParameters(Map<String, Object> presetValues)
{
// 1) name задаётся внутри closure
params.add {
name = "request"
DISPLAY_NAME = "Заявка на закупку"
TAG_LIST_ATTR = queries.getTagsFromCustomSelectionView("documents", "Заявки на закупку")
CSS_CLASSES = "col-lg-6"
GROUP_ID = "purchase"
GROUP_NAME = "Закупка"
}
// 2) name и displayName — аргументы метода
params.add("beginDate", "Дата начала") {
TYPE = java.sql.Date
}
// 3) только name / name + displayName
params.add("reason", "Причина")
return DpsUtils.setValues(params, presetValues)
}
}
edit(name) { ... } — изменить атрибуты уже существующего свойства.
Доступ к значениям и свойствам:
def value = params["reason"] // значение свойства
def prop = params._reason // объект DynamicProperty
params.with { reason = "vacation" } // установка значения
4.2. Мапа (Groovy)
params << [
name : "reason",
DISPLAY_NAME : "Причина увольнения",
TAG_LIST_ATTR : [["fired", "Уволен"], ["vacation", "Отпуск"]] as String[][],
CAN_BE_NULL : true,
value : "vacation"
]
4.3. Java fluent builder
DynamicPropertySet dps = new DynamicPropertySetSupport();
dps.add(new DynamicPropertyBuilder("name", String.class)
.value("text")
.title("Имя")
.tags(new String[] { "one", "two", "three" })
.attr("css-classes", "col-lg-6")
.get());
Полезные методы builder“а: value, title, readonly, nullable, hidden, tags,
dynamicTags, multiple, attr, extraAttrs, onchange, onclick, placeholder,
reloadOnChange, reloadOnClick, columnSize, size, group(groupId, name),
tab(id, name), rawValue, inputType, autocomplete, select2, chosen,
external(tableFrom, col, tableTo), noServerCheck.
4.4. Автоматическая сборка из модели (DpsHelper)
Сервис DpsHelper (be5/server/.../services/DpsHelper.java) собирает DPS из метаданных
сущности: addDp, addDpForColumns, addDpExcludeAutoIncrement, addParamsFromQuery,
addLabel, addLabelRaw. Для каждой колонки автоматически выставляются
PLACEHOLDER, CAN_BE_NULL, EXTRA_ATTRS (например, textArea для TEXT),
COLUMN_SIZE_ATTR, VALIDATION_RULES (range/step для числовых типов), локализованное
DISPLAY_NAME, а addTags заполняет TAG_LIST_ATTR из enum“ов, yes-no значений и
выборочных view внешних ключей.
Как атрибуты потребляются
Атрибуты сериализуются в JSON-мета для клиентского UI через
JsonPropertyAttributes (модуль beanexplorer/json). JSON-ключи, которые видит клиент:
tagList, multipleSelectionList, canBeNull, readOnly, hidden, rawValue,
reloadOnChange, reloadOnClick, groupId / groupName / groupClasses /
groupInitiallyClosed, tabId / tabName / tabClasses, cssClasses, columnSize,
inputSize, placeholder, status / message, defaultValue, extraAttrs,
validationRules, labelField, passwordField.
Проверка значений при записи — DpsUtils (модуль database-model: поиск имени тега,
проверка принадлежности значения к списку тегов) и Validator (модуль operation).