Шаблоны документов содержат параметры, вместо которых Битрикс24 подставит реальные данные. Например, {DocumentCreateTime} станет датой создания документа.
Однако мы не можем управлять внешним видом этих данных. К примеру, некоторые документы требуют конкретный формат даты или сумму прописью.
В этом случае настройте формат с помощью специальных модификаторов.
Как это работает?
Модификаторы расположены внутри параметра шаблона после знака тильды (~). Например, {DocumentCreateTime~d.m.Y h:s}.
Модификаторы доступны для дат, имён, адресов и денежных сумм.
Дата и время
По умолчанию, дата имеет формат страны текущего шаблона. Зададим произвольный формат с помощью модификаторов.
{DocumentCreateTime~Y-m-d H:i:s}
d.m.y- 28.08.18d.m.Y- 28.08.2018j, n, Y- 10, 3, 2018H:i:s- 10:24:18Y-m-d H:i:s- 2018-08-28 10:24:18j F, Y- 28 Августа, 2018
О всех доступных форматах дат и времени можете почитать в документации.
Создадим документ по шаблону.
Имя
Для имён мы прежде всего можем задать формат - порядок следования фамилии, имени и других элементов.
К примеру, {FormattedName~Format=#TITLE# #LAST_NAME# #NAME# #SECOND_NAME#} выведет обращение, а затем фамилию, имя и отчество.
Для контакта в сделке вы можете использовать параметр {ContactFormattedName}, а для имени ответственного - {AssignedFormattedName}
#TITLE#- обращение;#NAME#- имя;#LAST_NAME#- фамилия;#SECOND_NAME#- отчество;#NAME_SHORT#- первая буква имени с точкой;#LAST_NAME_SHORT#- первая буква фамилии с точкой;#SECOND_NAME_SHORT#- первая буква отчества с точкой.
Также мы можем изменить падеж имени. Например, {FormattedName~Case=0} выведет имя в родительном падеже.
- -1 - именительный;
- 0 - родительный;
- 1 - дательный;
- 2 - винительный;
- 3 - творительный;
- 4 - предложный.
Для примера, зададим формат полного имени контакта в родительном падеже.
{FormattedName~Format=#TITLE# #LAST_NAME# #NAME# #SECOND_NAME#,Case=0}
Создадим документ по шаблону.
Ещё один частый пример - вывести в сделке имя бухгалтера или директора компании из реквизитов в родительном падеже. В этом случае для директора используйте:
{CompanyRequisiteRqDirector~Case=0}
А для бухгалтера:
{CompanyRequisiteRqAccountant~Case=0}
Адрес
По умолчанию, Битрикс24 использует формат адреса страны текущего шаблона.
Мы можем изменить тип формата даты и разделитель строк. Зададим тип адреса Северной Америки с переводом строки между частями адреса.
{Address~Format=3,Separator=3}
Часть модификатора Format отвечает за тип формата:
- 1 - Европа;
- 2 - Великобритания;
- 3 - Северная Америка;
- 4 - Россия (улица -> страна);
- 5 - Россия (страна -> улица).
Часть Separator отвечает за разделитель строк:
- 1 - запятая;
- 2 - без разделителя;
- 3 - перевод строки.
Создадим документ по шаблону.
Деньги
Для денежных значений мы можем показать незначащие нули и валюту. Также с помощью специального модификатора сумму можно вывести прописью.
- WZ (With zeros) - По умолчанию, Битрикс24 показывает незначащие нули для денежных сумм в полях. При значении WZ=N сумма будет без незначащих нулей. Например, 12.00 рублей превратятся в 12 рублей.
По умолчанию нули выводятся в полях {TotalRaw}, {TaxesTaxRate}, {TotalSum}.
В полях, которые находятся в табличной части, например {ProductsProductPriceRawNetto}, {ProductsProductPriceRawSum} нули выводятся только при добавлении модификатора WZ=Y. - NS (No sign) - при значении NS=Y сумма будет без знака валюты, при значении NS=N - со знаком;
- W (Words) - при значении W=Y сумма будет написана прописью.
К примеру, выведем сумму сделки прописью и со знаком валюты.
{TotalSum~W=Y,NS=N}
Создадим документ по шаблону.
Телефон
Изменить формат номера телефона можно с помощью модификатора format. Например:
{ClientPhone~format=E.164}
Доступные форматы:
- E.164 - +79062191234
- International - +7 906 219-12-34
- National - 8 (906) 219-12-34
Выбор товара, налога или контакта из списка
Некоторые данные передаются в документы в виде списка - например, товары, налоги или контакты сделки.
Вы можете получить и один элемент из списка - для этого просто укажите название поля. По умолчанию, в документ будет вставлен первый элемент.
{ProductsProductName}
Используйте модификатор index, чтобы получить любой другой элемент. Например, этот код выведет третий элемент из списка товаров.
{ProductsProductName~index=2}
Множественные поля
В CRM поля могут быть множественными - то есть иметь несколько значений. Например, стандартные поля Телефон, Почта, Мессенджер или любое пользовательское поле со свойством Множественное.
С помощью модификатора mfirst вы можете управлять выводом множественных полей:
- mfirst=y - выводить только первое значение
- mfirst=n - выводить все значения
Например:
{TestField~mfirst=n}
По умолчанию, значения будут разделены запятой. Модификатор mseparator позволяет выбрать разделитель - запятая (1) или перенос строки (2):
{TestField~mseparator=2}
Перечисление всех товаров, налогов или контактов из списка
Вы можете вывести в шаблоне документа, к примеру, все названия товаров через запятую. Для этого добавьте к нужному полю модификатор all:
{ProductsProductName~all=y}
Этот модификатор аналогично работает и с любым другим списком - например, списком налогов или контактов в сделке.
Вместо запятой можно использовать перенос строки - для этого добавьте модификатор mseparator=2:
{ProductsProductName~mseparator=2,all=y}
Рассмотрим пример - у нас есть сделка, в которой участвует 10 контактов. У каждого контакта есть 10 номеров в поле Телефон.
Мы хотим вывести номера каждого из контактов с новой строчки - для этого нужен следующий код:
{ContactsContactPhone~mseparator=2,all=y,mfirst=n}
Регистр текста (с версии documentgenerator 22.200.0)
Один из частых запросов — модификатор для изменения регистра текста.
Например, {DocumentCreateTime~format=d F Y} выводит название месяца с большой буквы. А это часто не требуется.
Теперь к любому полю можно добавить модификатор letterCase, который преобразует регистр текста.
Модификатор может принимать следующие значения:
upper— верхний регистр,
lower— нижний регистр,
title— верхний регистр для первой буквы каждого слова.
Теперь {DocumentCreateTime~format=d F Y,letterCase=lower} выведет "25 апреля 2022" вместо "25 Апреля 2022".
