Синтаксис команд генератора

Основы формирования шаблонов документов¶

Документ формируется в любом редакторе, поддерживающем формат docx:

Порядок создания шаблона документов¶

В редакторе создайте файл документа и наполните его всеми необходимыми данными, включая графику, картинки, заголовки
Отформатируйте документ как он должен выглядеть, включая стили и заголовки.
Замените переменные параметры специальными командами Генератора документов
Сохраните документ с расширением docx на диск ПК
Загрузите шаблон в приложение Генератор документов
Настройте бизнес-процессы для применения генератора документов

Основной синтаксис шаблона документа
Многоуровневые данные шаблона документа
Управляющие команды в шаблоне документа
Специальные фильтры в шаблоне документа
Специальные тесты в шаблоне документа
Глобальные функции
Назначение переменных
Расширенный режим настроек шаблона

Основной синтаксис генератора документов¶

Внутренний объект данных генератора документов¶

Запуск генерации документа на основании шаблона происходит:

Из карточки объекта Битрикс24 (например из сделки или контакта, причем из конкретной сделки и конкретного контакта, карточка которого сейчас открыта на экране). В результате такого запуска на вход шаблону генератора документов передается информация о типе объекта и его идентификатор. Т.е. шаблон получает структуру данных заполненную конкретными данными текущего сделки или контакта.

Например если вы откроете карточку сделки, у которой ID=2, то на вход шаблону будет передана информация, что тип объекта сделка (crm_deal), а идентификатор экземпляра ID=2.

Генератор документов создаст внутренний объект под именем obj у которого будет структура данных полностью соответствовать структуре данных сделка (crm_deal), имена полей объекта obj будут такими же, как и имена полей сущности сделка, а значение полей объекта obj будут полностью соответствовать значению полей объекта сделка с ID=2.

Второй вариант запуска генератора документов, это запуск из бизнес-процесса.

При запуске из бизнес-процесса, на вход шаблона генератора документов также передаются Тип сущности (тип объекта) и его идентификатор.

Генератор также создает внутренний объект obj у которого будет структура данных полностью соответствовать структуре данных заданных в активити бизнес-процесса (подробнее настройку бизнес-процессов генератора документов), имена полей объекта obj будут такими же, как и имена полей типа сущности crm_deal, crm_contact, crm_item_<id-sp> и т.д., а значение полей объекта obj будут полностью соответствовать значению экземпляра объекта с полученным на вход идентификатором {{ID}}.

Типы сущностей Битрикс24

В Битрикс24 наименование сущностей пишется заглавными буквами, в поле настроек шаблона допускается использование строчными буквами. С полным списком сущностей и их описанием можно ознакомиться на портале Битрикс24 в разделе документация API

CRM_ACTIVITY = "crm_activity"
CRM_ADDRESS = "crm_address"
CRM_CATEGORY = "crm_category"
CRM_COMPANY = "crm_company"
CRM_CONTACT = "crm_contact"
CRM_CURRENCY = "crm_currency"
CRM_DEAL = "crm_deal"
CRM_DEALCATEGORY = "crm_dealcategory"
CRM_ITEM_PRODUCTROW = "crm_item_productrow"
CRM_ITEM = "crm_item"
CRM_LEAD = "crm_lead"
CRM_MEASURE = "crm_measure"
CRM_PRODUCT = "crm_product"
CRM_QUOTE = "crm_quote"
CRM_REQUISITE = "crm_requisite"
CRM_SMART_INVOICE = "crm_smart_invoice"
CRM_STATUS = "crm_status"
CRM_TYPE = "crm_type"
DEPARTMENT = "department"
TASK_ELAPSED_ITEM = "task_elapsed_item"
TASK = "task"
VOXIMPLANT_STATISTIC = "voximplant_statistic"
USER = "user"

Переменные данные в шаблонах документов¶

Для вставки значения поля в шаблон документа, переменную Битрикс24 со значением необходимо «обернуть» двойными фигурными скобками {{ obj.OPPORTUNITY }} и при генерации документа, вместо текста в фигурных скобках, будет подставлено реально значение из вашего объекта (сделки, компании и т.д.).

SYNTAX

Например: для выведения в документ параметров сделки, необходимо передать в шаблон в настройках Тип объекта crm_deal и ID конкретной сделки, тогда:

Поле {{ obj.DATE_CREATE }} — вставит в текст документа дату создания сделки, а поле {{ obj.OPPORTUNITY }} — сумму сделки, {{ obj.COMPANY_NAME }} — название компании контрагента и т.д.

Полный список полей сделки смотрите в разделе Имена полей Сделки

Имена полей СДЕЛКИ Битрикс24

