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

Что такое Vue-HTML

Vue-HTML — серверный язык шаблонов BuildNexus. Файлы выглядят как Vue, но их разбирает ядро: посетитель получает уже готовый HTML, а директивы на странице повторно не исполняются.

Vue-HTMLБраузерный Vue 3
Работает на сервере при создании HTMLРаботает в браузере после загрузки страницы
Файлы .tpl.htmlФайлы .vue, TypeScript и собранный JS
Условия, циклы, подстановки и небольшой набор функцийСостояние, события, запросы и интерактивность
Не требует JavaScript у посетителяТребует подключённого браузерного пакета

Где работает язык

ФайлНазначениеВозможности Vue-HTML
modules/<модуль>/templates/*.tpl.htmlРазметка блоков, карточек, списков и детальных страницПолный язык
www/templates/menus/*.tpl.htmlРазметка меню и его пунктовПолный язык
www/templates/pages/*.sehtmlКаркас всего HTML-документаТокены композитора и ветвление v-if, но не полный язык
www/templates/partials/*.sehtmlШапка, подвал и части каркасаТокены и ветвление, без циклов Vue-HTML

Не ориентируйтесь только на похожий синтаксис. Цикл v-for в шаблоне модуля или меню работает, а в каркасе страницы .sehtml не является полноценным циклом.

Типичная папка модуля

modules/promo_banner/
├── contract.json
├── module.compose.json
└── templates/
    └── promo_banner_template.tpl.html

Шаблон лежит внутри модуля, но начинает использоваться только после объявления его роли в module.compose.json.

Как подключить шаблон

Для простого блока укажите файл в modules/promo_banner/module.compose.json:

{
  "version": "1.0.0",
  "templates": {
    "section_template": "promo_banner_template.tpl.html"
  },
  "assets": {
    "css": ["style.scss"],
    "js": []
  },
  "runtime": {
    "mode": "app_native"
  }
}

Имя считается относительно папки templates/ этого модуля. Сам файл находится по адресу modules/promo_banner/templates/promo_banner_template.tpl.html.

Роли шаблонов

КлючЧто отрисовывает
section_templateВесь простой блок или внешнюю обёртку list/detail-модуля
record_templateОдну карточку записи
list_templateКонтейнер списка карточек
show_templateДетальную страницу одной записи
layout_templateНеобязательную общую обёртку представления

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

Какие данные приходят

Доступные имена зависят от роли шаблона и контракта модуля.

  • В простом section_template поля раздела доступны напрямую: title, text, image, link_url. Также доступен section_id.
  • В карточке записи доступны токены, которые контракт связал с record.*.
  • В списке доступны значения раздела и собранные записи, предусмотренные моделью модуля.
  • Значения серверного compute доступны как токены compute.* или подготовленные итоговые имена согласно contract.render.
  • В шаблоне меню доступны items, параметры меню и подготовленные поля каждого item.

Откуда берётся имя токена

Источником правды является contract.json. Поля редактора объявляют, что может заполнить владелец сайта, а contract.render связывает данные раздела, записи, результата вычисления и шаблонные токены.

<section data-section-id="{{ section_id }}">
  <h2>{{ title }}</h2>
  <div>{{ raw:text }}</div>
</section>

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

Подстановки и экранирование

ФормаЧто делает
{{ title }}Выводит значение с HTML-экранированием
{{ raw:text_html }}Вставляет готовый HTML без экранирования
{{ var:contact.phone }}Подставляет переменную проекта
{{ t('add_to_cart') }}Выводит перевод активного языка
<{{ title_tag }}>Использует значение как имя HTML-тега

Безопасный вывод по умолчанию

<h2>{{ title }}</h2>

Если в title попадёт <script>, посетитель увидит текст, а не исполняемый тег.

Доверенный HTML

<div class="article">{{ raw:text }}</div>

raw: и v-html применяйте только к данным редактора или ядра, происхождение которых известно. Не вставляйте так имя, комментарий, параметры адреса или другой ввод посетителя.

Условия и директивы

ДирективаНазначение
v-ifВыводит элемент, если выражение истинно
v-else-if, v-elseПродолжают цепочку соседних условий
v-forПовторяет элемент по массиву или объекту
v-textЗадаёт безопасный текст элемента
v-htmlВставляет доверенный HTML
:атрибутВычисляет значение атрибута
<article v-if="title" class="card">
  <h2 v-text="title"></h2>
  <p v-if="note">{{ note }}</p>
  <p v-else>Описание ещё не добавлено</p>
</article>
<p v-else>Карточка не заполнена</p>

v-else-if и v-else относятся к предыдущему условию и должны стоять на соседнем элементе. Если между ветвями вклинить другой тег, цепочка перестаёт быть однозначной.

Ложное значение в привязанном атрибуте убирает атрибут целиком. Это удобно для :aria-current, :target и условных классов.

Выражения и операторы

Выражения используются в v-if, привязанных атрибутах и подстановках.

ВозможностьПример
Путь и индексitem.title, items[1], rec.images.0.image
Литералыtrue, false, null, 42, 'текст'
Сравнения== != === !== > < >= <=
Логика!flag, a && b, a || b
Арифметика+ - * / %
Тернарное условиеflag ? 'on' : 'off'
Длинаitems.length, title.length
Скобки(a || b) && c

Особенности правдивости

Ложными считаются null, false, число 0 и пустая строка. Строка '0', пустой массив и пустой объект истинны. Флажок из данных проекта часто является строкой, поэтому проверяйте его явно:

<div v-if="is_active == '1'">Показать</div>

Переменную с точкой в имени берите через скобки: var['social.vk']. Вокруг оператора вычитания оставляйте пробелы: a - b; запись has-icon считается одним именем.

Атрибуты, классы и стили

Обычный атрибут и привязка

<a href="{{ item.url }}">Обычная подстановка</a>
<a :href="item.url">Выражение</a>

Внутри :атрибут пишется выражение без фигурных скобок. Запись :class="{{ kind }}" неверна и оставит элемент без класса.

Условные классы

<article :class="{
  'card--active': is_active == '1',
  'card--featured': featured == '1'
}">

Список классов

<button :class="['btn', kind ? 'btn--' + kind : '']">

Стили

<div :style="{ color: text_color, fontSize: size + 'px' }">

В объекте стилей fontSize превращается в font-size. Объекты и массивы можно комбинировать. Для постоянных классов оставляйте обычный class, а в :class помещайте только вычисляемые модификаторы.

Если результат выражения ложный, привязанный атрибут не выводится. Так :target="item.target" не создаёт пустой target.

Встроенные функции

Функции вызываются только в функциональной форме: upper(title), а не title.toUpperCase().

ФункцияНазначение
upper(s), lower(s), trim(s)Регистр и удаление крайних пробелов
truncate(s, n[, tail])Обрезка строки по символам
number(n[, digits])Число с группами разрядов и дробной запятой
round(n[, digits])Округление
plural(n, one, few, many)Русская форма слова; число отдельно
join(list[, separator])Склейка непустых значений списка
count(x)Длина списка, объекта или строки
t(key[, fallback])Перевод активного языка
<h2>{{ upper(trim(title)) }}</h2>
<p>{{ truncate(text, 120) }}</p>
<strong>{{ number(price, 2) }} ₽</strong>
<span>
  {{ count(records) }}
  {{ plural(count(records), 'товар', 'товара', 'товаров') }}
</span>

Функции можно вкладывать. Даты, регулярные выражения и сложные преобразования готовьте заранее в серверном JavaScript или источнике данных.

Циклы и loop

<article
  v-for="(item, index) in items"
  :class="{ 'card--first': loop.first }"
>
  <span>{{ loop.number }}</span>
  <h3>{{ item.title }}</h3>
</article>
ПолеЗначение
loop.numberПорядковый номер с единицы
loop.indexИндекс с нуля
loop.countВсего элементов
loop.first, loop.lastПервая и последняя итерация
loop.even, loop.oddЧётность по отображаемому номеру
loop.keyКлюч объекта или индекс массива
loop.parentСчётчик внешнего цикла

Поддерживаются формы item in items и (item, index) in items. Вложенный цикл создаёт собственный loop; к внешнему обращайтесь через loop.parent.

Серверные компоненты

Повторяющуюся серверную разметку можно вынести в компонент. Для модуля product_grid файл карточки располагается здесь:

modules/product_grid/templates/
└── _components/
    └── product_grid/
        └── card.tpl.html

Вызов использует пространство имён и имя файла:

<product_grid:Card
  v-for="item in records"
  :title="item.title"
  :url="item.url"
  :featured="item.featured == '1'"
  read-more="Подробнее"
/>
  • <product_grid:Card> соответствует _components/product_grid/card.tpl.html.
  • :title передаёт результат выражения.
  • read-more передаёт постоянную строку.
  • Атрибут без значения означает логическое «да».
  • v-if и v-for работают прямо на компоненте.

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

Пример 1. Единый шаблон

Модель A подходит блоку без отдельных записей: баннеру, текстовой секции, призыву к действию. Вся разметка находится в одном section_template.

module.compose.json

{
  "templates": {
    "section_template": "promo_banner_template.tpl.html"
  },
  "runtime": { "mode": "app_native" }
}

templates/promo_banner_template.tpl.html

<section
  class="promo-banner"
  data-section-id="{{ section_id }}"
>
  <div class="promo-banner__content">
    <{{ title_tag }}
      v-if="title"
      class="promo-banner__title"
    >{{ title }}</{{ title_tag }}>

    <div v-if="text" class="promo-banner__text">
      {{ raw:text }}
    </div>

    <a v-if="link_url && link_text"
       class="button"
       :href="link_url">
      {{ link_text }}
    </a>
  </div>
</section>

Поля title, title_tag, text, link_url и link_text должны быть объявлены контрактом модуля. Здесь нет скрытой промежуточной разметки: что написано в файле, то и становится секцией.

Пример 2. Список и детальная страница

Модель B нужна, когда есть карточки и отдельные страницы записей. Ядро по очереди создаёт карточки, список, при необходимости детальную страницу, а затем помещает результат во внешнюю оболочку.

module.compose.json

{
  "templates": {
    "section_template": "articles_template.tpl.html",
    "record_template": "articles_card.tpl.html",
    "list_template": "articles_list.tpl.html",
    "show_template": "articles_show.tpl.html"
  },
  "runtime": { "mode": "app_native" }
}

Внешняя оболочка

{{ raw:module_css }}
<section class="articles">
  {{ raw:content }}
</section>
{{ raw:module_js }}

Карточка одной записи

<article class="article-card">
  <h3>{{ title }}</h3>
  <p>{{ truncate(summary, 140) }}</p>
  <a :href="detail_url">Читать</a>
</article>

Контейнер списка

<div class="articles__grid">
  {{ raw:records_html }}
</div>

content и records_html уже содержат собранный HTML, поэтому выводятся через raw:. Чтобы изменить карточку, правьте record_template; section_template обычно остаётся тонкой оболочкой для CSS, JS и готового представления.

Пример 3. Меню

Шаблоны меню лежат в www/templates/menus/*.tpl.html и используют тот же полный движок Vue-HTML. Сами пункты находятся отдельно в www/menus/*.json.

<nav :aria-label="menu_title || 'Основное меню'">
  <ul class="menu">
    <li
      v-for="item in items"
      :class="['menu__item', item.is_active && 'is-active']"
    >
      <a
        v-if="item.has_url"
        class="menu__link"
        :href="item.url"
        :target="item.target"
        :aria-current="item.aria_current"
      >{{ item.title }}</a>

      <span v-else class="menu__link">
        {{ item.title }}
      </span>
    </li>
  </ul>
</nav>

Подготовленные поля item.item_class, item.link_class, item.children, item.target и item.aria_current позволяют сохранить навигационную семантику. Для вложенного меню повторите цикл по item.children.

В каркасе меню подключается токеном {{ menu:mainmenu }}. Вариант {{ menu:mainmenu|headermenu }} использует те же пункты с другим шаблоном.

Vue 3 в браузере

Vue-HTML заканчивает работу до отправки страницы. Если пользователь должен нажимать кнопки, менять состояние без перезагрузки, открывать панели или отправлять запросы, нужен браузерный Vue 3.

Разделите обязанности

  1. Vue-HTML выводит осмысленную серверную оболочку и запасное состояние.
  2. Серверный compute подготавливает начальные данные и безопасный JSON.
  3. Шаблон размещает точку монтирования и JSON-состояние.
  4. Компонент из frontend/src/App.vue монтируется в браузере.
  5. Сборка модуля создаёт файлы в assets/, которые объявляются в module.compose.json.
<div class="price-widget__mount"
     data-price-widget
     data-widget-key="{{ widget_key }}">
  <p>{{ title }}</p>
  <p>Загрузка интерактивного блока…</p>
</div>

<script type="application/json"
        id="price-state-{{ widget_key }}">
{{ raw:state_json }}
</script>

Так блок остаётся понятным без JavaScript и до монтирования. В поставке ядра и проекта ориентиром служит модуль bnx_vue_demo.

Чего в языке нет

Vue-HTML не является JavaScript и не поддерживает весь синтаксис Vue.

{{ title.toUpperCase() }}  // нет методов
{{ items.map(x => x.name) }} // нет стрелок и map
{{ user?.name }}          // нет optional chaining
{{ `Привет ${name}` }}   // нет шаблонных строк
{{ now() }}               // нет текущей даты
{{ /sale/i }}             // нет регулярных выражений
  • Нет произвольных функций и методов объектов.
  • Нет доступа к window, document и DOM.
  • Нет обработчиков @click как исполняемой браузерной логики.
  • Нет запросов к сети и файловой системе.
  • Нет import, require, обещаний и асинхронного кода.

Для регистра используйте upper(title), для массива — v-for, для отсутствующего пути достаточно обычного обращения, а сложные вычисления вынесите в серверный compute. Интерактивность реализуйте отдельным Vue 3-компонентом.

Проверка и диагностика

В Studio включите «Проверку шаблонов». Ядро проверит дерево при старте и каждый сохранённый шаблон, а замечания появятся в панели открытой страницы.

ДиагностикаЧто означает
callНеизвестная функция или вызов в стиле метода
optional-chainИспользован неподдерживаемый ?.
arrowОбнаружена стрелочная функция
backtickИспользована шаблонная строка JavaScript
unbalancedНе сходятся кавычки или скобки
interp-in-bindВнутри :атрибут ошибочно написаны фигурные скобки
bad-v-forЦикл не соответствует форме item in items

Проверка всего проекта

bnxdev --lint --sites ./sites --modules ./modules/src

Вывод имеет формат файл:строка: [код] сообщение и подходит для терминала, IDE и CI.

Что проверка не знает

Опечатку вроде item.is_activ невозможно отличить от необязательного пустого поля без реальных данных. Для таких случаев проверяйте вход раздела и итоговый HTML через инструменты рендера.

Проверочный список

  1. Определите среду: модуль или меню используют .tpl.html, каркас страницы — .sehtml.
  2. Объявите правильную роль файла в module.compose.json.
  3. Сверьте имена токенов с contract.json и ролью шаблона.
  4. Обычные данные выводите с экранированием; raw: оставьте доверенному HTML.
  5. В :атрибут пишите выражение без фигурных скобок.
  6. Для строковых флажков сравнивайте с '1' или '0'.
  7. Пустой список проверяйте через count(items).
  8. Сложную обработку вынесите в серверный JavaScript, интерактивность — в Vue 3.
  9. Включите диагностику и проверьте шаблоны линтером.
  10. Посмотрите итоговый HTML, мобильную ширину и страницу без браузерного JavaScript.

Куда дальше

Шаблоны сайта и каркасы · Устройство модулей · Серверный JavaScript · Данные и коллекции

В репозитории полезны живые образцы: about_block для единого шаблона, bnx_releases для разделения оболочки и карточки, www/templates/menus/menu.tpl.html для меню и bnx_vue_demo для браузерного острова.