Шаблонизатор документов 2.0 - руководство пользователя

Что такое шаблон документа и зачем он нужен

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

Один раз создаёте шаблон «Акт осмотра» — и система сама формирует готовый документ для любого осмотра, нажатием одной кнопки.

Шаблоны поддерживают:

• вставку полей из карточки (номер, дата, ФИО и т. д.)

• циклы — для вывода списков (замечания, покупатели)

• условия — показывать блок только если данные есть

• изображения и отметки на плане

• таблицы с автоматическим повтором строк по списку

• форматирование: дата прописью, число прописью

Как открыть редактор шаблонов

1. Перейдите в Настройки → Шаблоны.

2. Нажмите «+ Создать шаблон» или откройте существующий.

3. Перед вами — редактор документа, разделённый на три зоны: верхний колонтитул, тело документа и нижний колонтитул.

В правой панели два вкладки:

• «Настройки» — выберите сущность и режим формирования

• «Поля сущности» — справочник всех доступных переменных

Настройки шаблона (правая панель)

Сущность

Выберите, для каких карточек будет работать этот шаблон: Осмотр, Замечание, Сделка и т. д. После выбора сущности вкладка «Поля сущности» покажет все доступные переменные.

Режим формирования

Дополнительная опция «Разрешить массовую печать из списка» — позволяет в списке отметить несколько строк и скачать ZIP-архив, где на каждую карточку — свой документ (как "Печать одного документа"), но сразу по нескольким сущностям.

Как работают переменные (теги)

Переменная — это имя поля, обёрнутое в двойные фигурные скобки:

{{ room.number }}

Система найдёт это место в шаблоне и заменит его реальным значением. Например, {{ room.number }} превратится в 47.

Откуда брать имена переменных

Откройте вкладку «Поля сущности» в правой панели. Там перечислены все доступные поля с подсказками. Нажмите на поле — оно автоматически вставится в нужное место документа.

Поля делятся на два вида:

Прямые поля — вставляются сразу:

{{ id }}            → ID осмотра, например: 1042
{{ created_at }}     → дата создания приёмки, например: 2025-01-15

Поля через связь — через точку, сначала имя связи, потом поле:

{{ room.number }}   → номер квартиры, например: 47
{{ room.area }}     → площадь квартиры, например: 52.4
{{ responsible.full_name }}  → ФИО ответственного

Вставка тегов в редакторе

В редакторе теги отображаются как цветные «пилюли»:

• синие — переменные {{ значение }}

• зелёные — управляющие конструкции {% for %}, {% if %} и т. д.

Чтобы вставить тег:

1. Поставьте курсор в нужное место.

2. В панели инструментов нажмите кнопку «Вставить тег».

3. Введите имя переменной и нажмите Enter.

Или дважды щёлкните на уже вставленный тег — откроется редактирование.

Простые поля — примеры

Номер квартиры

Квартира № {{ room.number }}

Результат: Квартира № 47

Площадь и этаж

Площадь: {{ room.area }} кв.м, этаж: {{ room.floor.number }}

Результат: Площадь: 52.4 кв.м, этаж: 8

Дата приёмки

Дата приёмки: {{ take_date_start }}

Результат: Дата приёмки: 2025-01-15

Функции форматирования (фильтры)

Фильтры применяются через символ | (вертикальная черта). Пишется так: {{ переменная|фильтр }}.

Форматирование даты — date

По умолчанию даты хранятся в формате ГГГГ-ММ-ДД. Фильтр date переводит их в читаемый вид.

{{ take_date_start|date }}

Результат: 15.01.2025

Можно указать свой формат:

{{ take_date_start|date('d/m/Y') }}

Результат: 15/01/2025

Текущая дата (дата формирования документа) — используйте специальное слово "now":

Документ сформирован: {{ "now"|date }}

Результат: Документ сформирован: 12.06.2026

Дата с месяцем прописью — dateToWords

{{ take_date_start|dateToWords }}

Результат: 15 января 2025

Формат по умолчанию — d F Y. Можно изменить:

