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

Как выбрать место для данных

В BuildNexus данные можно хранить на нескольких уровнях. Выбор зависит не от технологии, а от простого вопроса: где это значение должно использоваться и кто будет его менять.

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

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

Переменные проекта и страницы

Переменная проекта задаётся один раз и доступна по всему сайту. Разберём полный путь на примере телефона в шапке.

1. Создайте значения в Studio

Откройте настройки проекта → «Переменные» и добавьте две переменные:

  • contact.phone_label — отображаемый номер, например +7 (982) 482-49-01;
  • contact.phone_href — адрес ссылки, например tel:+79824824901.

Точка в имени создаёт смысловую группу contact. Внизу этой вкладки Studio также показывает переменные, которые уже встречаются в шаблонах, но ещё не заполнены.

2. Используйте их в шаблоне

Откройте файл шапки www/templates/partials/header.sehtml и добавьте ссылку в нужное место:

<a
  v-if="var['contact.phone_href']"
  href="{{ var:contact.phone_href }}"
>{{ var:contact.phone_label }}</a>

Условие скрывает ссылку, пока адрес не заполнен. В выражении имя с точкой берётся через квадратные скобки, а в подстановке var: пишется целиком.

Переменная страницы

Переменная страницы относится только к одной странице. В каркасе www/templates/pages/default.sehtml её можно вывести так:

<h1>{{ pagevar:title }}</h1>

Проектные переменные работают в каркасах и модулях. pagevar предназначен для каркаса страницы и внутри модулей не используется. Значения каркаса подставляются напрямую, поэтому не помещайте туда непроверенный пользовательский HTML и следите за кавычками в значениях атрибутов.

Переменные проекта сгруппированы по назначению; значения можно менять отдельно.
Переменные проекта сгруппированы по назначению; значения можно менять отдельно.

Коллекции без базы данных

Коллекция — общий список записей в файлах проекта. База данных не нужна. Ниже — полный пример: модуль branches_list показывает одни и те же филиалы на нескольких страницах.

1. Опишите поля записи в contract.json

В modules/branches_list/contract.json поля редактора объекта должны включать данные филиала:

"editor": {
  "object_fields": {
    "fields": [
      { "name": "title", "type": "text", "label": { "ru": "Название" } },
      { "name": "address", "type": "textarea", "label": { "ru": "Адрес" } },
      { "name": "url", "type": "url", "label": { "ru": "Ссылка" } }
    ]
  }
}

2. Подключите коллекцию в module.compose.json

В modules/branches_list/module.compose.json добавьте records_collection внутрь уже существующего runtime.list_detail:

{
  "templates": {
    "section_template": "branches_list_template.tpl.html"
  },
  "runtime": {
    "mode": "app_native",
    "list_detail": {
      "records_collection": "branches",
      "source_fields": {
        "record": {
          "id": "id",
          "title": "title",
          "address": "address",
          "url": "url"
        }
      }
    }
  }
}

После запуска ядро подготовит коллекцию www/data/collections/branches.json. Редактируйте её через Studio, а не вручную.

3. Выведите записи в шаблоне

Файл modules/branches_list/templates/branches_list_template.tpl.html получает обычный массив records:

<section class="branches">
  <article v-for="rec in records" class="branches__item">
    <h3>{{ rec.title }}</h3>
    <p>{{ rec.address }}</p>
    <a v-if="rec.url" :href="rec.url">Открыть</a>
  </article>
</section>

4. Заполните данные

Добавьте секцию branches_list на страницу и заполните записи штатным редактором блока либо откройте коллекцию branches в настройках проекта. Любая секция совместимого модуля читает тот же список.

Раздел коллекций в настройках проекта.
Раздел коллекций в настройках проекта.

Данные из сущностей и базы

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

1. Объявите источник в module.compose.json

Откройте modules/brand_grid/module.compose.json. Блок data находится внутри runtime.list_detail:

{
  "templates": {
    "section_template": "brand_grid_template.tpl.html"
  },
  "runtime": {
    "mode": "app_native",
    "provider": "generic",
    "list_detail": {
      "data": {
        "source": "brands",
        "order": "name asc",
        "limit": 12,
        "require": ["name"],
        "fields": {
          "title": "name",
          "code": "code",
          "num": "@index"
        }
      }
    }
  }
}

