Аспекты

Аспект — механизм расширения функционала типа данных. Он позволяет переиспользовать определения атрибутов, форму конфигурации и связанное поведение, не копируя их в каждый тип. При подключении аспекта его атрибуты включаются в итоговую модель типа.

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

Атрибуты аспекта доступны через префикс в формате {prefix}:{attribute.id}, что позволяет однозначно идентифицировать их в формах, журналах, конфигурациях действий и мутациях записей.

В Citeck представлены системные аспекты для типовых задач:

  • учёт времени;

  • управление связями между документами;

  • генерация штрихкода;

  • конфигурация истории событий;

  • импорт данных;

  • обработка активностей.

Журнал аспектов доступен по адресу: v2/journals?journalId=ecos-aspects&viewMode=table&ws=admin$workspace

Изменение определения аспекта через API доступно под SYSTEM или ADMIN. Эти права следует отличать от прав на изменение значений атрибутов и подключение аспекта к конкретной записи.

Модель аспекта

id: String // Идентификатор аспекта
name: MLText // Имя аспекта (справочная информация)
prefix: String // Префикс аспекта. Будет добавляться перед идентификатором каждого атрибута, которые описаны в attributes и systemAttributes
configFormRef: EntityRef // Ссылка на форму, которую следует использовать для редактирования конфигурации аспекта в типе ECOS
attributes: List<AttributeDef> // Атрибуты аспекта, которые будут добавлены к сущностям с данным аспектом
systemAttributes: List<AttributeDef> // Системные атрибуты аспекта, которые будут добавлены к сущностям с данным аспектом. Системные атрибуты могут быть изменены только под пользователем system.

В конфигурации типа предусмотрено поле aspects, которое содержит список аспектов и их конфигурацию:

TypeDef
...
aspects: List<TypeAspectDef>
...

TypeAspectDef
ref: EntityRef // ссылка на аспект
config: ObjectData // конфигурация аспекта
inheritConfig: Boolean // использовать конфигурацию родительского типа как основу

Наследование

Дочерний тип наследует аспекты родительского типа. Если тот же аспект объявлен в дочернем типе повторно, при inheritConfig: true основой становится конфигурация родительского объявления. Иначе основой служит конфигурация по умолчанию аспекта. Затем ключи собственной config переопределяют ключи основы. Слияние выполняется по верхнему уровню: вложенный объект заменяется целиком.

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

Ограничения имён

Идентификатор аспекта должен соответствовать выражению ^[\w-]+$. Если prefix пустой, используется идентификатор аспекта. Эффективный префикс должен быть уникален среди аспектов.

Полное имя атрибута prefix:attributeId должно соответствовать выражению [\w-_:]+: допускаются латинские буквы, цифры, подчёркивание, дефис и двоеточие. Для атрибутов, сохраняемых как столбцы, длина полного имени ограничена 63 байтами UTF-8, включая префикс и двоеточие. Атрибуты, не сохраняемые как столбцы, освобождены от ограничения длины, но проверка допустимых символов остаётся.

В штатной форме id и prefix доступны при создании и заблокированы при редактировании. При изменении префикса через API проверяются полные имена уже заданных атрибутов.

API

Проверить наличие аспекта у сущности

await Records.get('emodel/some-id@local-id').load('_aspects._has.aspectToTest?bool!')

где,

emodel/some-id@local-id - идентификатор сущности, у которой мы хотим проверить наличие аспекта

aspectToTest - идентификатор аспекта, наличие которого мы проверяем

Получить конфигурацию аспекта типа

await Records.get('emodel/some-id@local-id').load('_type.aspectById.you-aspect-id.config?json')

Запрос через _type возвращает конфигурацию аспекта в типе указанной сущности. Вместо you-aspect-id подставьте идентификатор аспекта.

Добавить аспект к сущности

Для явного добавления аспекта к записи передайте его идентификатор в att_add__aspects:

var rec = Records.get('emodel/some-id@local-id');
rec.att('att_add__aspects', 'aspectToAdd');
await rec.save();

где,

emodel/some-id@local-id - идентификатор сущности, к которой мы хотим добавить аспект

aspectToAdd - идентификатор аспекта, который мы добавляем

Удаление аспекта

var rec = Records.get('emodel/some-id@local-id');
rec.att('att_rem__aspects', 'aspectToRemove');
await rec.save();

где,

emodel/some-id@local-id - идентификатор сущности, у которой мы хотим удалить аспект

aspectToRemove - идентификатор аспекта, который мы удаляем.

Эти операции изменяют набор аспектов конкретной записи. Для изменения аспектов, подключённых через тип, редактируйте конфигурацию типа с учётом наследования.

Описание работы с аспектами с точки зрения пользователя (без программирования) приведено в разделе Аспекты.