ID — Идентификатор сделки (Число)
DATE_CREATE — Дата и время создания сделки (Дата)
CREATED_BY_ID — Идентификатор сотрудника, создавшего сделку (Число)
CREATED_BY — Идентификатор и имя сотрудника, создавшего сделку (Строка)
CREATED_BY_NAME — Имя сотрудника, создавшего сделку (Строка)
DATE_MODIFY — Дата и время последнего изменения сделки (Дата)
MODIFY_BY_ID — Идентификатор сотрудника, изменившего сделку (Число)
MODIFIED_BY — Идентификатор и имя сотрудника, изменившего сделку (Строка)
MODIFIED_BY_NAME — Имя сотрудника, изменившего сделку (Строка)
ASSIGNED_BY_ID — Идентификатор сотрудника, ответственного за сделку (Число)
ASSIGNED_BY — Идентификатор и имя сотрудника, ответственного за сделку (Строка)
ASSIGNED_BY_DEPARTMENT — Идентификатор и название отдела ответственного сотрудника (Строка)
ASSIGNED_BY_NAME — Имя сотрудника, назначенного ответственным за сделку (Строка)
MOVED_BY_ID — Идентификатор сотрудника, сменившего стадию сделки (Число)
MOVED_BY — Идентификатор и имя сотрудника, сменившего стадию сделки (Строка)
MOVED_BY_NAME — Имя сотрудника, сменившего стадию сделки (Строка)
MOVED_TIME — Дата и время смены стадии сделки (Дата)
LEAD_ID — Идентификатор лида, который был сконвертирован в сделку (Число)
COMPANY_NAME — Название компании (Строка)
COMPANY_ID — Идентификатор компании, связанной со сделкой (Число)
COMPANY — Идентификатор и название компании, связанной со сделкой (Строка)
CONTACT_ID — Идентификатор контакта, связанного со сделкой (Число)
CONTACT_NAME — Название контакта (Строка)
CONTACT — Идентификатор и имя контакта, связанного со сделкой (Строка)
OPENED — Опция «Доступна для всех» в сделке: Y — да, N — нет (Строка)
TITLE — Название сделки (Строка)
CRM_PRODUCT — Идентификатор и название товара в сделке (Строка)
CATEGORY — Идентификатор и название воронки, в которой находится сделка (Строка)
STAGE_ID — Идентификатор стадии, на которой находится сделка (Строка)
STAGE — Идентификатор и название стадии, на которой находится сделка (Строка)
STAGE_SEMANTIC_ID — Идентификатор группы стадии, на которой находится сделка: F failed — - обработана неуспешно, S (success) — обработана успешно, P (processing) — сделка в работе — (Строка))
STAGE_SEMANTIC — Название группы стадий, на которой находится сделка: успех, провал, в работе (Строка)
IS_NEW — Сделка находится на первой стадии: Y — да, N — нет (Строка)
IS_RECURRING — На основании этого шаблона создаются регулярные сделки: Y — да, N — нет (Строка)
IS_RETURN_CUSTOMER — Повторная сделка: Y — да, N — нет (Строка)
CLOSED — Сделка на финальной стадии: Y — да, N — нет (Строка)
TYPE_ID — Тип сделки (Строка)
OPPORTUNITY_ACCOUNT — Сумма в валюте отчетов (Число)
OPPORTUNITY — Сумма сделки (Число)
IS_MANUAL_OPPORTUNITY — Сумма сделки введена вручную: Y — да, N — нет (Строка)
TAX_VALUE — Налог (Число)
TAX_VALUE_ACCOUNT — Налог в валюте отчетов (Число)
CURRENCY_ID — Базовая валюта (Строка)
ACCOUNT_CURRENCY_ID — Валюта отчета (Строка)
PROBABILITY — Вероятность успешного закрытия сделки (Число)
COMMENTS — Комментарии в сделке (Строка)
BEGINDATE — Время открытия сделки. Устанавливается автоматически и совпадает с датой создания (Дата)
CLOSEDATE — Планируемая дата закрытия сделки. По умолчанию устанавливается на 7 дней позже даты создания сделки (Дата)
LOCATION_ID — Местоположение клиента (Число)
SOURCE_ID — Идентификатор источника (Строка)
SOURCE — Идентификатор и название источника, из которого создана сделка (Строка)
SOURCE_DESCRIPTION — Описание рекламного источника (Строка)
ORIGINATOR_ID — Идентификатор внешней системы, в которой была создана сделка (Строка)
ORIGIN_ID — Идентификатор сделки во внешней системе, из которой была создана сделка (Строка)
ADDITIONAL_INFO — Дополнительная информация в сделке (Строка)
UTM_SOURCE — Рекламный источник, UTM_SOURCE в карточке сделки (Строка)
UTM_MEDIUM — Рекламный носитель, UTM_MEDIUM в карточке сделки (Строка)
UTM_CAMPAIGN — Рекламная кампания, UTM_CAMPAIGN в карточке сделки (Строка)
UTM_CONTENT — Рекламный контент, UTM_CONTENT в карточке сделки (Строка)
UTM_TERM — Рекламный термин, UTM_TERM в карточке сделки (Строка)
BANK_DETAIL_ID — Идентификатор банковских реквизитов (Число)
CRM_PRODUCT_ID — Идентификаторы товаров в карточке сделки (Число)
CRM_PRODUCT_COUNT — Количество товаров в карточке сделки (Строка)
WEBFORM_ID — Идентификатор CRM-формы, из которой была создана сделка (Число)
WEBFORM_NAME — Название CRM-формы, из которой была создана сделка (Строка)
WEBFORM — Идентификатор и название CRM-формы, из которой была создана сделка (Строка)

Например: создадим шаблон

Дата сделки {{ obj.DATE_CREATE }} на сумму {{ obj.OPPORTUNITY }} рублей
заключена с компанией {{ obj.COMPANY_NAME }}

---------------------------------------
Ответственный: {{ obj.ASSIGNED_BY_NAME}}

Итоговый документ

Дата сделки 05.11.2024 на сумму 5000.00 рублей
заключена с компанией ООО "Чистая компания"

---------------------------------------
Ответственный: Иванов С.И.

Вставка значений пользовательских полей¶

Все пользовательские поля имеют синтаксис:

