К содержимому
BuildNexus

Модуль и раздел

Сайт собирается из блоков: «первый экран», «карточки товаров», «форма обратной связи», «текст с картинкой».

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

Если вы пишете на Vue или React, аналогия прямая: модуль — компонент, раздел — его экземпляр в шаблоне, поля раздела — пропсы, а contract.json — описание пропсов.

Главный принцип: страницу собирает сервер

Ядро — серверная программа, написанная на языке Go, — берёт описание страницы, находит нужные модули, подставляет данные в их шаблоны и отдаёт браузеру готовый HTML — не пустой <div id="app">, который потом оживает. Страница видна сразу, её понимают поисковики и она не разваливается, если скрипт не загрузился.

Для большинства блоков код писать не нужно: модуль описывается JSON-файлами и шаблонами, а движок разбирается сам. JavaScript подключается только там, где нужна интерактивность: слайдер, вкладки, аккордеон.

Файлы модуля

Модуль — это папка в modules/. Имя папки и есть тип модуля — то слово, по которому его позовут со страницы. Пишется латиницей через подчёркивание.

hello_block/
  manifest.json                       паспорт модуля
  module.compose.json                 сборка: где шаблон и ассеты
  contract.json                       поля раздела и записей
  style.scss                          стили модуля
  templates/
    hello_block_template.tpl.html     вёрстка блока
    _components/hello_block/card.tpl.html   повторяющаяся часть

manifest.json — паспорт

Единственный файл, без которого папку вообще не сочтут модулем: имя, подпись для редактора на двух языках, описание и версия.

contract.json — какие у блока поля

Контракт описывает два уровня:

  • поля раздела — заголовок, подзаголовок, текст, картинка, режим контейнера;
  • поля записей — если внутри блока список карточек: заголовок карточки, текст, иконка, ссылка.

У каждого поля есть тип (text, textarea, html, enum, bool, image), подпись для редактора, значение по умолчанию и ограничения. Движок не примет полей, которых нет в контракте — это и держит редактор и рендер согласованными.

Шаблон — вёрстка блока

{{ raw:module_css }}
<section class="hello section" data-section-id="{{ section_id }}">
  <div class="container">
    <h2 v-if="title">{{ title }}</h2>
    <hello_block:Card v-for="rec in records" :heading="rec.heading" />
  </div>
</section>

Синтаксис нарочно похож на Vue, но выполняется на сервере — подробнее в разделе Шаблоны и Vue.

Свой модуль и логика на JavaScript

Проще всего начать с копии близкого по смыслу модуля: скопируйте папку, переименуйте её, поправьте контракт, шаблон и стили. После правок фронтенда модуль пересобирается; правки серверных шаблонов подхватываются без сборки.

Когда блоку нужна собственная логика — расчёты, свой источник данных, обработка формы — её можно описать на JavaScript прямо в модуле: код выполняется серверным ядром на Go, пересобирать ядро для этого не нужно.

Контракт, записи и данные

contract.json — договор между редактором, хранилищем и шаблоном. Он определяет, какие значения можно задать и как Studio должна их показать.

Два уровня полей

  • editor.section_fields описывает весь раздел: заголовок, фон, режим контейнера, лимит записей.
  • editor.object_fields описывает одну повторяемую запись: карточку, этап, отзыв или пункт списка.

Записи раздела всегда хранятся в массиве objects. В шаблон они приходят подготовленным списком, по которому можно пройти циклом. Изображения задаются полями типа image или images; редактор и шлюз сохраняют их в согласованной структуре, а не в произвольных строках.

Что даёт контракт

  • Studio строит форму редактирования и подставляет значения по умолчанию.
  • Шлюз для ИИ-агентов проверяет поля и типы перед записью.
  • Один набор данных одинаково понимают предпросмотр, серверное ядро и опубликованный сайт.
  • При изменении модуля видно, какие данные являются частью его публичного интерфейса.

Для простого списка записи лежат прямо в разделе. Общий список можно вынести в коллекцию, а данные магазина или CRM получить из сущности. Внешний вид шаблона при этом не обязан меняться: он по-прежнему работает с подготовленными записями. Подробнее: переменные, коллекции и данные.

Редактор контракта модуля: поля раздела, значения по умолчанию и проверка схемы.
Редактор контракта модуля: поля раздела, значения по умолчанию и проверка схемы.

Логика модуля и проверка

У модуля есть несколько уровней сложности. Не начинайте с самого тяжёлого.

  1. Обычный модуль: контракт, конфигурация, шаблон и стили. Этого достаточно для большинства информационных блоков.
  2. Декларативный источник: модуль объявляет коллекцию или сущность, фильтр и сортировку; ядро само получает записи.
  3. Серверный JavaScript: compute рассчитывает значения перед отрисовкой, а refresh заранее обновляет внешний кеш.
  4. Действие модуля: отдельный обработчик принимает форму или выполняет разрешённое изменение данных.
  5. Lego-композиция: объединяет самостоятельные секции в сложный блок с серверной отрисовкой и одним владельцем состояния.
  6. Проектный Go-сервис: реализует API, закрытый RPC, события и изолированную предметную логику.

Жизненный цикл блока

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

Что проверить перед публикацией

  • все поля шаблона объявлены в контракте;
  • пустой список и отсутствующее изображение имеют нормальный вид;
  • несколько экземпляров модуля не конфликтуют;
  • основное содержание читается без браузерного JavaScript;
  • модуль проходит проверку и сборку в Studio;
  • страница проверена на настольной и мобильной ширине.

Продолжение: Lego-модули, Go-сервисы и общий раздел расширения платформы.

Минимальный модуль: от папки до страницы

Самый надёжный способ начать — создать модуль в Studio или через module_create. Генератор подготовит согласованный каркас, после чего вы меняете только нужные части.

  1. Назовите тип латиницей, например promo_note. Имя папки станет типом раздела.
  2. Заполните manifest.json: имя, подписи, описание и версию.
  3. Опишите поля в contract.json: например, title, text и button_url.
  4. Укажите шаблон и ассеты в module.compose.json.
  5. Сверстайте раздел в templates/promo_note_template.tpl.html.
  6. Добавьте стили и небольшой браузерный сценарий только при необходимости.
<section class="promo-note" data-section-id="{{ section_id }}">
  <h2 v-if="title">{{ title }}</h2>
  <div v-if="text">{{ raw:text }}</div>
  <a v-if="button_url" :href="button_url">Подробнее</a>
</section>

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