Войти

Формат описания виджетов

Виджет — Самодостаточный визуальный компонент. В основе виджета лежит Wasaby-контрол, у которого описан набор настраиваемых свойств и контракт для работы с данными. Виджетами могут быть как простые компоненты (текст, кнопка), так и сложные (каталог продукции ресторана). Виджет может содержать внутри себя другие виджеты.

Виджет состоит из следующих частей:

  1. UI-компонент для отображения виджета в режиме просмотра(runtime);
  2. UI-компонент для отображения виджета в режиме редактирования (designtime);
  3. .widget файл, в котором содержится описание мета-информации, свойств виджета и механизмов работы с данными.

.widget файл должен содержать описание в формате json. Файлы должны располагаться в любой из папок сервисных модулей. Описание должно соответствовать следующему интерфейсу:

  1. id: string — уникальный идентификатор виджета. При именовании можно ориентироваться на правила, описанные в статье.

  2. info — мета информация о виджете, необходимая для отображения виджета в палитре/магазине виджетов.

    1. title: string — название виджета.
    2. description: string — подробное описание виджета.
    3. icon: string — иконка, которая будет отображена в палитре. svg файл, ссылка на cdn. Пример icon: "/cdn/MyModule/1.0.0/widgetIcon.svg".
    4. category: string — категория, к которой относиться виджет. Категория используется для группировки виджетов в магазине или палитре. Это поле не является логической группировкой (областью видимости) виджета и не пересекается с .widgetgroup-файлом. Поле несёт информативную нагрузку: пользователь совершает навигацию по человекопонятным категориям (например "Все о компаниях") и отыскивает нужный виджет.
    5. order: number - порядковый номер виджета в палитре, необходимый для организации порядка виджетов в палитре

  3. meta: object — информация, необходимая в местах использования виджета. Содержимое данного объекта не регламентируется. В данном поле должен содержаться объект с информацией, которая будет необходима в месте использования виджета. Например тип виджета для дашбодов, счетчик или обычный виджет. При этом если виджет используется не в дашбордах, эта информация не будет использоваться, но может использоваться другая информация, описанная в этом поле.

  4. rights: string[] — массив зон доступа, необходимых для использования виджета. При этом если виджет не доступен по правам, он все равно доступен в режиме конструирования, но в нем не отображаются данные. Для виджета нельзя задать уровень доступа к зоне: т.е. если зона доступна пользователю на чтение, то он будет доступен.

  5. rightmode: number — регулирует проверку вложенных зон доступа, а также правило доступа для нескольких зон: И или ИЛИ. Атрибут может принимать значения:

    1. 0 (по умолчанию) — проверка прав без учета вложенных зон доступа, доступ разрешен, если доступ есть хотя бы к одной зоне.
    2. 1 — проверка прав с учетом вложенных зон доступа, доступ разрешен, если доступ есть хотя бы к одной зоне.
    3. 10 — проверка прав без учета вложенных зон доступа, доступ разрешен, если есть доступ ко всем указанным зонам.
    4. 11 — проверка прав с учетом вложенных зон доступа, доступ разрешен, если есть доступ ко всем указанным зонам.
      Таким образом, старший разряд указывает, что для нескольких зон проверка будет осуществляться по правилу И (по умолчанию ИЛИ). А младший - учитывать или нет вложенные зон доступа.

  6. runtimeConfig — конфигурация виджета для отображения в режиме runtime:

    1. templateName: string — контрол, используемый для отображения виджета в режиме просмотра;
    2. sourceConfigGetter: string — путь до js метода, который вернет конфигурацию для загрузки данных. Подробнее об этом методе можно прочитать в статье.

  7. designtimeConfig — конфигурация виджета для отображения в режиме designtime.

    1. templateName: string — контрол, используемый для отображения виджета в режиме редактирования.
    2. sourceConfigGetter: string — путь до js метода, который вернет конфигурацию для загрузки данных. В режиме designtime должны грузиться только демо-данные, без запросов на БЛ. Подробнее об этом методе можно прочитать в статье.

  8. propTypes — свойства виджета, и конфигурация редакторов свойств, которые можно настроить с помощью PropertyGrid:

    1. name: string — название свойства.
    2. description: string — описание свойства.
    3. type: string — тип свойства. Подробнее про типы можно прочитать в разделе "Типизация свойств виджета".
    4. defaultValue: unknown — дефолтное значение.

    5. PGEditorConfig — настройки редактора свойства в PropertyGrid. Если поле не указано, то поле не редактируется в PropertyGrid.

      1. editorTemplateName: string — шаблон редактора, если не указать будет стандартный шаблон в зависимости от типа свойства.
      2. editorOptions: object — опции редактора свойства. Например items для редактора с типом select.
      3. group: string — человеко понятное название группы, в которой будет находиться свойство в PropertyGrid. Например “Шрифт”, “Отступы”
      4. order: number — порядок отображения в группе.
      5. visibilityCallback: string — путь до js метода, который вернет признак необходимости отображения редактора. В метод будет передан 1 параметр, со всеми текущими значениями свойств виджета.
      6. caption: string — заголовок редактора.
      7. captionPosition: string — положение заголовка редактора.
      8. sourceConfigGetter: string — путь до js метода, который вернет данные для редактора.