source — имя источника, зарегистрированного ядром или расширением. Встроенные источники включают brands, publications, reviews, product_catalog и другие сущности. Не используйте имя таблицы базы: модуль обращается к реестру сущностей.

2. Используйте выходные поля в шаблоне

Матрица fields слева задаёт имена, которые увидит шаблон. В modules/brand_grid/templates/brand_grid_template.tpl.html используйте именно title, code и num:

<section class="brands">
  <article v-for="brand in records" class="brands__item">
    <span>{{ brand.num }}</span>
    <h3>{{ brand.title }}</h3>
    <small>{{ brand.code }}</small>
  </article>
</section>

Что делает ядро

  1. Находит зарегистрированную сущность brands.
  2. Применяет сортировку, лимит и обязательные поля.
  3. Преобразует сырые записи по матрице fields.
  4. Передаёт результат шаблону как записи списка.

SQL в шаблоне и серверном JavaScript не нужен. Для обычного сайта на тарифе Site база не требуется; сущности Business, Commerce и Full рассчитаны на MySQL 8 или новее.

Дополнительные поля CRM для заказов, контактов, компаний, товаров и публикаций.
Дополнительные поля CRM для заказов, контактов, компаний, товаров и публикаций.

Декларативная выборка: фильтры и поля

Этот раздел продолжает пример brand_grid выше. Следующий фрагмент не является отдельным файлом: им нужно заменить объект runtime.list_detail.data в modules/brand_grid/module.compose.json.

"data": {
  "source": "brands",
  "filter": [
    { "field": "count", "op": ">=", "value": 1 }
  ],
  "order": "name asc",
  "limit_field": "records_per_page",
  "limit": 12,
  "limit_min": 1,
  "limit_max": 48,
  "require": ["name"],
  "fields": {
    "title": "name",
    "num": "@index",
    "url": "{catalog_page_url}?brand={code|rawurlencode}"
  }
}

Откуда берутся records_per_page и catalog_page_url

Это поля самой секции. Объявите их в modules/brand_grid/contract.json внутри editor.section_fields.fields, чтобы владелец мог менять значения в редакторе:

"section_fields": {
  "fields": [
    {
      "name": "records_per_page",
      "type": "int",
      "label": { "ru": "Количество брендов" },
      "default": 12
    },
    {
      "name": "catalog_page_url",
      "type": "url",
      "label": { "ru": "Адрес каталога" },
      "default": "/catalog/"
    }
  ]
}

Как читать декларацию

  • filter — структурные условия, а не SQL. Поддерживаются =, !=, in, like, >, <, >=, <=.
  • limit_field берёт число из поля секции; limit остаётся запасным значением.
  • limit_min и limit_max не позволяют случайной настройке запросить слишком мало или слишком много.
  • require исключает записи без обязательного поля.
  • @index создаёт номер с единицы.
  • {catalog_page_url} берётся из секции, {code} — из записи, а rawurlencode безопасно кодирует значение для адреса.

Итоговое поле url доступно в том же шаблоне как brand.url:

<a v-for="brand in records" :href="brand.url">
  {{ brand.num }}. {{ brand.title }}
</a>

Если данные нужно только выбрать и подготовить, декларации достаточно. Серверный compute добавляйте для настоящего расчёта, а не вместо фильтра, лимита или матрицы полей.

Практический маршрут

  1. Сначала соберите блок с локальными полями и записями, чтобы проверить содержание и внешний вид.
  2. Вынесите повторяющиеся значения в переменные проекта.
  3. Вынесите общий список в коллекцию, если он нужен на нескольких страницах.
  4. Подключайте сущность, когда данные уже живут в базе и меняются в ходе работы сайта.
  5. Добавляйте код только для вычислений, обмена с внешней системой или отдельного действия.

Так проект остаётся понятным редактору, разработчику и ИИ-агенту: источник данных объявлен рядом с модулем, а шаблон отвечает только за представление.

Шаг 6 из 11 — Переменные, коллекции и данные

← Шаг 5. Шаблоны и Vue-HTML  ·  Шаг 7. JavaScript и расширение платформы →

  1. Быстрый старт
  2. Структура проекта
  3. Страницы и навигация
  4. Модули
  5. Шаблоны и Vue-HTML
  6. Переменные, коллекции и данные — вы здесь
  7. JavaScript и расширение платформы
  8. IDE и ИИ-агенты
  9. Размещение сайта и серверное ядро
  10. Магазин и CRM
  11. Обновления и безопасность