Островки кода

В самом простом виде шаблон — это текст, который бот отправит как есть. Вся сила шаблонов — в островках кода: вставках, которые вычисляют значения, проверяют условия и повторяют текст.

Три вида островков

Островок	Назначение
{{ выражение }}	Вывод. Вычисляет выражение и подставляет результат в текст
{% тег … %}	Тег. Выполняет одну операцию: условие, цикл, присваивание. Сам ничего не выводит
{# … #}	Комментарий. Пропускается целиком, может занимать несколько строк

{# Приветствие с учетом уровня #}
{% set lvl = member.rank.level %}
Привет, {{ member.name }}! Твой уровень — {{ lvl }}.

Каждый островок {% %} выполняет одну операцию или открывает и закрывает часть конструкции. Сложная логика складывается из нескольких островков подряд.

Вывод

Единственный способ напечатать значение — островок вывода:

{{ member.name }}
{{ 2 + 2 }}
{{ member.rank.level >= 10 ? 'ветеран' : 'новичок' }}

Все, что выводится через {{ }}, экранируется под синтаксис шаблона: если в имени участника есть * или <, они будут показаны как символы, а не сломают разметку. Не экранируются только результаты функций разметки (bold, link, table…) и объекты с собственным видом — например, участник выводится упоминанием. Подробнее — Экранирование.

Контроль пробелов

Дефис у скобки убирает все пробелы и переносы строк с этой стороны островка:

Запись	Что убирает
{%- / {{- / {#-	Пробелы и переносы перед островком
-%} / -}} / -#}	Пробелы и переносы после островка

{% if 1 == 1 -%}     текст     {%- endif %}

Результат — текст без пробелов вокруг.

Типичный прием — «прилепить» теги к соседним строкам, чтобы не было пустых строк:

Участники клуба:
{%- for m in club.members %}
- {{ m.name }}
{%- endfor %}

Сырой текст

Чтобы вывести {{ или {% как обычный текст, оберните его в verbatim:

{% verbatim %}Переменные пишутся так: {{ member.name }}{% endverbatim %}

Результат: Переменные пишутся так: {{ member.name }}.

Имена

Имена переменных и макросов: латинские буквы, цифры и _, первым символом не может быть цифра. Регистр важен: total и Total — разные переменные.

Ключевые слова нельзя использовать как имена переменных:

set global if elseif else endif for endfor true false empty return include in as do
verbatim endverbatim filter endfilter null is not with require returning macro endmacro
transform endtransform break continue use run scoped and or by same divisible

Литералы

Литерал — значение, записанное прямо в шаблоне.

Тип	Примеры	Заметки
Строка	'текст', "текст"	Внутри работают \\, \', \", \n (перенос строки), \t, \r, \uXXXX
Целое число	56, -10
Дробное число	1.5, 0.25	Разделитель — точка
Логическое	true, false
Пусто	null
Список	[1, 2, 3], ['a', 'b']	Можно изменять: add, remove…
Диапазон	[1..10]	Целые числа включительно. [10..1] — по убыванию. Изменять нельзя
Карта	{ name: 'Анна', 'full name': 'Анна С.' }	Ключ без кавычек — это строка, а не переменная

{% set modes = ['Броулбол', 'Нокаут', 'Ограбление'] %}
{% set prices = { vip: 500, premium: 1000 } %}
{% for i in [1..3] %}{{ i }} {% endfor %}

Доступ к свойствам и элементам

Запись	Что делает
member.name	Свойство объекта
member.getAttribute('coins')	Вызов метода
list[0]	Элемент списка по номеру (с нуля)
map['key'], map.key	Значение из карты по ключу
form.values[fieldId]	Ключ из переменной

Обращение к несуществующему свойству, индексу или переменной дает пустое значение Undefined и не ломает шаблон. В строгом режиме это ошибка.