Модификаторы в шаблонах документов
Шаблоны документов содержат параметры, вместо которых Битрикс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}Нумерация элементов списка начинается с нуля. Например, товар с индексом 1 — это второй товар.
Множественные поля
В CRM поля могут быть множественными — то есть иметь несколько значений. Например, стандартные поля Телефон, Почта, Мессенджер или любое пользовательское поле со свойством Множественное.
Шаблоны документов не поддерживают множественные поля с типом Файл и Привязка к элементам 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″.
Источник материала: Битрикс24
