Документация для разработчиков
Документация для разработчиков Документация по D7 Документация по REST Пользовательская документация
Темная тема

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

Описание

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

Модификатор пишется внутрь фигурных скобок плейсхолдера после символа тильды. Например, {CreateDate~d.m.Y h:s}.

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

Если написать модификатор для не того типа поля, то он будет проигнорирован. Теоретически, после символа ~ внутри скобок можно написать почти что угодно (удовлетворяющее регулярному выражению #\{(([a-zA-Z0-9._]*?)\~?([^\~\r\t\n]*))\}#U), но лучше писать правильные модификаторы для правильных полей.

Доступ к полям внутри массива (с версии documentgenerator 18.6.1)

Некоторые поля передаются в документ в виде массивов (например, товары, налоги, контакты сделки). Раньше доступ к значениям таких полей можно было получить только внутри таблицы или повторяющихся блоков. Теперь можно вставить поле из массива в любое место шаблона. По умолчанию будет взят первый элемент массива. Но можно взять другой номер с помощью модификатора index, значение 0 соответствует первому элементу.

{ProductsProductName~index=1} - вставит название второго товара из списка. Если там только один товар, то ничего не вставится.


Множественные значения (с версии documentgenerator 18.6.1)

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

  • mfirst=Y/N - показывать только первое значение.
  • mseparator=1/2 - разделитель запятая (1) или перенос строки (2).

Вывод всех значений полей элементов массива (с версии documentgenerator 18.6.1)

Теперь можно вывести все значения одного поля из всех элементов массива в произвольном месте шаблона. Например, надо вывести названия всех товаров. Вставляем поле {ProductsProductName~all=y}. В этом случае из всех названий товаров будет сформировано множественное значение и вставлено в документ. Можно управлять выводом значений с помощью модификатора mseparator=1/2 - как в предыдущем пункте. Например, {ProductsProductName~mseparator=2,all=y} выведет названия всех товаров через перенос строки. Важное замечание ! Модификатор mseparator должен стоять слева от модификатора all. Это необходимо, т.к. значением поля может быть другое множественное значение, к которому нужно применить другой модификатор.

Модификатор index в маркере начала повторяющегося блока (с версии documentgenerator 20.0.0)

С версии 20.0.0 модификатор можно задать так:

{PRODUCTS.BLOCK_START~index=1}
Название товара с индексом один: {ProductsProductName}
{PRODUCTS.BLOCK_END}

В этом случае область будет напечатана только один раз для элемента списка с указанным индексом.

Если в списке нет элемента с этим индексом, то область всё равно будет вставлена в документ один раз, но с пустыми данными.

Использование маркеров повторяющихся блоков внутри ячеек таблиц (с версии documentgenerator 20.0.0)

C версии 20.0.0 можно вставлять повторяющиеся блоки прямо внутрь ячеек таблицы.

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

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

Дата/Время и Номер телефона


Дата и время

Если отдаваемое поле является датой/временем, то в модификаторе можно указать в явном виде формат. Формат задается также, как в php-функции date(). По умолчанию вся дата и время выводится в формате страны текущего шаблона (только дата, без времени), но с помощью модификатора можно задать произвольный формат. Например, {CreateTime~d.m.Y h:s} выведет дату вместе со временем.

Тип дата/время имеют все стандартные поля, возвращающие объект DateTime, а также пользовательские поля с типом Дата/Время.


Номер телефона

Допустимые значения модификаторов можно взять из \Bitrix\Main\PhoneNumber\Format

  • E.164: +79062191234
  • International: +7 906 219-12-34
  • National: 8 (906) 219-12-34

Код типа поля - 'PHONE' Пример модификатора

{ClientPhone~format=E.164}

Имя

Для полей, которые являются именами, можно в явном виде задать формат и падеж (с некоторыми ограничениями). Полностью модификатор выглядит так:

{ContactFormattedName~Format=#TITLE# #LAST_NAME#,Case=1}

Часть Format отвечает за формат выводимого имени. Допустимы следующие поля:

  • #TITLE# - обращение, для Контактов в CRM соответствует полю "Обращение"
  • #NAME# - имя
  • #LAST_NAME# - фамилия
  • #SECOND_NAME# - отчество
  • #NAME_SHORT# - имя сокращенно (первая буква плюс точка)
  • #LAST_NAME_SHORT# - фамилия сокращенно (первая буква плюс точка)
  • #SECOND_NAME_SHORT# - отчество сокращенно (первая буква плюс точка)

Вторая часть Case отвечает за желаемый падеж в имени.

Склонение работает только если:

  1. Имя на русском языке
  2. Заполнено отчество

Т.к. в CRM для контактов нет поля "Пол", то определение пола осуществляется по отчеству. Если оно не заполнено - падеж имени не будет изменен.

Для падежей передаются следующие коды:

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

Все именные поля контактов/ответственных отдаются как тип поля "Имя", к которому можно применить модификатор.

Адрес и Деньги

Адрес

Это поле отдается только в рамках CRM, поэтому в других модулях его нельзя будет использовать. Полностью модификатор выглядит так:

{MyCompanyAddress~Format=3,Separator=3}

Часть Format отвчает за тип формата. Возможны следующие варианты:

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

Часть Separator отвечает за разделитель строк. Возможны следующие варианты:

  • 1 - запятая (,)
  • 3 - перевод строки

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

Деньги

Это поле отдается только в рамках CRM, поэтому в других модулях его нельзя будет использовать. Полностью модификатор выглядит так:

{TotalSum~WZ=Y,NS=N} либо {TotalSum~W=Y,NS=N}

  • WZ - сокращение от With Zeros. Если WZ=Y, то в сумме всегда будут показаны незначащие нули, независимо от выбранного формата валюты.
  • NS - сокращение от No Sign. Если NS=Y, то сумма будет отображаться без символа валюты, если NS=N, то наоборот символ валюты будет показан.
  • W - сокращение от Words. Если W=Y и валюта одна из списка (рубль, белорусский рубль, гривна, тенге), то сумма будет написана прописью.

Этот же тип поля используется для численных значений (поля количества товаров, количества строк), но там по умолчанию NS=Y Также все денежные значения возвращают этот тип, в том числе пользовательские поля типа "Деньги".

Регистр текста

С версии documentgenerator 22.200.0

Один из частых запросов - модификатор для изменения регистра текста.

Например, {DocumentCreateTime~format=d F Y} выводит название месяца с большой буквы. А это часто не требуется.

Теперь к любому (абсолютно любому) полю можно добавить модификатор letterCase, который преобразует регистр текста.

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

  • upper - верхний регистр
  • lower - нижний регистр
  • title - верхний регистр для первой буквы каждого слова.

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



© «Битрикс», 2001-2024, «1С-Битрикс», 2024