{{ take_date_start|dateToWords('d F') }}

Результат: 15 января

Число прописью — numberToWords

Для вывода любого числа (площадь, количество и т. д.):

Площадь: {{ room.area|numberToWords }}

Результат: Площадь: пятьдесят два целых четыре десятых

Сумма прописью — priceToWords

Для денежных сумм — то же самое, но ориентировано на цены:

Стоимость: {{ room.price|priceToWords }}

Результат: Стоимость: три миллиона пятьсот тысяч

Условия — показывать блок только если данные есть

Используйте {% if %} … {% endif %} чтобы показать часть документа только при выполнении условия.

Проверка на наличие замечаний

{% if remarks %}
В ходе осмотра выявлены следующие замечания.
{% endif %}

Если замечаний нет — этот абзац не появится в документе.

Проверка на наличие и вывод текста

{% if remarks %}
Количество замечаний: {{ remarks|length }}
{% else %}
Замечания не выявлены.
{% endif %}

remarks|length — количество элементов в списке.

Проверка конкретного поля

{% if room.area %}
Общая площадь помещения составляет {{ room.area }} кв.м.
{% endif %}

Циклы — вывод списков

Используйте {% for %} … {% endfor %} для перебора списков.

Список покупателей

Переменная clients — это список покупателей из приемки. Каждый элемент — объект с полями full_name, phone, email.

Участники приёмки:
{% for client in clients %}
— {{ client.full_name }}, тел.: {{ client.phone }}
{% endfor %}

Результат:

Участники приёмки:
— Иванов Иван Иванович, тел.: +7 900 123-45-67
— Петрова Анна Сергеевна, тел.: +7 911 987-65-43

Список замечаний

Переменная remarks — список замечаний, выявленных на осмотре.

{% for remark in remarks %}
{{ loop.index }}. {{ remark.comment }}
   Плановая дата устранения: {{ remark.date_planned|date }}
{% endfor %}

loop.index — порядковый номер (1, 2, 3...).

Результат:

1. Трещина в штукатурке на стене у окна
   Плановая дата устранения: 01.03.2025
2. Царапины на стеклопакете
   Плановая дата устранения: 15.02.2025

Изображения

Для вывода фотографий используется специальная функция image().

Фотография замечания

В цикле по замечаниям, каждое замечание имеет список вложений remark.attachments. Чтобы вывести первую фотографию:

{% for remark in remarks %}
  {{ remark.comment }}
  {{ image(remark.attachments[0]) }}
{% endfor %}

Ограничение размера изображения

По умолчанию изображение занимает всю ширину листа (до 650 пикселей), если не указывать ничего. Но можно указать свою ширину в пикселях:

{{ image(remark.attachments[0], 300) }}

Соотношение сторон при указании ширины сохраняется автоматически.

Несколько фотографий замечания

Если нужны все фотографии - сначала цикл по замечаниям, внутри каждого замечания цикл по его прикрепленным файлам (attachments):

{% for remark in remarks %}
  {{ remark.comment }}
  {% for photo in remark.attachments %}
    {{ image(photo) }}
  {% endfor %}
{% endfor %}

Отметки на плане (план замечания)

Замечание может содержать привязку к плану квартиры. Для вывода плана с нанесёнными отметками используется та же функция image, только передаётся поле plan замечания:

{% for remark in remarks %}
  {{ remark.comment }}
  {% if remark.plan %}
   {{ image(remark.plan) }}
  {% endif %}
{% endfor %}

Если замечание не привязано к плану, блок {% if remark.plan %} скроет изображение и не будет показана пустая рамка.

Таблицы

Обычная таблица

Создайте таблицу через панель инструментов редактора. Чтобы вставить переменную в ячейку — поставьте курсор в ячейку и вставьте тег обычным способом.

Пример таблицы с данными осмотра:

Зациклить строку таблицы («повторять строку для каждого элемента»)

Чтобы в таблице автоматически добавлялась строка на каждое замечание (или каждого покупателя):

1. Выделите строку таблицы, которую нужно повторить.

