Что такое макет

Макет — способ описать страницу структурой, а не HTML-разметкой. Он даёт одну проверяемую запись страницы, которую одинаково понимают сервер, браузер, редактор и ИИ.

Определение

Макет — это описание страницы в JSON: из каких частей она состоит, как они вложены друг в друга и в каком порядке идут. Готовый макет — документ формата simai.composition.document с "schema_version": 1 рядом; прежняя метка simai.composition.document.v1 тоже принимается — так помечен, например, документ, собранный из рецепта в прежней форме (см. Имена и версии). В нём хранятся типы элементов, их настройки и содержимое. Framework проверяет документ и превращает его в безопасный HTML.

Главный принцип: одна запись — одна и та же страница везде. Сервер, браузер, редактор, генератор документации и ИИ работают с одним и тем же документом и по одним правилам. Одинаковый документ даёт одинаковую нормализованную форму и одинаковый отпечаток (SHA-256) в Node.js, в браузере и в PHP-проверке. Поэтому результат можно кешировать, сравнивать и воспроизводить.

Какие задачи решает

• Страница отделена от разметки. Исходные данные страницы — структура. HTML получают в конце, из структуры.
• Страницу можно собрать в системе управления сайтом. Редактор страниц переставляет секции и правит текст, а не HTML-строки.
• Одна страница — разные варианты. Настройка сайта выбирает, например, краткую или расширенную шапку, а сборщик раскрывает только выбранную ветвь.
• Проверка до показа. Неизвестный тип, неверный слот, опасная ссылка или превышение лимита находятся до того, как страница попадёт к посетителю.
• Машинное описание. Макет пригоден для генерации и проверки ИИ: каждое поле объявлено в схеме, придумать «удобное» поле нельзя.

Пример: каталог

Каталог можно представить как страницу, внутри которой секция с заголовком, вводным абзацем и колонками для фильтров и товаров. JSON отвечает на вопрос «что показать», Framework — «как проверить и отрисовать», а проект загружает товары и решает, что доступно посетителю.

{
  "schema": "simai.composition.document",
  "schema_version": 1,
  "id": "catalog-page",
  "profile": "ui-layout",
  "locale": "ru",
  "root": {
    "id": "page",
    "type": "layout.page",
    "slots": {
      "default": [
        {
          "id": "catalog",
          "type": "layout.section",
          "presentation": {"preset": "surface", "modifiers": ["contained"]},
          "bindings": [{"owner": "project/catalog", "ref": "products", "target": "items", "revision": "42"}],
          "slots": {
            "default": [
              {"id": "title", "type": "content.heading", "data": {"level": 1, "content": [{"type": "text", "value": "Каталог товаров"}]}},
              {"id": "lead", "type": "content.paragraph", "data": {"content": [{"type": "text", "value": "Framework показывает макет, а проект получает товары и проверяет права."}]}},
              {
                "id": "columns",
                "type": "layout.columns",
                "props": {"columns": 2},
                "presentation": {"modifiers": ["responsive"]},
                "slots": {"columns": [
                  {"id": "filters", "type": "content.paragraph", "data": {"content": [{"type": "text", "value": "Фильтры"}]}},
                  {"id": "products", "type": "content.paragraph", "data": {"content": [{"type": "text", "value": "Карточки товаров"}]}}
                ]}
              }
            ]
          }
        }
      ]
    }
  }
}

Чего в макете нет

Макет отвечает на вопрос «что показать». Он не содержит:

• HTML, JavaScript, PHP, SQL, запросов и выражений;
• произвольных CSS-классов — только зарегистрированные варианты оформления;
• секретов: паролей, токенов, cookie, заголовков авторизации;
• решений о правах доступа и бизнес-правил.

Это правило проверки: ключи вроде html, script, class, query, sql, token, password отклоняются в любом месте документа с кодом executable_or_secret_field_forbidden.

Когда макет не нужен

Обычную неизменяемую страницу можно написать HTML вручную, пользуясь компонентами и утилитами (Утилиты и раскладка и Компоненты). Макет окупается, когда структуру страницы нужно хранить отдельно от разметки, передавать между системами, собирать по настройкам, править в редакторе или создавать с ИИ.

Слово «макет» в Framework

В части Утилиты и раскладка «раскладка» и утилиты раскладки (grid, flex и т. п.) означают CSS-расположение элементов. В этой части «макет» — документ композиции. Это разные уровни: макет описывает дерево страницы, а утилиты раскладки оформляют уже полученный HTML.

Смотрите также

• Recipe, документ и HTML — три представления страницы.
• Раскладка — утилиты раскладки.
• Что такое компонент — компоненты.