Пример:

{
    "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": "string",
            "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"
            }
        }
        {
            "name": "userExcludeCategory",
            "type": "object",
            "description": "Отображаемые категории",
            "defaultValue": {},
            "PGEditorConfig": {
                "editorTemplateName": "NoticeCenter/widgets:CategoryEditor",
                "sourceConfigGetter": "NoticeCenter/EditorLoader",
                "captionPosition": "none"
        }
    ]
}

Требования к виджету

  1. Нет асинхронности при построении верстки виджета
  2. Минимальное количество статических зависимостей у шаблонов виджета
  3. sourceConfigGetter должен лежать отдельно от интерфейса. Это необходимо чтобы запрос за данными выполнился максимально рано, не дожидаясь загрузки статики. Статика будет загружена параллельно с данными.

Локализация

Для локализации информации о виджетах и его свойствах, нужно создать словарь в корне модуля рядом с файлом .widget. В словаре нужно перечислить все поля, которые содержат русский текст. Методы БЛ при получении виджетов сами будут локализовать следующие поля:

  1. info.title
  2. info.description
  3. info.category
  4. propTypes.description
  5. propTypes.group
  6. propTypes.PGEditorConfig.group
  7. propTypes.PGEditorConfig.caption

Поддержка переключателей функционала

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

{
    "id": "notice-notifications",
    ...
    "feature": "loyalty_widgets"
}

Типизация свойств виджетов

У всех свойств виджетов есть обязательное поле type. В качестве типа свойства могут быть следующие значения:

  1. string — значение свойства является строкой.
  2. number — значение свойства является числом.
  3. boolean — значение свойства является логическим значением.
  4. date — значение свойства является датой.
  5. object — значение свойства является объектом.
  6. array — значение свойства является набором элементов.
  7. widget — виджетируемое свойство. Такие свойства используются в раскладках или любых виджетах, которые могут встраивать другие виджеты. Значение свойства содержит массив с результатами конструирования.

Группировка виджетов

Группа виджетов - Набор виджетов имеющих схожее предназначение. Например, виджеты полей ввода или виджеты редактора бонусных карт. Группа виджетов может включать в себя как индивидуальные виджеты, так и другие группы виджетов. Каждому конструктору соответствует своя группа виджетов (состоящая из вложенных групп), на основе которой строится палитра. Таким образом, при добавлении нового виджета его не нужно будет включать в каждую палитру вручную. Базовые группы виджетов будут поставляться платформой. Достаточно просто знать название группы (можно указать группу в своём .pagex-файле) и получить виджеты, соответствующие данной и дочерней групп. Т.е. группы -- это своего рода «области видимости» для виджетов. В палитре или магазине виджетов группа не отображается, служит только для технических целей.

Пример групп виджетов:

  1. base-output — "Заголовок", "Текст".
  2. base-media — "Изображение", "Видео", "Коллаж".
  3. base-input — "Текст", "Многострочный текст", "Число", "Дата", "Время", "Номер телефон", "Маска", "ФИО", "Выбор из справочника", "Чекбокс", "Радиокнопки".

Для создания группы виджетов нужно создать файл с расширением .widgetgroup (например BaseInput.widgetgroup) в любой из папок внутри сервисного модуля.

Файл .widgetgroup содержит следующие поля:

  1. id: string - уникальный идентификатор группы виджетов в формате uuid.
  2. name: string - название группы виджетов.
  3. widgets: object[] - массив виджетов, которые входят в группу.
  4. groups: object[] - массив подгрупп, которые входят в группу.

Каждый из элементов widgets и groups должен содержать 2 поля:

  1. id: string - уникальный идентификатор группы виджетов или виджета в формате uuid.
  2. 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"
   }]
}

Один виджет можно поместить в неограниченное количество групп.

Например, если в группы employees и ekd будет включен виджет ekd-reports, то он вернётся для каждой из групп employees, ekd и staff в единственном экземпляре:

// TypeScript
{
  "id": "cd903687-942b-4eed-8812-67f0b4d1d876",
  "name": "staff",
  "groups": [
    {
      "id": "9b04cd45-9b8c-472d-9b33-8040ca0603b0",
      "name": "employees"
    },
    {
      "id": "002c259a-537e-4c7b-b5ec-993002dc5724",
      "name": "ekd"
    }
  ]
}

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

© 2023 Тензор. Все права защищены.