Modifiers in templates

Description

Modifier mechanism was developed for providing a flexible and universal method of managing display of various data.

Modifier is written inside curly braces of placeholder after twiddle character. For example, {CreateDate~d.m.Y h:s}.

Presently, there is a limited set of available fields which appearance can be managed using modifiers. Each type of field has its own modifiers.

When modifier is specified for an incorrect field type, it will be ignored. Theoretically, almost everything can be indicated after the character ~ inside brackets (matching to a regular expression #\{(([a-zA-Z0-9._]*?)\~?([^\~\r\t\n]*))\}#U). However, its better to write appropriate modifiers for correct fields.

Access to fields inside an array (from version documentgenerator 18.6.1)

Some fields are passed to the document as arrays (for example, products, taxes, deal contacts). Previously, the access to values of such fields can be retrieved only inside a table or repeated blocks. Now, a field can be inserted from array to any template location. First array element is sourced by default. But another number can be sourced via the identifier index; the value 0 corresponds to first element.

{ProductsProductName~index=1} - inserts second product name from list. When you need only one product, inserts nothing.

Multiple values (from documentgenerator 18.6.1)

Some field values can be multiple, each value can have its own type. In this case, all values are displayed comma-separated by default. There are two modifiers for multiple value fields:

• mfirst=Y/N - show only the first value.
• mseparator=1/2 - comma-separated (1) or line break (2).

Displaying all field values of array elements (from documentgenerator 18.6.1)

Now all values of single field can be displayed from all array elements in arbitrary template location. For example, names of all products must be displayed. Insert the field {ProductsProductName~all=y}. In this case, multiple value is generated from all product names and inserted into document. You can manage value display via the modifier mseparator=1/2 - just as in the previous item. For example, {ProductsProductName~mseparator=2,all=y} retrieves all product names via line break. important! Modifier mseparator must be located to the left from the modifier all. It's required because field value can be other multiple value which needs another modifier to be applied.

Date/Time and Phone number

Date and time

When the passed field contains date/time, you can directly specify format in the modifier. Format is specified also in date() php function. By default, date and time are printed in the format of a country for current template (date only, without time). However, modifier can be used to specify an arbitrary format. For example, {CreateTime~d.m.Y h:s} prints date with time.

Type date/time has all standard fields that return the object DateTime, as well as user fields with Date/Time field.

Phone number

Available values of modifiers can be sourced from \Bitrix\Main\PhoneNumber\Format

• E.164: +98 00919 0000 9231
• International: +7 99432 219-2221-34
• National: 8 (9384113) 219-12-34

Field type code - 'PHONE' Example of modifier

{ClientPhone~format=E.164}

Name

Format and case can be specified directly (with some limitations) for fields that are names. Full modifier looks as follows:

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

Portion of Format is responsible for displayed name format. The following fields are available:

• #TITLE# - reference; for CRM contacts matches to the field "Title"
• #NAME# - first name
• #LAST_NAME# - last name
• #SECOND_NAME# - middle name
• #NAME_SHORT# - shortcut name (first letter plus period)
• #LAST_NAME_SHORT# - shortcut last name (first letter plus period)
• #SECOND_NAME_SHORT# - shortcut middle name (first letter plus period)

Second portion of Case is responsible for desired case in name.

Case is applicable only when:

1. Language has a case grammatical category (For example, Russian language)
2. Middle name is available

Using Russian language of such example, the following must be taken into account: because CRM contacts do not have "Gender" field, gender identification is performed using middle name. When this field is empty, name case will not be replaced.

The following codes are passed for cases:

• -1 - subjective
• 0 - genitive
• 1 - dative
• 2 - accusative
• 3 - instrumental
• 4 - prepositional

All name fields for contacts/responsible users are passed as "Name" type fields to which a modifier can be applied.

Address and Currency

Address

This field is passed only within CRM, that's why it cannot be used in other modules. Fully modifier looks as follows:

{MyCompanyAddress~Format=3,Separator=3}

Format part is responsible for format type. The following options are available:

• 1 - Europe
• 2 - Great Britain
• 3 - North America
• 4 - Russia (street -> country)
• 5 - Russia (country -> street)

Separator part is responsible for string separator. The following options are available:

• 1 - comma (,)
• 3 - line break

The format default depends on a specific country, templates with comma separator.

Money

This field is passed only within CRM, and it cannot be used in other modules. Fully modifier looks as follows:

{TotalSum~WZ=Y,NS=N} or {TotalSum~W=Y,NS=N}

• WZ - acronym for With Zeros. When WZ=Y, the total sum will always show insignificant zeros, independently from selected currency format.
• NS - acronym for No Sign. When NS=Y, the total sum will be displayed without currency symbol. When NS=N, the situation is reversed: the currency symbol is displayed.
• W - acronym for Words. When W=Y and currency is listed (US dollar, British pound and etc.), the sum will be spelled in cursive.

The same field type is used for numerical values (fields of product numbers, number of strings), but has NS=Y by default. Also, note that all monetary values return this type, including "Money" type user fields.

Letter case

Available from documentgenerator version 22.200.0

One of most frequently asked questions: modifier for updating letter case.

For example, {DocumentCreateTime~format=d F Y} prints month name with capital letter. And often it's not necessary.

Now, any (absolutely any) field can have an added modifier letterCase that converts the letter case.

Modifier can receive the following values:

• upper - upper case
• lower - lower case
• title - upper case the first letter of each word.

Now, {DocumentCreateTime~format=d F Y,letterCase=lower} prints "25 april 2022" instead of "22 April 2022".