Формат описания виджетов
Виджет — Самодостаточный визуальный компонент. В основе виджета лежит Wasaby-контрол, у которого описан набор настраиваемых свойств и контракт для работы с данными. Виджетами могут быть как простые компоненты (текст, кнопка), так и сложные (каталог продукции ресторана). Виджет может содержать внутри себя другие виджеты.
Виджет состоит из следующих частей:
UI
-компонент для отображения виджета в режиме просмотра(runtime
);UI
-компонент для отображения виджета в режиме редактирования (designtime
);.widget
файл, в котором содержится описание мета-информации, свойств виджета и механизмов работы с данными.
.widget
файл должен содержать описание в формате json
. Файлы должны располагаться в сервисных модулях. Описание должно соответствовать следующему интерфейсу:
- id:
string
— уникальный идентификатор виджета. При именовании можно ориентироваться на правила, описанные в статье. info — мета информация о виджете, необходимая для отображения виджета в палитре/магазине виджетов.
- title:
string
— название виджета. - description:
string
— подробное описание виджета. - icon:
string
— иконка, которая будет отображена в палитре.svg
файл, ссылка наcdn
. Примерicon
: "/cdn/MyModule/1.0.0/widgetIcon.svg". - category:
string
— категория, к которой относиться виджет. Например "Все о компаниях". Категория используется для группировки виджетов в магазине или палитре. - order:
number
- порядковый номер виджета в палитре, необходимый для организации порядка виджетов в палитре
- title:
meta:
object
— информация, необходимая в местах использования виджета. Содержимое данного объекта не регламентируется. В данном поле должен содержаться объект с информацией, которая будет необходима в месте использования виджета. Например тип виджета для дашбодов, счетчик или обычный виджет. При этом если виджет используется не в дашбордах, эта информация не будет использоваться, но может использоваться другая информация, описанная в этом поле.- rights:
string[]
— массив зон доступа, необходимых для использования виджета. При этом если виджет не доступен по правам, он все равно доступен в режиме конструирования, но в нем не отображаются данные. rightmode:
number
— регулирует проверку вложенных зон доступа, а также правило доступа для нескольких зон: И или ИЛИ. Атрибут может принимать значения:- 0 (по умолчанию) — проверка прав без учета вложенных зон доступа, доступ разрешен, если доступ есть хотя бы к одной зоне.
- 1 — проверка прав с учетом вложенных зон доступа, доступ разрешен, если доступ есть хотя бы к одной зоне.
- 10 — проверка прав без учета вложенных зон доступа, доступ разрешен, если есть доступ ко всем указанным зонам.
- 11 — проверка прав с учетом вложенных зон доступа, доступ разрешен, если есть доступ ко всем указанным зонам.
Таким образом, старший разряд указывает, что для нескольких зон проверка будет осуществляться по правилу И (по умолчанию ИЛИ). А младший - учитывать или нет вложенные зон доступа.
runtimeConfig — конфигурация виджета для отображения в режиме
runtime
:- templateName:
string
— контрол, используемый для отображения виджета в режиме просмотра; - sourceConfigGetter:
string
— путь доjs
метода, который вернет конфигурацию для загрузки данных. Подробнее об этом методе можно прочитать в статье.
- templateName:
designtimeConfig — конфигурация виджета для отображения в режиме
designtime
. Если не указано, то используетсяruntime
настройка.- templateName:
string
— контрол, используемый для отображения виджета в режиме редактирования. Если не указано, то используетсяruntime
настройка. - sourceConfigGetter:
string
— путь доjs
метода, который вернет конфигурацию для загрузки данных. Подробнее об этом методе можно прочитать в статье.
- templateName:
propTypes — свойства виджета, и конфигурация редакторов свойств, которые можно настроить с помощью
PropertyGrid
:- name:
string
— название свойства. - description:
string
— описание свойства. - type:
string
— тип свойства. Подробнее про типы можно прочитать в разделе "Типизация свойств виджета". - defaultValue:
unknown
— дефолтное значение. PGEditorConfig — настройки редактора свойства в
PropertyGrid
. Если поле не указано, то поле не редактируется вPropertyGrid
.- editorTemplateName:
string
— шаблон редактора, если не указать будет стандартный шаблон в зависимости от типа свойства. - editorOptions:
object
— опции редактора свойства. Напримерitems
для редактора с типомselect
. - group:
string
— человеко понятное название группы, в которой будет находиться свойство вPropertyGrid
. Например “Шрифт”, “Отступы” - order:
number
— порядок отображения в группе. - visibilityCallback:
string
— путь доjs
метода, который вернет признак необходимости отображения редактора. В метод будет передан 1 параметр, со всеми текущими значениями свойств виджета. - caption:
string
— заголовок редактора.
- editorTemplateName:
- name:
Пример:
// TypeScript
{
"id": "notice-notifications",
"info": {
"title": "Заголовок",
"description": "Описание",
"icon": "/cdn/MyModule/1.0.0/widgetIcon.svg"
},
"runtimeConfig": {
"templateName": "Path/To/RuntimeTemplate",
"sourceConfigGetter": "Path/To/runtimeSourceConfigGetter"
},
"designtimeConfig": {
"templateName": "Path/To/DesigntimeTemplate",
"sourceConfigGetter": "Path/To/designtimeSourceConfigGetter"
},
"propTypes": [
{
"name": "font",
"type": "number",
"description": "Подробное описание свойства",
"PGEditorConfig": {
"group": "ШРИФТ",
"caption": "Шрифт",
"editorOptions": {
"value": ["TensorFont", "Courier New", "Arial"]
},
"editorTemplateName": "Path/To/FontEditorTemplate"
}
},
{
"name": "size",
"type": "number",
"description": "Очень подробное описание свойства",
"PGEditorConfig": {
"group": "ШРИФТ",
"caption": "Размер шрифта",
"editorOptions": {
"value": [14, 16, 18]
},
"editorTemplateName": "Path/To/SizeEditorTemplate"
}
}
]
}
Требования к виджету
- Нет асинхронности при построении верстки виджета
- Минимальное количество статических зависимостей у шаблонов виджета
- sourceConfigGetter должен лежать отдельно от интерфейса. Это необходимо чтобы запрос за данными выполнился максимально рано, не дожидаясь загрузки статики. Статика будет загружена параллельно с данными.
Локализация
Для локализации информации о виджетах и его свойствах, нужно создать словарь в корне модуля рядом с файлом .widget.
В словаре нужно перечислить все поля, которые содержат русский текст. Методы БЛ при получении виджетов сами будут локализовать следующие поля:
info.title
info.description
info.category
propTypes.description
propTypes.group
Поддержка переключателей функционала
В конфигурации виджета можно указать необязательное поле feature
типа строка. Тогда виджет пройдет проверку и будет доступен в магазине виджетов только пользователям, у которых включен соответствующий переключатель функционала.
{
"id": "notice-notifications",
...
"feature": "loyalty_widgets"
}
Типизация свойств виджетов
У всех свойств виджетов есть обязательное поле type. В качестве типа свойства могут быть следующие значения:
string
— значение свойства является строкой.number
— значение свойства является числом.boolean
— значение свойства является логическим значением.date
— значение свойства является датой.object
— значение свойства является объектом.array
— значение свойства является набором элементов.widget
— виджетируемое свойство. Такие свойства используются в раскладках или любых виджетах, которые могут встраивать другие виджеты. Значение свойтсва содержит массив с результатами констрирования.
Группировка виджетов
Группа виджетов - Набор виджетов имеющих схожее предназначение. Например, виджеты полей ввода или виджеты редактора бонусных карт. Группа виджетов может включать в себя как индивидуальные виджеты, так и другие группы виджетов. Каждому конструктору соответствует своя группа виджетов (состоящая из вложенных групп), на основе которой строится палитра. Таким образом, при добавлении нового виджета его не нужно будет включать в каждую палитру вручную. Базовые группы виджетов будут поставляться платформой.
Пример групп виджетов:
base-output
— "Заголовок", "Текст".base-media
— "Изображение", "Видео", "Коллаж".base-input
— "Текст", "Многострочный текст", "Число", "Дата", "Время", "Номер телефон", "Маска", "ФИО", "Выбор из справочника", "Чекбокс", "Радиокнопки".
Для создания группы виджетов нужно создать файл с расширением .widgetgroup
(например BaseInput.widgetgroup
).
Файл .widgetgroup
содержит следующие поля:
- id:
string
- уникальный идентификатор группы виджетов в формате uuid. - name:
string
- название группы виджетов. - widgets:
object[]
- массив виджетов, которые входят в группу. - groups:
object[]
- массив подгрупп, которые входят в группу.
Каждый из элементов widgets и groups должен содержать 2 поля:
- id:
string
- уникальный идентификатор группы виджетов или виджета в формате uuid. - name:
string
- название группы виджетов или виджета.
Пример объявления группы виджетов в файле base-output.widgetgroup
:
// TypeScript
{
"id": "f24dcd35-03c0-40f7-bafd-55e80c02b944",
"name": "base-output",
"widgets": [{
"id": "notice-notifications"
}, {
"id": "notice-holidays"
}],
"groups": [{
"id": "99c65c7a-84ce-11ec-a8a3-0242ac120002",
"name": "BaseImageWidgets"
}]
}
Для отображения виджетов на странице разработаны два контрола: плеер и конструктор, подробнее о которых можно прочитать здесь.