Модификатор — это специальный код, который меняет формат поля. Например, значение поля Ф.И.О. по умолчанию выводится в именительном падеже — Сергей Терехов. Чтобы CRM вывела поле в дательном падеже — Сергею Терехову, к символьному коду надо добавить специальный модификатор.

Модификаторы расположены внутри символьного кода после знака тильды (~). В коде {DocumentCreateTime~d.m.Y h:i:s} DocumentCreateTime — это код поля, а d.m.Y h:i:s — модификатор.

Чтобы научиться работать с модификаторами, сначала прочитайте статью про символьные коды, так как без кодов модификаторы не будут работать.
Символьные коды: что это и зачем они нужны

Модификаторы работают только с полями, у которых указан тип.

Типы модификаторов

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

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

Модификаторы даты:

• d.m.y — 28.08.23
• d.m.Y — 28.08.2023
• j, n, Y — 28, 08, 2023
• j F, Y — 28 Августа, 2023

Модификаторы времени:

• H:i:s — 10:24:18

Модификаторы даты и времени можно комбинировать:

• Y-m-d H:i:s — 2023-08-28 10:24:18

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

Возьмем код для поля «Дата создания документа» и преобразуем его в нужный формат. Для этого к коду {DocumentCreateTime} добавим модификатор ~d.m.Y h:i:s. Получим такой код {DocumentCreateTime~d.m.Y h:i:s}.

Модификаторы имени. С помощью модификаторов можно задать падеж, порядок следования фамилии, имени, отчества и обращения. Для изменения порядка следования используйте параметр ~format=. Модификаторы имени работают только с системными полями.
Системные поля в CRM

Список возможных модификаторов:

• #TITLE# — обращение
• #NAME# — имя
• #LAST_NAME# — фамилия
• #SECOND_NAME# — отчество
• #NAME_SHORT# — первая буква имени с точкой
• #LAST_NAME_SHORT# — первая буква фамилии с точкой
• #SECOND_NAME_SHORT# — первая буква отчества с точкой