UF_CRM_"порядковый номер поля" — Сведения из пользовательского поля с указанным номером, например из UF_CRM_123456789. Номер автоматически присваивается полю при создании. Этот формат применяется для всех сущностей (Сделки, контакты, компании и т.д. и номер поля уникален для всей вашей CRM)

Пример

Это значение пользовательского поля: {{obj.UF_CRM_123456789}}

Как узнать номер пользовательского поля

Чтобы узнать номер имя пользовательского поля в формате UF_CRM_"порядковый номер поля"

Перейдите в настройки CRM и выберите раздел Пользовательские поля

Выберите тип сущности, в которой вы хотите посмотреть пользовательское поле (Сделка, Лид, Компания и т.д. и кликните на надпись Список полей)

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

Добавление пользовательского поля в шаблон документа

Для добавления пользовательского поля в шаблон документа вставьте в текст {{ obj.UF_CRM_12340987 }}, где 12340987 — это номер вашего поля, которое вы увидели в адресной строке, замените значение из примера вашим значением.

Вставка вложенных структур Битрикс24¶

Сущности Битрикс24 имеют вложенные структуры и генератор документов позволяет выводить в шаблоне документов значения полей любой вложенности.

Например в структуре сделки есть поле COMPANY_ID, которое ссылается на структуру Компания со всеми данными о компании. Для генератора документов нужно указать в шаблоне следующую последовательность команд, чтобы получить данные о компании. Например нам нужен адрес компании:

Пример

Адрес компании: {{ obj.COMPANY_ID.ADDRESS_1}}
                {{ obj.COMPANY_ID.ADDRESS_2}}

Т.е. при обращении к сущности следующего уровня нам необходимо указать на первом уровне поле связку (в нашем случае COMPANY_ID) и поле назначение.

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

Допустим нам нужно ФИО ответственного по компании получить из сделки. Ответственного по компании можно определить из карточки компании по полю связке ASSIGNED_BY_ID и значению поля NAME для имени ответственного.

Пример

Ответственный за компанию: {{ obj.COMPANY_ID.ASSIGNED_BY_ID.NAME}}

Поля сущности Компания

ID — Идентификатор компании (Число)
DATE_CREATE — Дата и время создания карточки компании (Дата)
DATE_MODIFY — Дата и время последнего изменения карточки компании (Дата)
CREATED_BY_ID — Идентификатор создателя карточки компании (Число)
CREATED_BY — Идентификатор и имя создателя карточки компании (Строка)
CREATED_BY_NAME — Имя создателя карточки компании (Строка)
MODIFY_BY_ID — Идентификатор сотрудника, изменившего карточку компании (Число)
MODIFIED_BY_NAME — Имя сотрудника, изменившего карточку компании (Строка)
MODIFIED_BY — Идентификатор и имя сотрудника, изменившего карточку компанию (Строка)
ASSIGNED_BY_ID — Идентификатор ответственного (Число)
ASSIGNED_BY — Идентификатор и имя ответственного (Строка)
ASSIGNED_BY_NAME — Имя ответственного (Строка)
OPENED — Опция «Доступна для всех» в карточке компании: Y — да, N — нет (Строка)
TITLE — Название компании (Строка)
ADDRESS_1 — Адрес 1 (Строка)
ADDRESS_2 — Адрес 2 (Строка)
ADDRESS_CITY — Город (Строка)
ADDRESS_POSTAL_CODE — Почтовый индекс (Строка)
ADDRESS_REGION — Регион (Строка)
ADDRESS_PROVINCE — Область (Строка)
ADDRESS_COUNTRY — Страна (Строка)
ADDRESS_COUNTRY_CODE — Код страны (Строка)
BANKING_DETAILS — Банковские реквизиты (Строка)
COMMENTS — Комментарии (Строка)
COMPANY_TYPE_ID — Идентификатор типа компании (Строка)
COMPANY_TYPE_NAME — Название типа компании (Строка)
COMPANY_TYPE — Идентификатор и название типа компании (Строка)
INDUSTRY_ID — Идентификатор сферы деятельности (Строка)
INDUSTRY_NAME — Название сферы деятельности (Строка)
INDUSTRY — Идентификатор и название сферы деятельности компании (Строка)
REVENUE — Годовой оборот (Число)
CURRENCY_ID — Валюта (Строка)
EMPLOYEES — Количество сотрудников (Строка)
LEAD_ID — Идентификатор лида, связанного с компанией (Число)
ORIGINATOR_ID — Идентификатор внешней системы, в которой была создана компания (Строка)
ORIGIN_ID — Идентификатор компании во внешней системе (Строка)
ORIGIN_VERSION — Версия данных компании во внешней системе. Используется для отслеживания изменений и синхронизации данных (Строка)
IS_MY_COMPANY — Признак «Моя компания»: Y — да, N — нет. Используется для обозначения ваших компаний (Строка)
UTM_SOURCE — Рекламный источник, UTM_SOURCE в карточке компании (Строка)
UTM_MEDIUM — Рекламный носитель, UTM_MEDIUM в карточке компании (Строка)
UTM_CAMPAIGN — Рекламная кампания, UTM_CAMPAIGN в карточке компании (Строка)
UTM_CONTENT — Рекламный контент, UTM_CONTENT в карточке компании (Строка)
UTM_TERM — Рекламный термин, UTM_TERM в карточке компании (Строка)
PHONE — Телефон (Строка)
WEB — URL-адреса сайтов, которые связаны с компанией (Строка)
EMAIL — Email (Строка)
IM — Мессенджеры (Строка)

Поля сущности Контакт

