# Синтаксис шаблонов > [HTML Version](360027003711.html) Первый этап настройки генерации документов по шаблону — это подготовка файла, который может иметь формат **.doc**, **.docx**, **.rtf**, **.dot**, **.dotx**, **.xls**, **.xlsx**, **.xltx**, **.xlt**. Файл составляется с помощью специального синтаксиса и может содержать переменные, функции, условия и циклы. Это позволяет подставлять данные из ELMA365, форматировать текст, числа и даты, склонять значения, а также формировать списки и таблицы. В статье описаны правила записи переменных и выражений в файле шаблона. После подготовки файла ознакомьтесь с дальнейшими шагами настройки. ```` начало примера ```` Полезные статьи: - [«Добавить и настроить шаблон документов»](360026936731.md) — как загрузить файл шаблона в систему и сопоставить переменные; - [«Генерация по шаблону»](360026720792.md) и [«Генерация по файлу»](generate-from-file.md) — как настроить автоматическую генерацию документа с помощью специальных блоков в ходе бизнес-процесса. ```` конец примера ## ```` Подобрать синтаксис под задачу | | | |------|------| | **Что нужно сделать** | **Какой раздел выбрать ** | | Подставить значение из поля | [Формат переменных](#fields_syntax) | | Вывести свойство файла, пользователя или связанного элемента | [Формат вложенных переменных](#inner_fields_syntax) | | Узнать правила записи аргументов | [Передача аргументов функций](#function-arguments) | | Изменить регистр или вывести часть текста | [Работа с текстом](#string-data-type) | | Вывести значение нужного типа | [Функция ToString()](#tostring_function) | | Настроить отображение числа | [Функция NumberFormat()](#numberformat) | | Настроить формат даты и времени | [Функции DateTime() и Now()](#set-datetime-now) | | Получить количество строк или элементов | [Функция Count()](#count) | | Просклонять Ф. И. О., слово или число | [Склонение значений](#cases) | | Вывести текст в зависимости от значения поля | [Условия](#if) | | Отобразить список или сформировать таблицу | [Цикл \{for\}](#cycle) | | Вставить штрихкод, изображение или ссылку, а также добавить пользовательскую функцию | [Специальные функции синтаксиса шаблонов](another-template-syntax-functions.md) | ## Общие правила синтаксиса ### Формат переменных Для подстановки переменной укажите её код в фигурных скобках со знаком доллара: `\{\$код\_переменной\}`. При создании переменной её уникальный код указывается в поле **Имя свойства\* **латинскими буквами. ```` начало примера ```` Пример `\{\$client\}` — подставит наименование контрагента из карточки элемента. ```` конец примера ### ```` Формат вложенных переменные В шаблоне можно обращаться к атрибутам полей из контекста приложения, то есть использовать вложенные переменные. Это доступно для полей типа [Файлы](360009707032.md#file_type), [Пользователи](360009707032.md#users), [Приложение](app-data-type.md), [Произвольное приложение](360009707032.md#arbitrary-app) и т. д. Чтобы вывести атрибут связанного объекта, укажите код основного поля и код вложенного свойства через точку: `\{\$код\_переменной.код\_вложенной\_переменной\}`. ```` начало примера ```` Пример В приложении **Заказы** есть поля **Договор** (код — `contract`) и **Клиент** (код — `client`), в которые добавляются ссылки на элементы приложений. В синтаксисе укажите: - `\{\$contract.\_\_name\}` — чтобы отобразить название файла, загруженного в поле **Договор**; - `\{\$client.phone\}` — чтобы вывести номер телефона контрагента, указанного в поле **Клиент**. ```` конец примера ### ```` Передача аргументов функции Параметры функции передаются внутри скобок через запятую: 1. Переменные и числа указываются без кавычек, например `\{\$sum\}`, `100`. 2. Строковые значения: форматы, локали, маски и текстовые данные выделяются кавычками, например `"ru-RU"`, `"short"`. Хотя простые значения распознаются в системе без кавычек, для единообразия рекомендуем применять это правило ко всем строковым аргументам. Такой подход исключает ошибки при обработке пробелов и спецсимволов. Допустимо использовать следующие виды кавычек: **" "**, **« »**, **“ “**, **” ”**, **' '**. 3. В схемах синтаксиса необязательные параметры оборачиваются в квадратные скобки `\[\]`. При составлении шаблона в функциях их прописывать не нужно. ### Формат передачи локали Для некоторых функций, например `ToString()`, `DateTime()`, `Now()`, в качестве аргумента можно указать локаль, чтобы вынести дату, число или сумму в формате конкретной страны. Доступные локали: - `"ru-RU"` — русский; - `"en-US"` — английский (США); - `"en-GB"` — английский (Великобритания); - `"de-DE"` — немецкий; - `"fr-FR"` — французский; - `"es-ES"` — испанский. Также можно использовать сокращённый вариант языкового кода, например `"ru"` или `"en"`. ```` начало примера ```` Пример Значение даты в переменной `\{\$\_\_createdAt\}` — **25.08.2000**: `\{DateTime("DD MMMM YYYY", \{\$\_\_createdAt\}, "ru-RU")\} `—> 25 августа 2000. ```` конец примера ## ```` Работа с текстом Функции для работы со строками позволяют менять регистр текста и выводить только часть значения. В примерах переменная `\{\$string\}` содержит значение **Иван Крапивин**. ### Перевести в верхний регистр функцией UpperCase() **Синтаксис:** `\{UpperCase(\{\$код\_переменной\}: строка)\}`. ```` начало примера ```` Пример `\{UpperCase(\{\$string\})\}` —> ИВАН КРАПИВИН. ```` конец примера ### ```` Перевести в нижний регистр функцией LowerCase() **Синтаксис:** `\{LowerCase(\{\$код\_переменной\}: строка)\}`. ```` начало примера ```` Пример `\{LowerCase(\{\$string\})\}` —> иван крапивин. ```` конец примера ### ```` Сделать первую букву заглавной функцией Capitalize() Функция переводит первую букву первого слова в верхний регистр. **Синтаксис:** `\{Capitalize(\{\$код\_переменной\}: строка)\}`. ```` начало примера ```` Пример `\{Capitalize(\{\$string\})\}` —> Иван крапивин. ```` конец примера ### ```` Вывести часть текста функцией Substr() Функция извлекает часть текста с указанной позиции и заданной длины. **Синтаксис:** `\{Substr(\{\$код\_переменной\}: строка, позиция: число, \[длина: число\])\}`, где: - **позиция** — номер символа, с которого начинается вывод строки; - **длина** — количество отображаемых символов. Если не указать этот аргумент, подставится весь остаток строки после заданной позиции. ```` начало примера ```` Примеры 1. `\{Substr(\{\$string\}, 0, 3)\}` —> Ива. 2. `\{Substr(\{\$string\}, 3)\}` —> н Крапивин. ```` конец примера ## ```` Вывести значение переменной функцией ToString() Функция `ToString()` позволяет отобразить в документе значения следующих типов данных: - [Строка](360027003711.md#string); - [Число](#number) - [Категория](360027003711.md#string); - [Выбор «да/нет»](360027003711.md#yes_no); - [Деньги](360027003711.md#money); - [Ф.И.О.](#name); - [Телефон](360027003711.md#phone); - [Дата/время](#date_time). Подробнее о типах данных читайте в статье [«Типы данных в системе»](360009707032.md). Набор параметров функции зависит от типа переменной. ### Строка Функция `ToString()` позволяет выводить значение текстовой переменной. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: строка)\}` Для типа **Строка** использовать функцию необязательно. Значение отобразится в шаблоне и при стандартной записи кода переменной в фигурных скобках. ```` начало примера ```` Примеры В переменной `\{\$string\}` содержится значение **Отправлено на согласование**. 1. `\{ToString(\{\$string\})\}` —> Отправлено на согласование. 2. `\{\$string\} `—> Отправлено на согласование. ```` конец примера ### ```` Число По умолчанию число выводится цифрами. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: число, \["формат": строка\], \["локаль": строка\])\}`, где: - **формат** — используйте значение формата `"astext"`, чтобы вывести целое число прописью; - **локаль** — язык для записи числа прописью, например `"ru"` или `"en"`. Доступные варианты смотрите в разделе [«Формат передачи локали»](#locale). ```` начало внимание ```` Чтобы вывести дробные числа прописью, вместо функции `ToString()` используйте `NumberToString()`. ```` конец внимание начало примера ```` Примеры В переменной `\{\$number\}` содержится целое число 546. 1. `\{ToString(\{\$number\})\}` —> 546. 2. `\{ToString(\{\$number\}, "astext")\}` —> пятьсот сорок шесть. 3. `\{ToString(\{\$number\}, "astext", "en-US")\}` —> five hundred forty six. ```` конец примера ```` Для более точной настройки отображения чисел используйте функцию [NumberFormat()](#numberformat). Она позволяет округлить дробную часть, перевести число в проценты или шестнадцатеричный формат и т. д. ### Категория Тип данных **Категория** позволяет выбрать одно значение из заданного списка, например для способа оплаты можно указать: картой, наличными. При настройке такого поля задаются название и код самой переменной, а также наименования и коды для каждого варианта выбора. **Синтаксис:** `ToString(\{\$код\_переменной\}: категория)`. Также вывести название выбранного варианта можно другими способами: - через код переменной — `\{\$variable\_code\}`; - с помощью обращения к наименованию варианта, указав его через точку — `\{\$код\_переменной.name\}`; Если вам нужно вывести не название, а код выбранного варианта, используйте запись `\{\$код\_переменной.code\}`. ```` начало примера ```` Пример В приложении создана переменная **Способ оплаты** (код `\{\$payment\}`). В ней выбран вариант **картой** (код `card`). 1. Оплата производится `\{ToString(\{\$payment\})\}` —> Оплата производится картой; 2. Оплата производится `\{\$payment\} `—> Оплата производится картой; 3. Оплата производится `\{\$payment.name\} `—> Оплата производится картой; 4. Код используемой категории: `\{\$payment.code\} `—> Код используемой категории: card. ```` конец примера ### ```` Выбор «да/нет» У этого типа данных два варианта: **Да** и **Нет**. Их можно переименовать, например в **Согласовано** и **Не согласовано**. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: выбор «да/нет»\})\}`. ```` начало примера ```` Пример В переменной **Резолюция** (код — `resolution`)` `вариант **Да** (код — `true`) определён как **Согласовано** и выбран как значение поля: Резолюция документа: `\{ToString(\{\$resolution\})\}` —> Резолюция документа: Согласовано. ```` конец примера ### ```` Деньги Значение переменной типа **Деньги** можно отобразить в нескольких форматах. **Cинтаксис:** `\{ToString(\{\$код\_переменной\}: деньги, \["формат": строка\], \["локаль": строка\])\},` где: - формат — доступные значение для формата: - `"short"` — короткий числовой. Формат знаков и разделителей соответствует выбранной локали —> 1 005, 56; - `"sign" `**— **сумма с кодом валюты, заданной в переменной** **—> 1 005, 56 RUB; - `"full"`** — **полный с наименованием валюты** **—> 1 005 рублей 56 копеек; - `"astext"`** **— сумма прописью —> Одна тысяча пять рублей 56 копеек; - `"wildcard"`** **— пользовательский формат. Вместо служебного слова задаётся шаблон в кавычках с символами: `"%i"` — для целой части, `"%f"` — для дробной части. Примеры пользовательского формата 1. `\{ToString(\{\$money\}, "%i руб. %f коп.")\}` —> 1005 руб. 56 коп. 2. `\{ToString(\{\$money\}, "%i (%f)")\}` —> 1005 (56); 3. `\{ToString(\{\$money\}, "%i ₽ %f к.")\}` —> 1005 ₽ 56 к. - **локаль** — для вывода значения на определённом языке, например `"ru"` или `"en"`. Доступные варианты смотрите в разделе [«Формат передачи локали»](#locale). ```` начало примера ```` Пример `\{ToString(\{\$money\}, "full", "ru")\}` —> 1 005 рублей 56 копеек. ```` конец примера ### ```` Ф. И. О. С помощью `ToString()` можно вывести фамилию, имя и отчество в нужном формате и падеже. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: Ф.И.О., \["формат": строка\], \["падеж": строка\])\}`, где: - **формат** — доступные значения: - `"long"` — фамилия, имя и отчество указываются полностью; - `"short"` — указываются фамилия и инициалы. - **падеж** — при указании падежа не учитывается регистр. Допустимо использовать один из трёх вариантов: - `"Nominative"` | `"Именительный"` | `"И"` — именительный; - `"Genitive"` | `"Родительный"` | `"Р"` — родительный; - `"Dative"` | `"Дательный"` | `"Д"` — дательный; - `"Accusative"` | `"Винительный"` | `"В"` — винительный; - `"Instrumental"` | `"Творительный"` | `"Т"` — творительный; - `"Prepositional"` | `"Предложный"` | `"П"` — предложный. При использовании предложного падежа функция `ToString()` не добавляет автоматически значения «о» или «об». Функция точнее склоняет имя, если в исходном значении указано отчество. ```` начало примера ```` Примеры 1. `\{ToString(\{\$fio\})\}` —> Сергеев Сергей Николаевич. 2. `\{ToString(\{\$fio\}, "short")\}` —> Сергеев С. Н. 3. `\{ToString(\{\$fio\}, "short", "Р")\} `—> Сергеева С. Н. 4. `\{ToString(\{\$fio\}, "long", "П")\}` —> Сергееве Сергее Николаевиче. ```` конец примера ```` Если вам требуется более гибкая настройка вывода Ф. И. О., используйте специальные функции: - [FormatFio()](#format_fio) — позволяет настроить порядок отображения частей имени и автоматически добавлять предлог в предложном падеже; - [GetPartOfFullName()](#part_of_fio) — извлекает только имя, фамилию или отчество; - [AnotherGenderSecondName()](#another_gender_fio) — формирует вариант фамилии противоположного рода. ### Телефон Функция позволяет задать маску для вывода номера телефона. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: номер телефона, "маска: +7-XXX-XXX-XX-XX EEE")\}`, где латинские буквы означают: - **X** — основной номер; - **E** — добавочный номер. Если в номере меньше цифр, чем указано символов `X` или `E`, лишние символы не отображаются в готовом документе. Цифры номера подставляются слева направо. ```` начало примера ```` Примеры 1. `\{ToString(\{\$phone\}, "+7-XXX-XXX-XX-XX")\}` —> +7-912-345-67-89. 2. `\{ToString(\{\$phone\}, "X-XXX-XXX-XX-XX EEE")\}` —> 8-912-345-67-89 159. 3. `\{ToString(\{\$phone\}, "XX-XX-XX E")\}` —> 45-67-89 3. ```` конец примера ### ```` Дата/время С помощью `ToString()` можно вывести значение типа **Дата/время**, например дату поставки оборудования по договору. У типа данных **Дата/время** есть подтипы: **Дата/время**, **Дата**,** Время**. Результат в функции будет зависеть от выбранного в переменной подтипа. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: дата/время, \["формат": строка\], \["локаль": строка\])\}`, где: - **формат** — определяет детальность и вид отображения элементов даты и времени в зависимости от подтипа: - без указания формата — выводит дату числовым значением в виде маски: DD.MM.YYYY, а время — с точностью до секунд в следующем виде: hh:mm:ss; - `"short"` — сокращённый формат. Выводит дату числами и скрывает секунды для времени; - `"long"` — полный формат. Для даты подставляет наименование месяца словом, а время выводит с секундами. - **локаль** — дата отобразится согласно принятым в указанной стране стандартам, например `"ru"` или `"en"`. Все доступные варианты смотрите в разделе [«Формат передачи локали»](#locale). **Важно:** подтип **Дата/время** выводит дату и время с учётом временной зоны компании. С подтипами **Дата** и **Время** значения отобразятся в том виде, в котором они сохранены в системе, без учёта временной зоны. ```` начало примера ```` Примеры В переменной `\{\$date\}` сохранено значение **09.04.2025 15:18:43**. 1. Без указания формата — `\{ToString(\{\$date\})\}`: - подтип **Дата/время** —> 09.04.2025 15:18:43; - подтип **Дата** —> 09.04.2025; - подтип **Время** —> 15:18:43. 2. Сокращённый формат, без секунд — `\{ToString(\{\$date\}, "short")\}`: - подтип **Дата/время** —> 09.04.2025 15:18; - подтип **Дата** —> 09.04.2025; - подтип **Время** —> 15:18. 3. Полный формат, с месяцем прописью — `\{ToString(\{\$date\}, "long")\}`: - подтип **Дата/время **—> 09.04.2025 15:18:43; - подтип **Дата** —> 9 апреля 2025 г.; - подтип **Время** —> 15:18:43. 4. С указанием локали — `\{ToString(\{\$date\}, "short", "en-US")\}`: - подтип **Дата/время **—> 4/9/25 3:18 pm; - подтип **Дата** —> 4/9/25; - подтип **Время** —> 3:18 pm. ```` конец примера ```` Для более гибкой настройки даты и времени используйте функцию [DateTime()](#datetime-function). Она позволяет задать пользовательскую маску отображения, например, переставить части местами, показать день недели и т. д. ## Отобразить число функцией NumberFormat() Функция `NumberFormat()` позволяет вывести значение переменной типа **Число** в заданном формате, например с фиксированным количеством знаков после запятой или в шестнадцатеричной системе счисления. **Синтаксис:** `\{ToString(\{\$код\_переменной\}: число, \["формат": строка\])\}`. Формат в функции `NumberFormat()` — это буквенный параметр, указывающий правило отображения числа. Рядом с ним можно подставить спецификатор точности — число сразу после буквы. В зависимости от выбранного формата оно определяет количество знаков в дробной части или минимальную длину записи. В примерах переменная `\{\$number\}` содержит дробное число **1125,34**. ### Десятичный формат Аргумент `"D"` или `"d"` выводит целое число без десятичной части и дополняет его нулями до заданной длины. Спецификатор точности задаёт количество заполняющих нулей. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "D5")\}` —> 01125. ```` конец примера ### ```` Экспоненциальный формат Аргумент `"E"` или `"e"` выводит число в виде мантиссы и порядка. Спецификатор точности задаёт количество знаков в дробной части. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "E2")\}` —> 1.13E+03. ```` конец примера ### ```` Формат с фиксированным количеством знаков Аргумент `"F"` или `"f"` выводит фиксированное количество знаков в дробной части. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "F2")\}` —> 1125.34. В примере задано два знака в дробной части. ```` конец примера ### ```` Общий формат Аргумент `"G"` или `"g"` преобразует число в фиксированный или экспоненциальный формат в зависимости от того, какой вариант получается компактнее. Спецификатор точности задаёт количество цифр без заполняющих нулей. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "G4")\}` —> 1125. ```` конец примера ### ```` Числовой формат с разделителями Аргумент `"N"` или `"n"` выводит число с разделителями разрядов. Спецификатор точности здесь задаёт количество знаков в дробной части. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "N3")\}` —> 1,125.340. ```` конец примера ### ```` Процентный формат Аргумент `"P"` или `"p"` умножает число на 100 и добавляет знак процента **%**. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "P")\}` —> 112534.00 %. ```` конец примера ### ```` Формат точного представления Аргумент `"R"` или `"r"` выводит точное представление числа без округления. Спецификатор точности не поддерживается. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "R")\}` —> 1125.34. ```` конец примера ### ```` Шестнадцатеричный формат Аргумент `"X"` или `"x"` выводит число в шестнадцатеричной системе счисления без дробной части. ```` начало примера ```` Пример `\{NumberFormat(\{\$number\}, "X")\}` —> 465. ```` конец примера ## ```` Настроить формат даты и времени ### Функция DateTime() Функция `DateTime()` позволяет вывести дату и время с заданным форматом и локалью, например дату создания элемента. **Синтаксис:** `\{DateTime("формат": строка, \{\$код\_переменной\}: дата/время, \["локаль": строка\])\}`, где: - **формат** — маска отображения даты и времени вида `"DD MM YYYY hh:mm:ss"`. Заключается в кавычки и задаёт шаблон итогового значения. Внутри маски допустимо обрамлять кавычками отдельные части даты и времени или разделять их дефисами. Доступные форматы маски для вывода даты и времени Для примера значение даты — 02.01.2025 15:04:05 (четверг): - Месяц: - `"M"` — 1; - `"MM"` — 01; - `"MMM"` — ЯНВ; - `"MMMM"` — Январь; - День: - `"D"` — 2; - `"DD"` — 02; - `"DDD"` — ЧТ; - `"DDDD"` — Четверг; - Год: - `"YY"` — 25; - `"YYYY"` — 2025; - Часы: `"hh"` — 15; - Минуты: `"mm"` — 04; - Секунды: `"ss"` — 05. - **локаль** — дата отобразится согласно принятым в указанной стране стандартам, например `"ru"` или `"en"`. Все доступные варианты смотрите в разделе [«Формат передачи локали»](#locale). ```` Начало примера ```` Примеры Переменная `\{\$\_\_createdAt\}` содержит значение **31.08.2024 08:30:56**: 1. `\{DateTime("YYYY-MM-DD hh:mm:ss", \{\$\_\_createdAt\}, "ru-RU")\}` —> 2024-08-31 08:30:56. 2. `\{DateTime("«DD» MMMM YYYY", \{\$\_\_createdAt\}, "ru-RU")\}` —> «31» августа 2024. 3. `\{DateTime("'DD' MMMM YYYY",\{\$\_\_createdAt\},"en\_US")\}` —> '31' August 2024. ```` Конец примера ### ```` Функция Now() Функция `Now()` подставляет в шаблон текущую дату и время с учётом часового пояса и локали. **Синтаксис:** `\{Now(\["формат": строка\], \["локаль": строка\], \["временная\_зона": строка\])\}`, где: - **формат** — вариант отображения даты и времени: - `"short"` — дата и время без секунд. Используется по умолчанию, если формат не указан; - `"date"` — только дата в числовом формате; - `"datelong"` — дата с прописным названием месяца; - `"time"` — только время в часах и минутах; - `"timelong"` — время с точностью до секунд. - **локаль** — отображение названий месяцев и формата даты на нужном языке, например `"ru"`, `"en"`. Все доступные варианты смотрите в разделе [«Формат передачи локали»](#locale); - **временная зона** — наименование временной зоны в принятом стандарте **IANA**, например `"Europe/Samara"`, `"America/Toronto"`. ```` начало примера ```` Примеры Предположим, что текущая дата и время по Москве — **13.04.2025 15:34**: 1. `\{Now()\}` —> 13.04.2025 15:34. Без аргументов функция отобразит дату и время с коротким форматом `"short"`, применятся локаль и временная зона, установленные в системе. 2. `\{Now("short", "ru")\}` —> 13.04.2025 15:34. 3. `\{Now("date", "ru")\}` —> 13.04.2025. 4. `\{Now("date", "en")\}` —> 04/13/2025. 5. `\{Now("datelong", "en-US")\}` —> April 13, 2025. 6. `\{Now("datelong", "ru-RU")\}` —> 13 апреля 2025 г. 7. `\{Now("time", "ru")\}` —> 15:34. 8. `\{Now("timelong", "ru", "Europe/Samara")\}` —> 16:34:22. В результате учитывается часовой пояс Самары. ```` конец примера ## ```` Получить количество элементов функцией Count() Функция `Count()` возвращает количество элементов, переданных в переменную типа [Таблица](360009707032.md#table) или [Приложение](app-data-type.md). С помощью функции можно: - показать количество вложенных элементов связанного приложения; - вывести итоговое количество строк в таблице; - подсчитать число элементов во вложенных таблицах. **Синтаксис:** `\{Count(\{\$код\_переменной\}: приложение или таблица)\}`. ```` Начало примера ```` Примеры 1. Подсчёт строк в таблице отчёта: `\{Count(\{\$report\_table\})\}` —> 12. 2. Подсчёт элементов в связанном приложении: `\{Count(\{\$app\})\}` —> 3. ```` Конец примера ### ```` Использование Count() в циклах \{for\} Функцию `Count()` можно использовать внутри [цикла \{for\}](#cycle) для подсчёта элементов во вложенных таблицах или вложенных связях. #### Вывести количество строк во вложенной таблице Если в строку основной таблицы вложена ещё одна таблица, например список выполненных работ, применим синтаксис: ```` \{for row in \{\$report\_table\}\} Subrow count: \{Count(\{\$row.execution\})\} \{end\} ```` где: - `\{\$report\_table\}` — основная таблица отчёта; - `\{\$row.execution\}` — вложенная переменная типа **Таблица** в строке таблицы. ## Просклонять значение Для изменения по падежам и родам Ф. И. О., слов, словосочетаний и чисел используются специальные функции. | | | |------|------| | **Задача** | **Функция** | | Просклонять Ф. И. О. и настроить порядок частей | [FormatFio()](#format_fio) | | Извлечь отдельную часть Ф. И. О.: фамилию, имя или отчество | [GetPartOfFullName()](#part_of_fio) | | Сформировать вариант фамилии другого рода | [AnotherGenderSecondName()](#another_gender_fio) | | Просклонять слово или словосочетание в единственном числе | [Incline()](#incline) | | Просклонять слово или словосочетание во множественном числе | [InclineMany()](#incline-many) | | Подставить число прописью и просклонять единицу измерения | [NumberToString()](#number-to-string) | | Изменить род прилагательного | [ChangeKind()](#change_kind) | Для каждой функции поддерживаются два эквивалентных варианта записи — на английском и русском языках. В шаблоне вы можете использовать любой из них. ### Функция FormatFio() Функция `FormatFio()` или `ФорматФио()` склоняет Ф. И. О. в нужном падеже и отображает составные части в заданном порядке. **Синтаксис:** `\{FormatFio(значение: "строка" или \{\$код\_переменной\}: Ф.И.О., \["падеж": строка\], \["формат": строка\])\}`, где: - **значение** — можно задать строкой, выделив её кавычками, или с помощью переменной типа **Ф.И.О.**; - **падеж** — указывается без учёта регистра одним из трёх вариантов: - `"Nominative"` | `"Именительный"` | `"И"` — именительный; - `"Genitive"` | `"Родительный"` | `"Р"` — родительный; - `"Dative"` | `"Дательный"` | `"Д"` — дательный; - `"Accusative"` | `"Винительный"` | `"В"` — винительный; - `"Instrumental"` | `"Творительный"` | `"Т"` — творительный; - `"Prepositional"` | `"Предложный"` | `"П"` — предложный. По умолчанию результат показывается с предлогом «о» или «об». Если его отображать не нужно, используйте параметр `"Предложныйбезпредлога"`. - **формат** — маска отображения Ф. И. О. Указывается в кавычках. Позволяет менять порядок частей, выводить их полностью или инициалами, с пробелом или без него. Регистр в маске не учитывается, итоговый результат показывается с заглавных букв: - `"Фамилия"` или `"Ф."`; - `"Имя"` или `"И."`; - `"Отчество"` или `"О."`. ```` начало примера ```` Примеры 1. Данные `\{FormatFio("Иванов Иван Иванович", "Р", "Фамилия И.О.")\}` —> Данные Иванова И.И. 2. Информация `\{FormatFio(\{\$fullname\}, "п", "фамилия и. о.")\}` —> Информация об Иванове И. И. Переменная `\{\$fullname\}` содержит значение **Иванов Иван Иванович** 3. При `\{ФорматФио("Иванов Иван Иванович", "предложныйбезпредлога", "фамилия и. о.")\}` —> При Иванове И. И. ```` конец примера ### ```` Функция GetPartOfFullName() Функция `GetPartOfFullName()` или `ФИО()` возвращает полное имя или отдельную его часть. **Синтаксис:** `\{GetPartOfFullName("значение": строка или \{\$код\_переменной\}: Ф.И.О., "часть Ф. И. О.": строка)\}`, где: - **значение** — можно задать строкой, выделив её кавычками, или с помощью переменной типа **Ф.И.О.**; - **часть Ф. И. О.** — наименование нужной части имени в полном или сокращённом варианте: - `"Фамилия"` или `"ф"`; - `"Имя"` или `"и"`; - `"Отчество"` или `"о"`; - `"полное имя"` или `"полн"`. ```` начало примера ```` Примеры Значение **Пушкин Александр Сергеевич** передаётся в функцию в строковом представлении и с помощью переменной `\{\$fullname\}`: 1. `\{GetPartOfFullName("Пушкин Александр Сергеевич", "о")\}` —> Сергеевич. 2. `\{ФИО(\{\$fullname\}, "полн")\}` —> Пушкин Александр Сергеевич. ```` конец примера #### ```` Альтернативный вариант обращения к частям Ф. И. О. Если данные хранятся в переменной типа **Ф.И.О.**, вы можете получить части имени без использования функций. Для этого укажите код переменной и обратитесь к нужному свойству через точку: - `\{\$код\_переменной.lastname\}` — фамилия; - `\{\$код\_переменной.firstname\}` — имя; - `\{\$код\_переменной.middlename\}` — отчество. ```` начало примера ```` Пример Переменная типа **Ф.И.О.** с кодом `\{\$user\}` содержит значение **Петров Иван Иванович**. `\{\$user.lastname\}` —> Петров. ```` конец примера ### ```` Функция AnotherGenderSecondName() Функция `AnotherGenderSecondName()` или `ФамилияПротивоположногоПола()` возвращает фамилию противоположного пола. **Синтаксис:** `\{AnotherGenderSecondName("фамилия": строка или \{\$код\_переменной\})\}`. В качестве аргумента можно передать текстовую строку с фамилией, переменную типа **Строка** или **Ф.И.О.**, если в поле указана только фамилия, без имени и отчества. ```` начало примера ```` Примеры 1. `\{AnotherGenderSecondName("Петров")\}` —> Петрова. 2. `\{ФамилияПротивоположногоПола(\{\$executor\})\}` —> Петрова. Переменная типа **Ф.И.О.** `\{\$executor\}` содержит только фамилию: **Петров**. ```` конец примера ### ```` Функция Incline() Функция `Incline()` или `Просклонять()` возвращает заданную строку в указанном падеже. **Синтаксис:** `\{Incline(значение: "строка" или \{\$код\_переменной\}, \["падеж": строка\], \["признаки": строка\])\}`, где: - **значение** — можно передать текстовые данные или задать с помощью переменной типа **Строка**; - **падеж** — указывается полным названием или первой буквой так же, как для функции склонения Ф. И. О — [FormatFio ()](#format_fio), например `"Nominative"` | `"Именительный"` | `"И"`. В предложном падеже по умолчанию отображается предлог «о» или «об». Если его отображать не нужно, используйте параметр `"Предложныйбезпредлога"`. - **признаки** — грамматические свойства слова, которые помогают функции точнее определить форму склонения. Выделяются кавычками и комбинируются через пробел: - `"м"` — мужской род; - `"ж"` — женский род; - `"о"` — одушевлённое; - `"но"` — неодушевлённое; - `"ф"` — Ф. И. О.; - `"н"` — имя нарицательное. ```` начало примера ```` Примеры 1. `\{Incline("договор подряда", "П", "м но")\}` —> о договоре подряда; 2. `Описано в \{Просклонять("статья", "предложныйбезпредлога", "ж но")\}` —> Описано в статье. ```` конец примера ### ```` Функция InclineMany() Функция `InclineMany()` или `ПросклонятьМнож()` возвращает заданную строку во множественном числе и указанном падеже. **Синтаксис:** `\{InclineMany(значение: "строка" или \{\$код\_переменной\}: строка, \["падеж": строка\], \["признаки": строка\])\}`. Параметры задаются так же, как для функции `Incline()`. `начало примера` Примеры 1. `\{InclineMany("договор подряда", "П")\}` —> о договорах подряда; 2. Зафиксировано в `\{ПросклонятьМнож(\{\$currency\},предложныйбезпредлога)\}` —> Зафиксировано в рублях. Переменная `\{\$currency\}` — это свойство типа **Строка** со значением **рубль**: ```` конец примера ### ```` Функция NumberToString() Функция `NumberToString()` или `ЧислоВСтроку()` преобразует числовое значение в текст прописью с возможностью указать падеж, единицу измерения и шаблон отображения. **Синтаксис:** `\{NumberToString(значение: число, \["падеж": строка\], \["единица измерения": строка\], \[объём единицы измерения: число\], \["формат": строка\])\}`, где: - **значение** — число для преобразования в строку; - **падеж** — указывается полным названием или первой буквой так же, как для функции склонения Ф. И. О — [FormatFio ()](#format_fio), например `"Nominative"` | `"Именительный"` | `"И"`. По умолчанию употребляется именительный падеж; - **единица измерения** — наименование в строковом представлении. Если нужно указать единицу измерения для целой и дробной частей, разделите их вертикальной чертой **|**, например `"рубль|копейка"` или `"евро|евроцент"`; - **объём единицы измерения** — количество частей в одной целой единице измерения. Прописывается числом и используется для расчёта дробной части. По умолчанию задано значение **100**; - **формат** — шаблон отображения числа. Если указывать объём единицы измерения не требуется, его можно пропустить и передать формат в функцию следующим аргументом. **Допустимые шаблоны для формата отображения числа** В виде произвольной строки с тегами вы можете указать следующие значения: - `"\{ЦЧ\}"` или `"\{ЦелаяЧасть\}"` — целая часть числа; - `"\{ДЧ\}"` или `"\{ДробнаяЧасть\}"` — дробная часть числа; - `"\{ПЦЧ\}"` или `"\{ПрописьЦелойЧасти\}"` — целая часть прописью; - `"\{ПДЧ\}"` или `"\{ПрописьДробнойЧасти\}"` — дробная часть прописью; - `"\{НЦЧ\}"` или `"\{НаименованиеЦелойЧасти\}"` — наименование единицы измерения целой части; - `"\{НДЧ\}"` или `"\{НаименованиеДробнойЧасти\}"` — наименование единицы измерения дробной части; - `"\{ЦЧ:Ф\}"` или `"\{ЦелаяЧасть:Ф\}"`, а также `"\{ДЧ:Ф\}"` или `"\{ДробнаяЧасть:Ф\}"` — целая или дробная части с форматом отображения. Вместо **Ф** подставляется символ стандартного числового формата. Полный список обозначений приведен в [документации Microsoft](https://msdn.microsoft.com/ru-ru/library/fzeeb5cd(v=vs.110).aspx). ```` начало примера ```` Примеры 1. `\{NumberToString(5634, "П")\}` —> пяти тысячах шестистах тридцати четырёх. 2. `\{NumberToString(5634.37, "Р")\}` —> пяти тысяч шестисот тридцати четырёх целых тридцати семи сотых. 3. `\{NumberToString(5850, "П", "рубль")\}` —> пяти тысячах восьмистах пятидесяти рублях. 4. `\{NumberToString(5830.35, "Т", "евро|евроцент")\}` —> пятью тысячами восемьюстами тридцатью евро тридцатью пятью евроцентами. 5. `\{NumberToString(46.25, "И", "ящик|мешок", 38, "\{ЦЧ\} (\{ПЦЧ\} \{НЦЧ\}) примерно \{ДЧ\} (\{ПДЧ\} \{НДЧ\}) и один контейнер")\}` —> 46 (сорок шесть ящиков) примерно 10 (десять мешков) и один контейнер. В исходном значении указано: .25 — это четверть. В целом задано 38 частей. 38/4 = 9.5, результат округляется до 10. 6. `\{NumberToString(12345.5, "Д", "бочка|литр", 60, "\{ЦЧ:N\} (\{ПЦЧ\} \{НЦЧ\}) и \{ДЧ\} (\{ПДЧ\} \{НДЧ\})")\}` —> 12,345.000 (двенадцати тысячам трёмстам сорока пяти бочкам) и 30 (тридцати литрам). В значении "\{ЦЧ:N\}" символ **N** задаёт формат отображения, который требует показывать дробную часть. Поскольку в функции дробная часть обрабатывается отдельно, после запятой выводятся нули. ```` конец примера ### ```` Функция ChangeKind() Функция `ChangeKind()` или `ИзменитьРод()` меняет род или число прилагательного. **Синтаксис:** `\{ChangeKind("прилагательное": строка, "признак": строка)\}`, где: - **прилагательное** — словосочетание или отдельное прилагательное в именительном падеже мужского рода; - **признак** — род или число для преобразования. Допустимые значения: - `"м"` или `"муж"` — мужской род; - `"ж"` или `"жен"` — женский род; - `"с"` или `"ср"` — средний род; - `"мн"` или `"множ"` — множественное число. ```` начало примера ```` Примеры 1. `\{ChangeKind("спокойный", "жен")\}` —> спокойная. 2. `\{ИзменитьРод("спокойный", "мн")\}` —> спокойные. ```` конец примера ## ```` Вывести текст по условию Условия позволяют выводить в документе текст в зависимости от значения переменной или наличия данных в поле. Синтаксис: `\{if условие\} текст \{else\} альтернативный текст \{end\}`, где: - **условие** — проверяемое логическое выражение следующего вида `\{\$код\_переменной\} оператор значение`: - **оператор** — знак сравнения: равно, не равно, больше, меньше и т. д.; - **значение** — текстовая строка в кавычках или число; - **текст** — содержимое, которое отобразится в документе при выполнении условия; - **\{else\} альтернативный текст** — необязательный параметр. Обозначает содержимое, которое отобразится, если условие не выполнено. Допустимые операторы для составления условия При написании условий вы можете использовать следующие операторы: - `=`** **— равно; - `<>` — не равно; - `>` — больше; - `>=` — больше или равно; - `<` — меньше; - `<=` — меньше или равно. ### Проверить одно значение ```` начало примера ```` Пример ```` \{if \{\$user\_name\} = "Петров Илья"\} С уважением, Петров Илья \{end\} ```` Если значение поля совпадает с указанным, в документе отображается текст «С уважением, Петров Илья». ```` конец примера ### ```` Вывести один из двух вариантов ```` начало примера ```` Пример ```` \{if \{\$weekday\} = "Пятница"\} До свидания, хороших выходных\! \{else\} До свидания\! \{end\} ```` В скрипте по текущей дате вычисляется день недели и записывается в переменную типа **Строка** с кодом `\$weekday`.` `В зависимости от значения текущего дня недели отображается один из двух вариантов текста. ```` конец примера ### ```` Проверить поле «Выбор „да/нет“» Для переменных типа **Выбор «да/нет»** в условии нужно указывать значения из поля **Варианты**. По умолчанию это **Да** и **Нет**. ```` начало примера ```` Пример ```` \{if \{\$options\} <> "Нет"\} Оплата произведена \{end\} ```` Текст отображается, если выбран вариант **Да**. ```` конец примера ### ```` Проверить заполнение поля В условии можно проверить наличие значения у свойства элемента приложения. ```` начало примера ```` Пример ```` \{if \{\$document\}\} \{\$document\} \{end\} ```` Если в поле типа **Файлы** загружен документ, в сгенерированном файле отображается его название. ```` конец примера ```` **Важно:** для свойств типа **Приложение** или **Файлы** условие применяется, если включена опция **Один**. Если разрешено добавление нескольких элементов, используйте [Цикл \{for\}](#cycle). ### Особенность работы с условиями в Excel При оформлении условий в файлах формата **.xlsx** размещайте операторы `\{if условие\}`, `\{else\}` и `\{end\}` в отдельных строках таблицы, свободных от других данных. В процессе генерации документа строки с этими операторами удаляются целиком. Поэтому любой текст или значения в соседних ячейках на этих строках будут удалены вместе с ними. ```` начало примера ```` Пример размещения в Excel | | | |------|------| | **Ячейка А1** | **Ячейка B1** | | ````
\{if \{\$status\} = "Согласовано"\}
```` | ````
| | Данные договора | Сумма: 100 000 руб. | | ````
\{end\}
```` | ````
| В итоговом документе строки с `\{if\}` и `\{end\}` удалятся, а строка с данными останется на своём месте. ```` конец примера ### ```` Сложные условия с операторами OR и AND Для объединения нескольких проверок в одном запросе используются логические операторы: - `OR` — условие выполнится, если верно хотя бы одно из выражений; - `AND` — условие выполнится, только если все перечисленные выражения верны. #### Пример использования оператора OR ```` начало примера \{if \{\$trip.location\_type\} = "Гостиница" OR \{\$trip.location\_type\} = "Хостел"\} Расходы на проживание будут возмещены после проверки отчёта о командировке. \{end\} ```` В зависимости от типа размещения в документе отображается уведомление о возмещении дополнительных расходов. ```` конец примера #### ```` Пример использования оператора AND ```` начало примера \{if \{\$business\_trip\_request.isApproved\} AND \{\$business\_trip\_tickets.isPurchased\}\} Командировка запланирована на \{\$business\_trip\_request.date\}. \{else\} Командировка еще не запланирована. \{end\} ```` Дата командировки отобразится, если выполнится несколько условий: заявка одобрена, билеты куплены. В остальных случаях в документе показывается, что командировка не запланирована. ```` конец примера #### ```` Пример комбинирования операторов OR и AND Несколько операторов можно объединять в одной конструкции. Чтобы задать правильный порядок проверок, используйте скобки. ```` начало примера \{if (\{\$business\_trip\_request.location\_type\} = "Гостиница" OR \{\$business\_trip\_request.location\_type\} = "Хостел") AND (\{\$business\_trip\_request.price\} = 5 000) \{\$business\_trip\_request.city\} \{end\}  ```` Город показывается в зависимости от типа размещения и суммы, запрошенной на проживание. ```` конец примера ## ```` Вывести список или сформировать таблицу циклом \{for\} Цикл `\{for\}` используется, чтобы отобразить в документе список, например перечислить [элементы приложения](#app-cycle) или показать несколько [файлов и изображений](another-template-syntax-functions.md#pasteimage). **Синтаксис:** ```` \{for элемент in список\} действия с элементом \{end\}```` где: - **элемент** — временная переменная-контейнер. На каждом шаге цикла в эту переменную последовательно помещается следующий объект из списка. Имя этой переменной задаётся произвольно, например `item`, `row`, `position`, и затем используется внутри цикла для обращения к текущему объекту или его свойствам; - **список** — переменная системы из контекста приложения или бизнес-процесса, содержащая массив данных, например список приложений, файлов или строк таблицы, элементы которого нужно последовательно отобразить в документе; - **действия с элементом** — тело цикла, например текст, свойства, функции или строки таблицы, которое будет повторяться для каждого объекта из списка. ```` Начало примера ```` Пример отображения нескольких товаров В приложении есть переменная **Товар** с типом **Приложение (несколько)** и кодом `item`. Чтобы перечислить список заказанных товаров, используем конструкцию: ```` \{for position in \{\$item\}\} Заказан товар: \{\$position\} \{end\} конец примера ### ```` Отобразить данные списком Цикл `\{for\}` можно использовать для выгрузки данных из связанного приложения, когда для поля включена опция **Несколько**. Коды полей элементов приложения можно указывать с префиксом `data` или без него: - `\{\$data.appListField\}`; - `\{\$appListField\}`. #### Задать цикл \{for\} для списка в файлах Word В файлах **.doc** или **.docx** данные из связанного приложения можно показывать списком или блоками текста друг за другом. ```` начало примера ```` Пример ```` \{for app in \{\$appListField\}\} Приложение: \{\$app\}, с именем \{\$app.\_\_name\} на сумму \{\$app.money\} \{end\} конец примера #### ```` Задать цикл \{for\} для списка в файлах Excel В файлах **.xlsx** цикл позволяет выводить данные связанного приложения построчно. ```` начало примера ```` Пример `\{for app in \{\$appListField\}\}` | | | | |------|------|------| | `\{\$app\}` | `\{\$app.\_\_name\}` | `\{\$app.money\}` | `\{end\}` ```` конец примера ```` **Важно:** операторы `\{for\}` и `\{end\}` размещаются на отдельных строках таблицы, свободных от других данных, как при[ написании условий \{if\}](#if-for-in-excel). Иначе вся строка удалится вместе с оператором. Исключение составляет текст в [объединённых ячейках](#merged-cells). ### Отобразить данные таблицей С помощью цикла можно вывести данные не только списком, но и таблицей. При [загрузке шаблона в систему](360026936731.md#add_variables) укажите для переменной в цикле тип данных [Таблица](360009707032.md#table). #### Задать цикл \{for\} для таблицы в файлах Word Чтобы генерировать таблицу в файле формата **.doc** или **.docx**: 1. Отделите первую строку таблицы с помощью команды **Разделить таблицу**. 2. В появившейся пустой строке объявите цикл `\{for\}`. 3. В таблице укажите переменные с префиксом `row.data` или `row`, например из контекста бизнес-процесса. 4. Под таблицей закройте цикл командой `\{end\}`. Пример шаблона: **(template-syntax-1.png)** #### Задать цикл \{for\} для таблицы в файлах Excel Чтобы вывести в документ данные из таблицы ELMA365, например список товаров с количеством и стоимостью: 1. Пропишите команды `\{for\}` и `\{end\}` в первом столбце таблицы. 2. Введите коды полей приложения с префиксом `row.data` или `row`. Префикс позволяет обратиться к элементу внутри цикла и создать в документе столько строк, сколько заполнено в таблице ELMA365. В строках с операторами `\{for\}` и `\{end\}` нельзя размещать другой текст, как при[ написании условий \{if\}](#if-for-in-excel). Иначе вся строка удалится вместе с оператором. Исключение составляет текст в [объединённых по вертикали ячейках](#merged-cells). Пример формирования шаблона: **(template-syntax-2.png)** В цикл `\{for\}` можно добавить условие `\{if\}`. Пример приведён в статье [«Настроить шаблоны листов согласования и ознакомления»](ready-made-sheets-settings.md). В шаблоне нельзя располагать несколько генерируемых таблиц горизонтально рядом друг с другом: параллельные циклы `\{for\}` не обрабатываются. Можно создать вложенную таблицу, а затем объединить несколько таблиц в одну, например в бизнес-процессе с помощью блока [Скрипт](360027203731.md). На основе объединённой таблицы формируется документ по шаблону. ### Вложенные таблицы Цикл `\{for\}` можно использовать для создания вложенной таблицы. Обратите внимание, в шаблоне поддерживается не более одной вложенной таблицы. Для обращения к колонкам вложенной таблицы вместо `row.data` или `row` используется другой префикс: - `subrow.data`; - `subrow`. В строках с операторами `\{for\}` и `\{end\}` нельзя располагать другой текст, так как он удаляется при генерации. Исключение составляют объединённые по вертикали ячейки. В примере показана генерация таблицы отчёта. Значение `\{\$row.author\}` отобразится, т. к. ячейки объединены по вертикали. **(template-syntax-3.png)** ### Вывести порядковый номер в таблице Чтобы показать в таблице порядковый номер строки, в шаблоне используйте префикс `row.data` или `row` и системное свойство идентификатора: `\{\$row.\_\_index\}`. Пример шаблона таблицы с номером строки, названием товара и стоимостью: **(template_syntax-5.png)** ## Специальные функции Для отдельных задач используются специальные функции: - `GenerateBarcode()` — вывести значение в виде штрихкода; - `JobPosition()` — подставить должность пользователя; - `PasteImage()` — вставить изображение; - `Hyperlink()` — преобразовать заданное значение в гиперссылку; - `ExtText()` — создать пользовательскую функцию для расширенной работы с шаблонами. Синтаксис и примеры приведены в статье [«Специальные функции синтаксиса шаблонов»](another-template-syntax-functions.md). ## Пример настройки шаблона договора Рассмотрим, как настроить автоматическую генерацию на примере договора поставки: 1. ## Создадим файл шаблона и разметим его переменными и функциями. Документ можно подготовить в формате .docx или .xlsx. разметьте его переменными и функциями. Для ознакомление с файлом, использованным в примере, вы можете [скачать его на свой компьютер](doc_template.docx). 2. ## [Добавим шаблон в приложение](360026936731.md) и сопоставим переменные из шаблона с полями. **(template_syntax-new6.png)** 3. Настроим бизнес-процесс. Чтобы файл формировался автоматически, на схему добавим блок [Генерация по шаблону](360026720792.md) и укажем в настройках созданный ранее шаблон. 4. Когда пользователь заполнит данные на форме элемента приложения и процесс дойдёт до шага генерации, создастся итоговый файл. **(template_syntax-7.PNG)**