Собственный тип

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

1. Начните со смысла элемента: что это за часть страницы и почему её нельзя собрать из встроенных типов.
2. Опишите тип в манифесте: данные, настройки, слоты, варианты оформления, рендерер, ресурсы.
3. Зарегистрируйте рендерер с тем же именем.
4. Добавьте правильный контрольный пример и ошибочный — например, с неизвестным слотом и опасной ссылкой — и убедитесь, что второй отклоняется.
5. Подключайте пример в документацию из того же проверенного файла.

Правила:

• общий тип создают в репозитории Framework, предметный тип — в контролируемом расширении проекта;
• нельзя помещать рендерер и произвольный код внутрь документа.

Пример: сетка товаров

Тип project.product-grid разрешает слот items, пресет cards и ресурс project/product-grid. Его манифест имеет формат simai.composition.type-manifest (Манифест типа). Контрольный пример доказывает порядок карточек, а отрицательный — что неизвестный слот и опасная ссылка отклоняются.

1. Опишите project.product-grid в манифесте.
2. Зарегистрируйте рендерер с тем же именем.
3. Добавьте правильный контрольный пример с двумя карточками.
4. Добавьте пример с неизвестным слотом и убедитесь, что проверка его отклоняет.
5. Подключите пример к документации из проверенного файла.

Регистрация типа

Тип регистрируется в реестре вместе с рендерером. SF.Composition.extendRegistry(manifests, renderers) создаёт реестр из встроенных типов (layout.page, layout.columns, content.paragraph и других) и ваших. Ключ в renderers — имя из renderer.name в манифесте.

const registry = SF.Composition.extendRegistry(
  [productGridManifest],
  {
    'project.product-grid': ({node, slots}) =>
      `<div class="project-product-grid" data-sf-composition-id="${node.id}">${slots.items}</div>`,
  },
);

const {html, diagnostics} = await SF.Composition.render(compositionDocument, {registry});

Рендерер получает объект с полями:

• node — проверенный узел;
• slots — готовый HTML слотов: строкой по имени слота и массивом в slots.<имя>List;
• manifest — манифест типа;
• context — контекст render();
• resolvedBindings — результаты resolveBinding по полю target привязки.

Рендерер возвращает строку HTML. Готовый HTML слотов уже безопасен, а данные и настройки узла рендерер экранирует сам: Framework вставляет его результат как есть. Атрибут data-sf-composition-id рендерер собственного типа добавляет сам, если узел нужно выбирать в редакторе (в примере id вставлен без экранирования, потому что схема разрешает в нём только латинские буквы, цифры, ., _, : и -; текстовые данные узла так вставлять нельзя). Ошибки документа приходят в diagnostics, а не исключением.

SF.Composition.createRegistry(manifests, renderers) берёт список как весь реестр: встроенных типов в нём нет. Он подходит для теста одного типа. Список встроенных типов доступен как SF.Composition.BUILTIN_TYPE_MANIFESTS.