ID — Идентификатор контакта (Число)
DATE_CREATE — Дата и время создания контакта (Дата)
DATE_MODIFY — Дата и время последнего изменения контакта (Дата)
CREATED_BY_ID — Идентификатор создателя (Число)
CREATED_BY — Идентификатор и имя создателя (Строка)
CREATED_BY_NAME — Имя создателя (Строка)
MODIFY_BY_ID — Идентификатор сотрудника, изменившего карточку контакта (Число)
MODIFIED_BY_NAME — Имя сотрудника, изменившего карточку контакта (Строка)
MODIFIED_BY — Идентификатор и имя сотрудника, изменившего карточку контакта (Строка)
ASSIGNED_BY_ID — Идентификатор ответственного (Число)
ASSIGNED_BY — Идентификатор и имя ответственного (Строка)
ASSIGNED_BY_NAME — Имя ответственного (Строка)
OPENED — Опция «Доступен для всех» в карточке контакта: Y — да, N — нет (Строка)
COMPANY_ID — Идентификатор компании (Число)
SOURCE_ID — Идентификатор источника (Строка)
SOURCE_DESCRIPTION — Описание источника (Строка)
NAME — Имя (Строка)
LAST_NAME — Фамилия (Строка)
SECOND_NAME — Отчество (Строка)
POST — Должность (Строка)
ADDRESS_1 — Адрес 1 (Строка)
ADDRESS_2 — Адрес 2 (Строка)
ADDRESS_CITY — Город (Строка)
ADDRESS_POSTAL_CODE — Почтовый индекс (Строка)
ADDRESS_REGION — Регион (Строка)
ADDRESS_PROVINCE — Область (Строка)
ADDRESS_COUNTRY — Страна (Строка)
ADDRESS_COUNTRY_CODE — Код страны (Строка)
COMMENTS — Комментарии (Строка)
LEAD_ID — Идентификатор лида, связанного с контактом (Число)
EXPORT — Участвует в экспорте: Y - да, N - нет (Строка)
TYPE_ID — Идентификатор типа, например, CLIENT (Строка)
ORIGINATOR_ID — Идентификатор внешней системы, в которой был создан контакт (Строка)
ORIGIN_ID — Идентификатор контакта во внешней системе (Строка)
ORIGIN_VERSION — Версия данных контакта во внешней системе. Используется для отслеживания изменений и синхронизации данных (Строка)
BIRTHDATE — Дата рождения (Дата)
HONORIFIC — Код обращения, например, HNR_RU_1 (Строка)
FACE_ID — Идентификатор faceid (Число)
PHONE — Телефон (Строка)
WEB — URL-адреса сайтов, которые связаны с контактом (Строка)
EMAIL — Email (Строка)
IM — Мессенджеры (Строка)
UTM_SOURCE — Рекламный источник, UTM_SOURCE в карточке контакта (Строка)
UTM_MEDIUM — Рекламный носитель, UTM_MEDIUM в карточке контакта (Строка)
UTM_CAMPAIGN — Рекламная кампания, UTM_CAMPAIGN в карточке контакта (Строка)
UTM_CONTENT — Рекламный контент, UTM_CONTENT в карточке контакта (Строка)
UTM_TERM — Рекламный термин, UTM_TERM в карточке контакта (Строка)

Доступ к данным Смарт-процесса¶

Смарт процесс — это самостоятельная единица хранения данных в Битрикс24 любой сложности. Для обращения к полям смарт процесса необходимо в настройках генератора указать тип сущности crm_item_<id смарт-процесса> (Подробнее смотри раздел настройки)

Как узнать ID смарт-процесса

Перейдите в список смарт-процессов вашей CRM
В строке с названием смарт-процесса получите номер ID смарт-процесса
Если ID смарт-процесса равно 64, то при настройке активити в поле Типа базового объекта вам необходимо указать: crm_item_64

Для указания полей смарт-процесса в настройках шаблона:

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

Преобразование полей смарт-процесса

Для правильного указания названия поля смарт-процесса в Генераторе документов необходимо код поля, указанного в таблице преобразовать к следующему формату:

UF_CRM_2_1698741796 необходимо преобразовать в формат ufCrm2_1698741796, т.е. обозначение UF_CRM_2 преобразуется в ufCrm2, а UF_CRM_7 преобразуется в ufCrm7. При этом числовое значение поля после подчеркивания остается неизменным.

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

SYNTAX

Исполнитель услуги: {{obj.ufCrm2_1698741796}}

Управляющие команды¶

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

Управляющие команды упаковываются в специальный синтаксис су указанием знака % возле двойных фигурных скобок:

SYNTAX

{% команда %}

Внимание