2. В панели инструментов нажмите «Зациклить строку» (это создаст Twig-цикл в строке).

3. Введите выражение цикла, например: remark in remarks (первое слово - любое название переменной, второе - название связи, массива данных из сущности)

4. В ячейках этой строки вставляйте поля через имя переменной цикла: {{ remark.comment }}, {{ remark.date_planned|date }}.

Пример строки с перечислением замечаний из приемки "remark in remarks":

При формировании документа система автоматически повторит эту строку для каждого замечания.

Полный пример: «Акт осмотра помещения»

Ниже — шаблон, который можно взять за основу. Он использует все описанные выше возможности на примере сущности "Приемка".

[Верхний колонтитул]

ООО «Застройщик»                             АКТ № {{ id }} от {{ "now"|date }}

[Тело документа]

АКТ ОСМОТРА ПОМЕЩЕНИЯ

г. Москва                                    {{ "now"|dateToWords }}

Объект: {{ room.house.name }}, квартира № {{ room.number }},
этаж {{ room.floor.number }}, общая площадь {{ room.area }} кв.м.

Дата приёмки: {{ take_date_start|dateToWords }}

---

УЧАСТНИКИ ОСМОТРА

Ответственный со стороны застройщика:
{{ responsible.full_name }}

{% if clients %}
Участники со стороны покупателей:
{% for client in clients %}
  {{ loop.index }}. {{ client.full_name }}
     Телефон: {{ client.phone }}
     Email: {{ client.email }}
{% endfor %}
{% endif %}

---

РЕЗУЛЬТАТЫ ОСМОТРА

{% if remarks %}
В ходе осмотра выявлено {{ remarks|length }} замечание(й):

{% for remark in remarks %}
Замечание № {{ loop.index }}
Описание: {{ remark.comment }}
{% if remark.instruction %}
Инструкция по устранению: {{ remark.instruction }}
{% endif %}
{% if remark.date_deadline %}
Срок устранения: {{ remark.date_deadline|date }}
{% endif %}

{% if remark.attachments %}
Фотофиксация:
{{ image(remark.attachments[0], 400) }}
{% endif %}

{% if remark.plan %}
Отметка на плане:
{{ image(remark.plan, 400) }}
{% endif %}

{% endfor %}

{% else %}
В ходе осмотра замечания не выявлены. Помещение передаётся в надлежащем состоянии.
{% endif %}

---

ИТОГ

Помещение осмотрено « {{ take_date_start|dateToWords("d") }} » {{ take_date_start|dateToWords("F Y") }} г.

{% if remarks %}
Общее количество замечаний: {{ remarks|length }}
{% endif %}

---

ПОДПИСИ СТОРОН

Передал (застройщик): ___________________  {{ responsible.full_name }}

{% for client in clients %}
Принял: ___________________  {{ client.full_name }}
{% endfor %}

[Нижний колонтитул]

Акт № {{ id }} | {{ "now"|date }}                              Страница {page} из {pages}

Справочник всех фильтров и функций

Справочник переменных Приемки (Inspection)

Полный список всех полей всегда доступен во вкладке «Поля сущности» в правой панели редактора.

Частые вопросы

Поле показывает пустоту вместо значения — проверьте имя переменной во вкладке «Поля сущности». Имена чувствительны к регистру: room.Number не то же самое, что room.number.

Связанные данные не отображаются — некоторые связи (например, clients, remarks, room) нужно явно включить. Они называются «embed-параметры». Если данных нет — обратитесь к администратору, возможно нужно включить нужный embed в настройках сущности.

Нет кнопки «Печать» в карточке осмотра — шаблон появится в карточке только если у него выбрана правильная Сущность в настройках (вкладка «Настройки» → поле «Сущность»).

Дата выводится в формате 2025-01-15 вместо 15.01.2025 — добавьте фильтр: {{ take_date_start|date }}.

Хочу цикл внутри таблицы — используйте функцию «Зациклить строку» (выделите строку таблицы → кнопка в тулбаре "Действия с таблицей"). Это позволит повторять строку для каждого элемента списка без ручной записи {% for %}.