Плейсхолдеры

Плейсхолдеры — это метки в шаблоне, которые система заменяет значениями полей при формировании документа. Каждый плейсхолдер заключён в двойные фигурные скобки: {{fieldName}}.

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

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

Это единственное, что нужно понять перед тем, как писать шаблон: словарь шаблона — это список полей типа сущности. Ничто другое не разрешается.

Машинное имя и отображаемое название

У каждого поля два имени. Отображаемое название видят пользователи в форме; его можно изменить в любой момент и на любом языке. Машинное имя — постоянный идентификатор, и в шаблонах используется именно оно.

Откройте тип сущности в разделе Настройки → Сущности, найдите поле и прочитайте его машинное имя. Поле с названием «Имя клиента» вряд ли окажется {{Имя клиента}}.

О том, как определяются поля и где задаётся машинное имя, читайте в типах сущностей.

Допустим, администратор определил тип документа Счёт с такими полями:

Отображаемое название Машинное имя Тип Плейсхолдер

Номер счёта

invoiceNumber

Строка

{{invoiceNumber}}

Дата выставления

issueDate

Дата-время

{{issueDate}}

Клиент

customer

Ссылка → Контрагент

{{customer.name}}

Валюта

currency

Набор

{{currency}}

Позиции

lineItems

Вложенная сущность

