Быстрый старт: первый блок руками

За один проход мы сделаем промо-секцию с заголовком, текстом и кнопкой: опишем схему полей, напишем шаблон, поставим блок на страницу и опубликуем её.

Что понадобится

аккаунт в PageCraft;
сайт — представление вашего магазина внутри PageCraft, с настроенным провайдером публикации. Без сайта блок сделать можно, а опубликовать страницу — нет.

Всё то же самое доступно через REST API по API-ключу — см. REST API V1. Здесь описан путь через интерфейс.

Шаг 1. Создать блок

В студии блоков нажмите Новый блок. В карточке блока заполните:

имя — так блок будет виден в списке;
описание — одна фраза, зачем он;
тип блока — оставьте Schema (LiquidJS). Второй тип, Markdown (Rich Text), нужен для текстовых секций, которые редактируют визуальным редактором, — см. Markdown в блоках.

Редактор блока состоит из вкладок: HTML (Liquid-шаблон), CSS, JS, Schema (схема полей) и документация. Рядом — живой предпросмотр.

Шаг 2. Описать схему полей

Схема — это JSON на вкладке Schema. Корень всегда объект с type: "object" и картой fields; ключ карты становится именем поля.

{
  "type": "object",
  "label": "Промо-секция",
  "fields": {
    "title": {
      "type": "text",
      "label": "Заголовок",
      "default": "Скидки до 40%"
    },
    "subtitle": {
      "type": "textarea",
      "label": "Подзаголовок"
    },
    "show_button": {
      "type": "switch",
      "label": "Показывать кнопку",
      "default": true
    },
    "button_text": {
      "type": "text",
      "label": "Текст кнопки",
      "default": "Смотреть акции"
    },
    "button_url": {
      "type": "url",
      "label": "Ссылка кнопки",
      "default": "#"
    }
  }
}

Что здесь важно:

label — это подпись в форме редактора. Именно её увидит тот, кто будет заполнять блок на странице; имя ключа он не видит.
default подставляется в форму и в предпросмотр. Блок без заполненных значений должен выглядеть осмысленно — это и есть роль дефолтов.
Имена size, first, last запрещены. Это зарезервированные аксессоры Liquid, и валидация схемы такой ключ отклонит. Берите box_size, first_item и подобные.
Кроме показанных типов есть image, icon, color, select, radio, date, time, datetime, а также object для группы полей и array для повторяющихся элементов. Полный перечень — Схема полей.

Шаг 3. Написать Liquid-шаблон

Вкладка HTML. Значения полей приходят в шаблон под именем props:

<section class="promo">
  <h2 class="promo__title">{{ props.title }}</h2>

  {% if props.subtitle != '' %}
    <p class="promo__text">{{ props.subtitle }}</p>
  {% endif %}

  {% if props.show_button %}
    <a class="promo__button" href="{{ props.button_url | default: '#' }}">
      {{ props.button_text }}
    </a>
  {% endif %}
</section>

Liquid в PageCraft работает в мягком режиме: неизвестная переменная и неизвестный фильтр не роняют рендер, а дают пустую строку. Ошибка в самом шаблоне тоже не ломает страницу — на её месте окажется HTML-комментарий с текстом ошибки. Удобно при разработке и опасно при публикации: пустое место на витрине выглядит как «блок не работает». Подробнее — Liquid: основы.

Шаг 4. Добавить стили

Вкладка CSS. Стили блока попадают на страницу вместе с ним, поэтому имена классов должны быть уникальными — иначе блоки на одной странице перекрасят друг друга.

.promo {
  padding: 48px 24px;
  text-align: center;
}
.promo__title {
  font-size: 32px;
  margin: 0 0 12px;
}
.promo__button {
  display: inline-block;
  padding: 12px 24px;
  border-radius: 8px;
}

Шаг 5. Проверить в предпросмотре

Предпросмотр рендерит шаблон прямо в браузере и показывает результат в iframe с переключателем ширины (мобильный, планшет, десктоп). Рядом — форма, собранная из вашей схемы: поменяйте значения и посмотрите, как блок реагирует.

Проверьте оба состояния переключателя show_button и пустой subtitle — блок не должен разваливаться ни в одном из них.

Шаг 6. Сохранить

Сохранение создаёт ревизию блока — неизменяемый снимок шаблона, стилей, скрипта и схемы. Первая ревизия получает версию 1.0.

Дальше при каждом сохранении номер считается автоматически:

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

Подробнее — Ревизии и версии.

Шаг 7. Поставить блок на страницу

Создайте страницу внутри сайта (при необходимости — в папке).
Добавьте на неё свой блок из списка блоков.
Заполните форму настроек блока — это те самые поля из схемы.
Задайте порядок блоков, если их несколько.

Блок на странице хранит ссылку на блок и на конкретную его версию, а не копию разметки. Поэтому правка блока не ломает уже собранные страницы, а обновление до свежей версии — отдельное осознанное действие. См. Сборка страницы из блоков.

Шаг 8. Опубликовать

Заполните SEO-поля страницы и нажмите Опубликовать. В диалоге провайдера указываются название страницы на витрине, рубрики и SEO-поля.

Что происходит при публикации:

блоки страницы рендерятся по порядку — на сервере, другим движком Liquid, чем в предпросмотре;
CSS и JS всех блоков собираются вместе;
подставляются переменные сайта; обёртку с шапкой и подвалом добавит витрина;
провайдер выкладывает страницу на витрину и возвращает её адрес.

Повторная публикация обновляет ту же страницу, а не создаёт копию: PageCraft запоминает её идентификатор на стороне витрины. Детали — Публикация и обновление.

Что дальше

Сохранить удачный набор значений блока, чтобы не заполнять форму заново, — Пресеты.
Отдать блоку живые данные витрины — Биндинги и слоты.
Разобраться, что ещё доступно в шаблоне, — Что доступно в контексте.
Отдать рутину агенту — Скиллы.

Источники: backend/public/block-schema.json, backend/src/Service/BlockSchemaValidator.php, backend/src/Service/BlockVersionService.php, backend/src/Publishing/BlockRenderer.php, backend/src/Controller/Page/PublishPageAction.php, front/src/components/BlockEditor/BlockEditorScreen.tsx, front/src/components/BlockEditor/BlockPreview.tsx, front/src/providers/fourcms/FourCmsPublishDialog.tsx.