Документация для разработчиков

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

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

Модификатор пишется внутрь фигурных скобок плейсхолдера после символа тильды. Например, {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. Это необходимо, т.к. значением поля может быть другое множественное значение, к которому нужно применить другой модификатор.


Дата и время

Если отдаваемое поле является датой/временем, то в модификаторе можно указать в явном виде формат. Формат задается также, как в 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 Также все денежные значения возвращают этот тип, в том числе пользовательские поля типа "Деньги".



Пользовательские комментарии

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

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2019, «1С-Битрикс», 2019
Наверх