Модификаторы в шаблонах документов

Шаблоны документов содержат параметры, вместо которых Битрикс24 подставит реальные данные. Например, {DocumentCreateTime} станет датой создания документа.

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

В этом случае настройте формат с помощью специальных модификаторов.

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

Модификаторы расположены внутри параметра шаблона после знака тильды (~). Например, {DocumentCreateTime~d.m.Y h:s}.

Как работать с параметрами и редактировать шаблоны документов читайте в статье Шаблоны документов

Модификаторы доступны для дат, имён, адресов и денежных сумм.

Дата и время

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

{DocumentCreateTime~Y-m-d H:i:s} Возможные форматы дат и времени

d.m.y — 28.08.18
d.m.Y — 28.08.2018
j, n, Y — 10, 3, 2018
H:i:s — 10:24:18
Y-m-d H:i:s — 2018-08-28 10:24:18
j 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

получить консультацию

Мoдификaторы в шaблонах документов