Выведем имя в такой последовательности: фамилия, имя, отчество. Возьмем символьный код, который обозначает полное имя контакта {ContactFormattedName} и добавим к нему модификаторы в том порядке, который описан выше. Код будет иметь такой вид: {ContactFormattedName~Format=#LAST_NAME# #NAME# #SECOND_NAME#}.

Для изменения падежа используем параметр ~Case=. Склонение по падежам работает только для имён на русском языке, в которых указано отчество.

Модификаторы падежа:

• -1 — именительный
• 0 — родительный
• 1 — дательный
• 2 — винительный
• 3 — творительный
• 4 — предложный

Создадим код для имени в родительном падеже. Возьмем код с модификаторами последовательности, который мы создали раньше, и добавим модификатор родительного падежа {ContactFormattedName~Format=#LAST_NAME# #NAME# #SECOND_NAME#, Case=0}.

Если надо вывести имя главного бухгалтера или директора компании в родительном падеже, используем {CompanyRequisiteRqDirector~Case=0} для директора, {CompanyRequisiteRqAccountant~Case=0} для бухгалтера.

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

Формат адреса можно изменить, а также добавить разделитель строк. Для изменения формата будем использовать параметр ~Format=, а для разделения строк ~Separator=.

Модификаторы формата и разделителя:

Для параметра Format:

• 1 — Европа
• 2 — Великобритания
• 3 — Северная Америка
• 4 — Россия (улица > страна)
• 5 — Россия (страна > улица)

Для параметра Separator:

• 1 — запятая
• 2 — без разделителя
• 3 — перевод строки

Зададим тип адреса — Россия (страна > улица) с переводом строки между частями адреса, к коду поля адрес контакта добавим нужные модификаторы и получим {ContactAddress~Format=5,Separator=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 сумма будет написана прописью.
• SN (Show No VAT). При значении SN=Y налоговая ставка будет выведена без указания НДС, то есть только числовое значение ставки. Например, {TaxesTaxRate~SN=Y} выведет 22 вместо 22% НДС.
• WP (With Percent). При значении WP=Y к налоговой ставке добавляется символ процента. Например, {TaxesTaxRate~WP=Y} выведет 22%. Если указать WP=N, символ процента не отобразится.

Покажем итоговую сумму, налог с учетом модификаторов процента и НДС {TaxesTaxRate~WP=Y, SN=Y}.

Модификаторы для телефона. Изменить формат номера телефона можно с помощью модификатора ~format=.

Доступные форматы:

• E.164 — +7900xxxxxxx
• International — +7 900 xxx-xx-xx
• National — 8 (900) xxx-xx-xx

Выведем номер контакта в привычном нам формате +7 и без пробелов, Используем код {ContactPhone~format=E.164}, где {ContactPhone} — это код для поля «Телефон контакта».

Модификаторы регистра текста. С помощью модификатора ~letterCase= можно изменить регистр текста.

Модификатор может принимать следующие значения:

• upper — ВЕРХНИЙ РЕГИСТР
• lower — нижний регистр
• title — Верхний Регистр Для Первой Буквы Каждого Слова

Теперь {DocumentCreateTime~format=d F Y, letterCase=lower} выведет «25 апреля 2022» вместо «25 Апреля 2022».

Как с помощью модификаторов вывести значения из множественного поля

В CRM есть поля, в которые можно добавить несколько значений. Например, в поле Телефон можно указать рабочий и личный номер. Такие поля называются множественными.

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

Модификатор ~mfirst= — выводит одно или все значения поля. Работает с системными полями CRM, например, Телефон, Почта, Мессенджер, и с пользовательскими множественными полями.
Системные поля в CRM

• mfirst=y — только первое значение. Используйте, если в документе нужен один основной номер. Например, {ContactPhone~mfirst=y} выведет первый телефон контакта.
• mfirst=n — все значения. Используйте, если нужно вывести все номера сразу. Например, у контакта два телефона — рабочий и мобильный. {ContactPhone~mfirst=n} выведет оба через запятую: +7 999 000-99-00, +7 921 444-55-66.

По умолчанию значения разделяются запятой. Если нужно, чтобы каждый номер был на отдельной строке — например, в акте или договоре, где список телефонов читается удобнее столбиком — добавьте ~mseparator=2. Тогда {ContactPhone~mfirst=n,mseparator=2} выведет:
+7 999 000-99-00
+7 921 444-55-66

Модификатор ~index= — выводит конкретный товар из списка товаров в сделке. Нумерация начинается с нуля: первый товар — ~index=0, второй — ~index=1 и так далее.

• index=0 — первый товар. Например, {ProductsProductName~index=0} выведет название первого товара в сделке.
• index=1 — второй товар. Например, {ProductsProductName~index=1} выведет название второго товара.
• index=2 — третий товар. Например, если в сделке три товара — ноутбук, мышь и сумка — то {ProductsProductName~index=2} выведет сумка.

Модификатор работает только со списком товаров и только если код поля размещен вне таблицы в шаблоне. С системными полями и пользовательскими полями он не работает — для них используйте ~mfirst=.

Модификатор ~all=y — выводит все элементы из поля Привязка к элементам CRM. Это системное поле, которое создается в настройках CRM. Оно позволяет привязать, например, к сделке другие элементы CRM — несколько компаний или предложений.

• all=y — все привязанные элементы. Например, если к сделке привязаны две компании и одно предложение, {КодПоля~all=y} выведет ID всех трех элементов через запятую.

С другими полями этот модификатор не работает.

Рекомендуем прочитать:

• Шаблоны документов в CRM: как настроить, чтобы быстро отправлять счета и акты
• Как изменить стандартный шаблон документа в СRM
• Как загрузить свой шаблон документа в CRM
• Пользовательские поля в шаблонах документов: как добавить свое поле в шаблон