{{#lineItems}}...{{/lineItems}}

Итого

total

Выражение

{{total}}

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

Что доступно кроме ваших полей

У каждой записи есть ещё системные поля; они присутствуют всегда, как бы ни был настроен тип:

name

Название записи.

description

Описание записи, если оно заполнено.

id

Внутренний идентификатор записи.

Кроме них, автор записи, ответственный и отметки времени выводятся и доступны по пути через точку.

В пакетных отчётах в контекст шаблона входит ещё объект filter, в котором лежат критерии поиска, применённые пользователем при формировании отчёта. Подробности — в разделе значения фильтра в шаблоне.

При совпадении имён системные поля имеют приоритет. Если пользовательскому полю дать машинное имя name, победит системное поле, а пользовательское станет недоступным. Не используйте name, id и description как машинные имена своих полей.

Как поле каждого типа попадает в шаблон

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

Строка, целое, дробное, дата-время, логическое, набор, перечисление

Одно значение. Используйте его напрямую: {{invoiceNumber}}.

Ссылка

Связанная запись выводится целиком, поэтому в неё заходят по пути через точку: {{customer.name}}, {{customer.taxNumber}}. Цепочки работают, пока есть связи — {{site.division.company}}.

Голый {{customer}} — это запись, а не значение, и выводится бесполезно.

Вложенная сущность и коллекция

Список. Используйте повторяющийся раздел — {{#lineItems}}...{{/lineItems}} — и внутри него обращайтесь к машинным именам вложенного типа, которые определяются отдельно от родительского. О том, как настраиваются такие строки, читайте в вложенных сущностях, а о стороне шаблона — в повторяющихся разделах.

Выражение

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

Файл и изображение

Ссылка, а не значение. Для картинок используйте плейсхолдер-изображение, а не текстовый.

Сопоставление

Список пар «ключ — значение»; перебирается как коллекция.

Шаблон привязан к одному типу сущности

Доступные имена меняются в зависимости от того, к чему привязан шаблон. Шаблон на типе документа Счёт видит поля счёта; шаблон на типе контрагента видит поля контрагента.

Поэтому же существует лист _data в XLSX: он позволяет внести в ту же книгу записи другого типа сущности под выбранным вами именем.

Плейсхолдеры простых значений

Простой плейсхолдер вставляет одно значение поля:

Invoice {{invoiceNumber}}
Issued: {{issueDate}}
Bill to: {{customer.name}}

Если счёт сформирован из записи, где invoiceNumber равен INV-2026-0042, issueDate — 15 марта 2026 года, а связанный клиент — Apex Media, результат выглядит так:

Invoice INV-2026-0042
Issued: 15.03.2026
Bill to: Apex Media

Вложенные пути

Запись через точку заходит в связанные записи. Если у типа сущности есть поле-ссылка customer, указывающее на запись клиента, а у этой записи есть поле name, то:

{{customer.name}}

разрешается в название связанного клиента.

Вложенность идёт настолько глубоко, насколько позволяют данные:

{{customer.billingAddress.city}}

Доступ к корневому контексту

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

{{$.dealNumber}}

Это полезно, когда в строке таблицы нужно вывести рядом поле позиции и поле сделки. Например, в таблицу позиций предложения можно добавить номер сделки в каждую строку:

Столбец Плейсхолдер

Номер сделки

{{$.dealNumber}}

Название конструкции

{{displayName}}

Период

{{period}}

Цена

{{price}}

Без префикса $. плейсхолдер {{dealNumber}} искал бы поле dealNumber у самой позиции, а если такого поля нет, он разрешится в пустое место.

Доступ к родительскому контексту

Когда разделы вложены больше чем на один уровень, {{../fieldName}} обращается к полю родительского контекста — на один уровень выше, не обязательно к корню.

{{#campaigns}}
  Campaign: {{campaignName}}
  {{#placements}}
    Campaign (from parent): {{../campaignName}}
    Display: {{displayName}}
  {{/placements}}
{{/campaigns}}

Чтобы дойти до корня при любой глубине вложенности, используйте префикс $., описанный выше.

Инвертированные разделы

Инвертированный раздел выводит своё содержимое, только когда поле пусто, отсутствует или равно false. Вместо решётки в нём стоит символ ^:

{{^discount}}No discount applied.{{/discount}}

Если у поля discount есть значение, текст «No discount applied.» не выводится. Если discount пусто или отсутствует, текст попадает в результат.

Это удобно для запасного текста — например, чтобы показать «N/A», когда у необязательного поля нет значения:

Contact: {{contactEmail}}{{^contactEmail}}N/A{{/contactEmail}}

Комментарии

Текст в {{! ... }} — комментарий. При формировании документа он вырезается и до читателя не доходит.

{{! Clause 4.2 is for outdoor deals only. Legal asked for it -- keep. }}

Комментарий может занимать несколько строк и стоять внутри строки обычного текста:

Total: {{total}} {{! net of agency commission }}

Эта строка выйдет как Total: 45 000 — всё вокруг комментария остаётся нетронутым.

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

Что остаётся после комментария

Текст комментария исчезает всегда. Что происходит с местом, которое он занимал, зависит от формата.

XLSX

Ячейка, в которой только комментарий, остаётся по-настоящему пустой, а не содержит пустую строку. Остальное в строке не затрагивается.

На листе _data это вдвойне полезно: пустой столбец A означает, что строка не читается как источник данных, поэтому комментарий в столбце A превращает строку в строку подписей.

DOCX

Текст уходит, но абзац остаётся — пустой абзац, который Word показывает как пустую строку.

Чтобы пустой строки не было, ставьте комментарий в конец абзаца, где есть собственный текст, а не на отдельную строку:

AGREEMENT No. {{contractNumber}} {{! number comes from the deal }}

Комментарий, который один стоит в ячейке таблицы, просто оставляет ячейку пустой, и это ничего не стоит.

PPTX

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

Никогда не пишите синтаксис плейсхолдера внутри комментария

Комментарий не должен содержать }}.

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

Total: {{total}} {{! see {{total}} above }}

выйдет как Total: 45 000 above }} — хвост вашей собственной заметки, доставленный клиенту.

Описывайте плейсхолдеры словами или разбивайте скобки так, чтобы }} не встречалась:

{{! the total below is computed, not stored }}
{{! the block under this row loops -- see the items section }}

Как ведут себя отсутствующие поля

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

Значит, опечатка в имени поля — {{custmerName}} вместо {{customerName}} — молча даст пустое место в сформированном документе. Как это диагностировать, описано на странице Диагностика проблем.

Автоформатирование

Даты и дробные числа форматируются автоматически, когда вставляются простым плейсхолдером:

  • Даты форматируются как dd.MM.yyyy — например, 15.03.2025.

  • Дробные числа форматируются с двумя знаками после запятой — например, 1234.50.

Чтобы применить другой формат, используйте вместо этого плейсхолдер-выражение с функцией форматирования. См. Выражения и форматирование.

Сводка по типам плейсхолдеров

Синтаксис Что делает

{{fieldName}}

Вставляет значение поля.

{{linked.field}}

Вставляет значение из связанной записи (запись через точку).

{{$.fieldName}}

Вставляет значение из корневого контекста, в том числе внутри вложенного раздела.

{{../fieldName}}

Вставляет значение из родительского контекста (на один уровень выше).

{{#collection}} ... {{/collection}}

Повторяет блок для каждого элемента коллекции. См. повторяющиеся разделы.

{{^field}} ... {{/field}}

Выводит блок, только когда поле пусто или отсутствует.

{{! ... }}

Комментарий. Удаляется из результата; читатель его не видит.

{{=expression}}

Вычисляет выражение JavaScript на месте. См. выражения и форматирование.

{{=}}formula

Только XLSX — записывает в ячейку живую формулу Excel. См. Шаблоны Excel.

Связанные страницы