Установка пробелов между { и % не допускаются, это ошибка. ~~{ %~~ и ~~% }~~ Правильно: {% команда %}

Команда условие `IF`¶

Следующие пример выведет содержимое блока IF — ENDIF если условие истинно, в противном случае ничего не выведет.

SYNTAX

{% if obj."название поля для проверки"=="значение для проверки" %}
        Вывести этот текст, если условие поля удовлетворяет
{% endif %}

Более сложный пример с двумя проверками IF и ELIF и значением ELSE, которое выполнится если не выполнится ни одно из условий IF. Т.е. в такой конструкции, вы можете назначать любое количество блоков ELIF и последний блок ELSE.

SYNTAX

{% if obj.CONTACT_ID %}
    Если есть контакт у сделки, то напечатать этот текст.
{% elif obj.COMPANY_ID %}
    Если есть в сделке компания, то напечатать этот текст
{% else %}
    Напечатать этот текст, если нет ни контакта ни компании
{% endif %}

операторы сравнения

При выполнении сравнения в генераторе возможно использование операторов сравнения:

== — Сравнивает два объекта для равенства.
!= — Сравнивает два объекта для неравенства.
> — true если левая сторона руки больше, чем правая.
>= — true если левая сторона больше или равна правой стороне руки.
< — true если левая сторона руки ниже, чем правая.
<= — true если левая сторона руки ниже или равна правой стороне руки.

логические операторы

При выполнении сравнения в генераторе возможно использование логических оператор и группировать выражения с помощью ( и ):

and — логическое И
or — логическое ИЛИ
not — логическое отрицание not X, если X=false, то сравнение даст true. Для отрицания операторов is и in, используется постфиксная нотация: is not; in not;

Команда цикла `FOR`¶

Для работы со списочными переменными применяется команда FOR IN ENDFOR

Выведем в нашем документе список всех значений через дефис:

SYNTAX

{% for row in obj."списочное поле Битрикс24" %}
    - {{ row }}
{% endfor %}

в выражении for row — создали внутреннюю переменную, в которую будут передаваться значения списка поочередно
obj."списочное поле Битрикс24" — указываем имя списочного поля Битрикс24
команда {{row}} — будет выводить только одно значение из списка на каждой итерации цикла
endfor — завершает блок цикла

Специальные команды в FOR

loop.index — Текущая итерация цикла. (1 индексируется)
loop.index0 — Текущая итерация цикла. (0 индексируется)
loop.revindex — Количество итераций из конца цикла (1 индексируется)
loop.revindex0 — Количество итераций из конца цикла (0 проиндексировано)
loop.first — Правда, если первая итерация.
loop.last — Правда, если последняя итерация.
loop.length — Количество элементов в последовательности.
loop.cycle — Функция помощника для цикла между списком оследовательности. См. пояснение ниже.
loop.depth — Указывает, насколько глубоко в рекурсивной петле рендеринг настоящее время. Начинается на уровне 1
loop.depth0 — Указывает, насколько глубоко в рекурсивной петле рендеринг настоящее время. Начинается на уровне 0
loop.previtem — Пункт из предыдущей итерации цикла. Неопределённое в оде первой итерации.
loop.nextitem — Пункт из следующей итерации цикла. Неопределённое во ремя последней итерации.
loop.changed(*val) — Правда, если раньше звонили с другим значением (или е называется вообще).

Пример

{% for row in rows %}
    <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
{% endfor %}

Блоки комментариев в шаблонах¶

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

Для установки комментария в шаблоне, оберните текст с комментариями в фигурные скобки с хэштегом {# комментарий #}

SYNTAX

{# комментарий #}

Контроль над пробелами¶

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

Например в блоке выведения цикла, если нам нужно подавить вывод пробелов перед и после значением элемента списка, то нужно поставить -%} {{выводимый элемент }} {%- — обратите внимание, что скобки одинарные и стоит знак минус, для подавления пробелов перед и после выводимого значения.

SYNTAX

{% for item in obj.список -%}
    {{ item }}
{%- endfor %}

Если в нашем примере obj.список содержит значения [1,2,3,4,5,6,7,8,9], то на выходе мы получим 123456789

Если нам нужно добавить пробелы между элементами списка, то необходимо поставить +%} {{выводимый элемент }} {%+ — обратите внимание, что скобки одинарные и стоит знак плюс, для установки пробелов перед и после выводимого значения.

SYNTAX

{% for item in obj.список +%}
    {{ item }}
{%+ endfor %}

Если в нашем примере obj.список содержит значения [1,2,3,4,5,6,7,8,9], то на выходе мы получим 1 2 3 4 5 6 7 8 9

Специальные фильтры¶

В генераторе документов предусмотрены специальные фильтры, которые можно применить к значению переменных, находящиеся внутри блока фильтра.

Три варианта применения фильтров в шаблоне:

Блок фильтра начинается с команды filter и специального названия фильтра, который будет применен к блоку. Завершается блок фильтра командой endfilter.
Фильтр добавляется к полю в формате: {{obj.COMPANY_NAME.title()}} — вернет название компании с заглавной буквы.
Фильтр добавляется к полю через | вертикальную черту {{obj.COMPANY_NAME | title() }}, также вернет значение как и в предыдущем случае, наименование компании с заглавной буквы.

Этот пример напечатает в шаблоне наименование компании с заглавной буквы:

SYNTAX

{% filter title %}
    {{ obj.COMPANY_NAME}}
{% endfilter %}

или

{{obj.COMPANY_NAME.title()}}

или

{{obj.COMPANY_NAME | title() }}

Список фильтров

Список Встроенных Фильтров

abs() — абсолютное значение аргумента.
attr(obj: Any, name: str) — возвращает аттрибуты объекта
map(value: Iterable[Any], args: Any, *kwargs: Any) — Применяет фильтр к последовательности объектов или ищет атрибут. Это полезно при работе со списками объектов. {{ users|map(attribute='username')|join(', ') }} — на вход получаем список пользователей и возвращем все username через запятую.
select() — применяет тест к объекту и выводит в случае истины теста
selectattr(value: 't.Iterable[V]', args: Any, *kwargs: Any) — отбирает аттрибуты сложного объекта, возращает список аттрибутов и их значения
unique() — вернет список уникальных значений
format(value: str, args: Any, *kwargs: Any) — выводит форматированный текст {{ "%s, %s!"|format(greeting, name) }} или {{ "{}, {}!".format(greeting, name) }}
max() — вернет максимальное значение из списка
upper() — переводит текст в заглавные буквы
min() — вернет минимальное значение списка
capitalize() — возвращает строку, где каждое слово с заглавной буквы
sort() — сортирует список значений
center(value: str, width: int = 80) — центрирует текст в поле заданной ширины
int() — возвращает целое число
random() — возвращает случайное число
string() — преобразует в текст
wordcount() — считает количество слов в строке
reject() — применяет тест к каждому объекту
wordwrap() — текст вернется заданной ширины в символах
join() — объединяет список через указанные разделители {{ [1, 2, 3]|join('|') }} -> 1|2|3; {{ [1, 2, 3]|join }} -> 123;
sum() — вернет сумму списка
last() — вернет последнее значение списка
replace() — заменяет значение текста в подстроке
title() — начинаться текст будет с заглавной, остальные строчные
length() — длина строки
reverse() — вернет список в обратном порядке
first() — вернет первый элемент списка
list() — возвращает список
round() — округляет число
trim() — удаляет пробелы
float() — возвращает число с плавающей точкой
lower() — текст строчными буквами

Специальные Тесты¶

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

Тесты — это встроенные функции и переменные генератора документов, применение тестов в шаблонах позволяет делать дополнительные проверки переменных. Блок теста начинается с ключевого слова IF — переменная которую проверяем — ключевое слово IS — функция теста.

Или в контексте проверки значения переменной без ключевого слова IS: {% if obj.<числовое поле>.divisibleby(3) %}

SYNTAX

{% if obj.<числовое поле> is divisibleby(3) %}
    Число делится на 3
{% endif %}

или 

{% if obj.<числовое поле>.divisibleby(3) %}
     Если число делится на 3, то напечатается эта строка
{% endif %}

Список тестов генератора документов

boolean() — поле логического типа
even() — Возвращает true, если переменная четная.
in() — проверяет,что значение входит в список
sequence() — Возвращает true, если переменная является последовательностью.
false() — Возвращает true, если объект является False.
integer() — Возвращает true, если объект является целым числом.
ne() — проверяет на !=
string()— Возвращает true, если переменная строка.
iterable() — Проверьте, можно ли выполнить итерацию по объекту.
none() — Возвращает true, если переменная пустая.
divisibleby() — проверяет на делимость переменной
float() — Возвращает true, если объект является float.
le() — проверяет на <=
number() — Возвращает true, если переменная является числом.
true() — Возвращает true, если объект является True.
eq() — проверяет на равенство переменной значению
ge() — проверяет на >=
lower() — Возвращает true, если переменная имеет нижний регистр.
odd() — Возвращает true, если переменная нечетная.
gt() — проверяет на >
lt() — проверяет на <
upper() — Возвращает true, если переменная имеет верхний регистр.

Назначение переменных¶

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

SYNTAX

{% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %}
{% set key, value = call_something() %}
{% set iterated = false %}

Переменные могут быть в виде блоков, которые многократно можно использовать в документе:

Пример

{% set navigation %}
    <li><a href="/">Index</a>
    <li><a href="/downloads">Downloads</a>
{% endset %}

Размещаем в шаблоне:

{{ navigation }}
{{ navigation }}

Глобальные функции¶

Функция RANGE¶

Возвращает список, содержащий арифметическую прогрессию целых чисел.

SYNTAX

range([start, ]stop[, step])

Следующий пример выведет список от 1 до 10:

Пример

{% for number in range(1,10) %}
<li class="empty"><span>number</span></li>
{% endfor %}

Функция DICT¶

Удобная альтернатива литералам dict. {'foo':'bar'} - это то же самое, что и dict(foo='bar').

Функция CYCLER¶

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

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

Пример

{% set row_class = cycler("odd", "even") %}
<ul class="browser">
{% for folder in folders %}
<li class="folder {{ row_class.next() }}">{{ folder }}
{% endfor %}
{% for file in files %}
<li class="file {{ row_class.next() }}">{{ file }}
{% endfor %}
</ul>

Пространство имен NAMESPACE¶

Создает новый контейнер, позволяющий присваивать атрибуты с помощью тега {% set %}:

SYNTAX

{% set ns = namespace() %}
{% set ns.foo = 'bar' %}

Все переменные в пространстве имен не пересекаются с именами в другом пространстве имен.

Специальные теги управления шаблонами¶

Чтобы управлять абзацами, строками таблиц, столбцами таблиц, прогонами, необходимо использовать специальные теги ({%p, {%tr,{%tc,{%r):

SYNTAX

{%p ваша команда if, for, set %} для параграфа
{%tr ваша команда if, for, set %} для строк таблицы
{%tc ваша команда if, for, set %} для колонок таблицы
{%r ваша команда if, for, set %} для форматированных вставок документа

Специальный тег `{%p` новый абзац¶

Пример

{%p if display_paragraph %}
Выводим в формате Word новый параграф
{%p endif %}

Специальный тег `{%tr` строка таблицы¶

Создадим блок цикла FOR с тегом строки таблицы и внутри тега разместим шаблон заполнения таблицы

Пример

{%tr for debt in debts_list %}
1.{{ loop.index }}  {{ debt.ufCrm47_1735105058}}    {{ debt.ufCrm47_1735202292}}    {{ debt.ufCrm47_1735105148}}    {{ debt.ufCrm47_1742815487}}    {{ debt.ufCrm47_1742816797}}
{%tr endfor %}

Специальные команды в FOR

loop.index — Текущая итерация цикла. (1 индексируется)
loop.index0 — Текущая итерация цикла. (0 индексируется)
loop.revindex — Количество итераций из конца цикла (1 индексируется)
loop.revindex0 — Количество итераций из конца цикла (0 проиндексировано)
loop.first — Правда, если первая итерация.
loop.last — Правда, если последняя итерация.
loop.length — Количество элементов в последовательности.
loop.cycle — Функция помощника для цикла между списком оследовательности. См. пояснение ниже.
loop.depth — Указывает, насколько глубоко в рекурсивной петле рендеринг настоящее время. Начинается на уровне 1
loop.depth0 — Указывает, насколько глубоко в рекурсивной петле рендеринг настоящее время. Начинается на уровне 0
loop.previtem — Пункт из предыдущей итерации цикла. Неопределённое в оде первой итерации.
loop.nextitem — Пункт из следующей итерации цикла. Неопределённое во ремя последней итерации.
loop.changed(*val) — Правда, если раньше звонили с другим значением (или е называется вообще).

Специальный тег `{%tc` колонка таблицы¶

Создадим блок цикла FOR с тегом колонки таблицы и внутри тега разместим шаблон заполнения таблицы. Наша таблица из предыдущего примера будет состоять из 6 строк и количество колонок будет равно количеству записей в переменной debts_list

Пример

{%tс for debt in debts_list %}
1.{{ loop.index }}  {{ debt.ufCrm47_1735105058}}    {{ debt.ufCrm47_1735202292}}    {{ debt.ufCrm47_1735105148}}    {{ debt.ufCrm47_1742815487}}    {{ debt.ufCrm47_1742816797}}
{%tс endfor %}

Макросы (MACRO) в генераторе шаблонов¶

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

SYNTAX

{% macro get_value(type, field_name) -%}
{{ obj.rev("crm_item_140", "parentId2") | selectattr("ufCrm10_1698755231", "equalto", type) | map(attribute=field_name) | first }} 
{%- endmacro %}

{% macro get_value(type, field_name) -%} — объявляем макрос ключевым словом macro
Присваиваем имя макросу get_value
На вход макрос будет получать две переменные: type, field_name
Тело макроса: {{ obj.rev("crm_item_140", "parentId2") | selectattr("ufCrm10_1698755231", "equalto", type) | map(attribute=field_name) | first }}

тело макроса будет выполняться каждый раз, когда вызывается макрос в шаблоне
{%- endmacro %} — завершение макроса

Для вызова макроса будем выполнять команду со следующим синтаксисом:

{{ get_value("Паспорт", "ufCrm10_1733317301") }}, где:

значению type будет присвоено значение type="Паспорт"
значению field_name будет присвоено значение field_name="ufCrm10_1733317301"
в макросе выполнится подстановка переменных и выполнится тело макроса:

    {{ obj.rev("crm_item_140", "parentId2") | selectattr("ufCrm10_1698755231", "equalto", "Паспорт") | map(attribute="ufCrm10_1733317301") | first }}

Функция REV¶

Специальная функция генератора документов, которая позволяет выполнять запрос к структуре данных Битрикс24 и возвращать список сущностей, удовлетворяющих отправленному запросу

SYNTAX

obj.rev(entity: str,     #тип сущности в которой будет выполняться поиск
        field_name: str, #поле по которому будет выполняться поиск значений
        raw_filter: dict | None = None, # словарь {ключ: значение} для дополнительно фильтрации значений поиска
        result_filter: dict | None = None, # словарь {ключ: значение} для дополнительно фильтрации результата вывода
            )

Пример

{{ obj.rev("crm_item_140", "parentId2") | selectattr("ufCrm10_1698755231", "equalto", type) | map(attribute=field_name) | first }}

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

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

Используя функцию REV мы выполняем обращение к сущности смарт-процесса документы (crm_item_140) ищем в этом смарт процессе все записи, в которых хранится в поле ParentId2 ID нужной нам сделки и получаем список этих записей.

{{ obj.rev( — в нашем примере объект obj является сделкой
"parentId2", — поле, в котором хранится ID сделки нашего объекта obj которое будем искать в других сущностях
"crm_item_140", — тип сущности ("смарт-процесс") в котором будем искать ID сделки нашего объекта obj,а "140"— ID смарт-процесса в котором будем искать ID сделки нашего объектаobj` по полю "parentId2"
) | вертикальная черта | обозначает фильтр. Т.е. все значения запроса rev передаем на следующий шаг (в функцию на следующей строке)
selectattr("ufCrm10_1698755231", "equalto", type) — Выбрать из списочного поля ufCrm10_1698755231 значения, которые равны ("equalto" или "==") значению "type"
| — фильтр,в котором передадим найденное значение
map(attribute=field_name) — возвращаем значение, хранящееся в поле field_name
| first }} — получаем первое значение из списка и возвращаем из функции

Пример 2: Мы хотим узнать какие Дела (Activity) выполнялись по сделке. Для решения этой задачи в функцию rev необходимо передать поле для поиска OWNER_ID, сущность в которой будет поиск crm_activity и функция нам вернет список всех дел, которые были выполнены по данной сделке

Пример

obj.rev("crm_activity", "OWNER_ID")

Функция rev выполняется внутри шаблона документа и работает с текущим объектом obj, который был передан на вход генератору документов (подробнее смотри настройку генератора документов) в котором хранится тип сущности и ID сущности (например crm_deal и ID=2), которые являются неизменными до окончания генерации документа.

В примере выше в поле OWNER_ID будет подставляться для поиска значение ID=2, для поиска дел, связанных со сделкой у которой ID=2.

Фильтр raw_filter в функции REV¶

Третий не обязательный параметр функции REV.

Параметр raw_filter выполняет задачу дополнительной фильтрации при поиске связанных объектов в системе Битрикс24.

raw_filter: уточняет условия поиска связанных сущностей в Битрикс24 и позволяет добавить дополнительные критерии отбора помимо основного поля связи (field_name).

Как это работает:

Первоначально функция REV содержит только основное условие это field_name = "имя поля для поиска" Если передан raw_filter, его содержимое объединяется с field_name и поиск осуществляется по уточненной схеме включая условия переданные в raw_filter. Таким образом, raw_filter добавляет новые поля для фильтрации в запросе к Битрикс24.

Параметр raw_filter является словарем и получает значения в виде списка пар ключ — значение — {"ключ1": "значение_ключа1" "ключ2": "значение_ключа2"}, где ключ — это имя поля в Битрикс24, а значение_ключа — это значение поля, которое мы отбираем.

Пример:

Допустим, у вас есть сделка и в настройках шаблона вы указали (crm_deal), и вы хотите найти все контакты, которые:

Указаны в поле CONTACT_ID этой сделки (field_name="CONTACT_ID").
Имеют дополнительный атрибут TYPE_ID="CLIENT" (это можно передать в raw_filter).

Пример

{{ obj.rev(entity="crm_contact",
        field_name="CONTACT_ID",
        raw_filter={"TYPE_ID": "CLIENT"}
       ) }}

На выходе вы получите только те контакты, которые связаны со сделкой и соответствуют TYPE_ID="CLIENT".

raw_filter нужен для гибкого расширения условий поиска связанных объектов в Битрикс24 без изменения основного логического потока. Это полезно в сложных интеграциях, где стандартных полей связи (field_name) недостаточно.

Фильтр result_filter в функции REV¶

Четвертый параметр функции REV

Параметр result_filter используется для фильтрации уже полученных объектов после выполнения основного запроса к Битрикс24. В отличие от raw_filter (который фильтрует данные на стороне сервера), result_filter работает локально в шаблоне.

Параметр result_filter является словарем и получает значения в виде списка пар — {"ключ1": "значение_ключа1" "ключ2": "значение_ключа2"}

После того как функция REV получил список объектов с сервера, если result_filter задан будет выполнена дополнительная проверка, в итоговый результат попадут только те объекты, чьи атрибуты соответствуют условиям result_filter.

Пример

Допустим, вы ищете элементы смарт-процесса (crm_item), связанные со сделкой, но хотите оставить только те, где у ответственного (assignedById.LAST_NAME) фамилия "Иванов":

Пример

{{ obj.rev(entity="crm_item_140",
           field_name="PARENT_ID",
           result_filter={"assignedById.LAST_NAME": "Иванов"}
           ) }}

Сначала с сервера функция REV получает все элементы, где PARENT_ID = текущая сделка. Затем для каждого элемента проверяется, что assignedById.LAST_NAME == "Иванов" и возвращает итоговый результат.

Принципиальное требование фильтра result_filter, поле по которому выполняется отбор и фильтрация, должно быть получено с сервера и загружено в объект obj. Если поле, по которому вы делаете выборку не загружено в объект obj используйте фильтр raw_filter.

Функция REV1¶

Специальная функция генератора документов, которая позволяет выполнять запрос к структуре данных Битрикс24 и возвращать единственную запись, удовлетворяющих отправленному запросу или пустую запись, если условия не выполнены.

Работает также как и функция REV, только вместо списка возвращает первую запись результата.

SYNTAX

obj.rev(entity: str,     #тип сущности в которой будет выполняться поиск
        field_name: str, #поле по которому будет выполняться поиск значений
        raw_filter: dict | None = None, # словарь {ключ: значение} для дополнительно фильтрации значений поиска
        result_filter: dict | None = None, # словарь {ключ: значение} для дополнительно фильтрации результата вывода
       )

Синтаксис команд генератора

Основы формирования шаблонов документов¶

Популярные редакторы, поддерживающие формат DOCX¶

Порядок создания шаблона документов¶

Основной синтаксис генератора документов¶

Внутренний объект данных генератора документов¶

Переменные данные в шаблонах документов¶

Вставка значений пользовательских полей¶

Вставка вложенных структур Битрикс24¶

Доступ к данным Смарт-процесса¶

Управляющие команды¶

Команда условие IF¶

Команда цикла FOR¶

Блоки комментариев в шаблонах¶

Контроль над пробелами¶

Специальные фильтры¶

Специальные Тесты¶

Назначение переменных¶

Глобальные функции¶

Функция RANGE¶

Функция DICT¶

Функция CYCLER¶

Пространство имен NAMESPACE¶

Расширенный режим настроек шаблонов¶

Специальные теги управления шаблонами¶

Специальный тег {%p новый абзац¶

Специальный тег {%tr строка таблицы¶

Специальный тег {%tc колонка таблицы¶

Макросы (MACRO) в генераторе шаблонов¶

Функция REV¶

Фильтр raw_filter в функции REV¶

Фильтр result_filter в функции REV¶

Функция REV1¶

Команда условие `IF`¶

Команда цикла `FOR`¶

Специальный тег `{%p` новый абзац¶

Специальный тег `{%tr` строка таблицы¶

Специальный тег `{%tc` колонка таблицы¶