Специальные функции синтаксиса шаблонов

В статье описаны правила использования дополнительных функций синтаксиса шаблонов:

  • Barcode() — вывести содержимое переменной в документе в виде штрихкода;
  • JobPosition() — подставить должность пользователя;
  • PasteImage() — вставить на месте переменной изображение;
  • Hyperlink() — преобразовать заданное значение в гиперссылку;
  • ExtText() — создать пользовательскую функцию для расширенных возможностей работы с шаблоном документов.

Функция Barcode()

Функция Barcode() используется для кодирования строки приложения и добавления её в документ в виде штрихкода. Например, таким образом можно сгенерировать штрихкод для регистрационного номера договора или другого уникального номера документа. В дальнейшем с помощью штрихкода можно будет сопоставить документ на бумажном носителе и электронную копию.

Взаимодействие ELMA365 с ПО для считывания штрихкодов осуществляется через модули интеграции. Подробнее о них можно прочитать в статьях «Модули расширения системы» и в справке по публичному API ELMA365.

Генерация штрихкода доступна для форматов, поддерживаемых в программах Word и Excel.

Синтаксис функции: GenerateBarcode(text: строка:1, format: формат кода:2, высота сгенерированного штрихкода в пикселях).

  • [1] — строка зависит от формата, указываемого во втором параметре;
  • [2] — возможные форматы штрихкодов и требования к строке:
    • QR Code — любая строка. Поддерживается разрешение до 300 DPI;
    • EAN-8 — строка до восьми цифр, где последняя используется как контрольная;
    • EAN-13 — строка из 12 цифр или 13 цифр, где последняя — контрольная.

Вы также можете указать формат EAN без уточнения типа. В таком случае тип сгенерированного штрихкода будет зависеть от количества цифр в передаваемой строке;

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

Если в шаблоне одна и та же строка используется для генерации QR-кода два раза, но при этом указывается разный размер, то в обоих случаях сгенерируется QR-код одинакового размера.

начало внимание

Если при использовании форматов EAN контрольная сумма не была указана, она добавится автоматически. Для корректной работы сканер штрихкодов следует настроить на работу с данными форматами.

конец внимание

Мы рекомендуем использовать формат QR Code, так как он не имеет таких строгих ограничений, как форматы EAN.

Для примера возьмём строку $numberstring = «5901234123457». Она подойдёт для формата QR Code и EAN-13.

начало примера

Примеры

  • {GenerateBarcode({$numberstring}, "QR Code", "125")};
  • {GenerateBarcode({$numberstring}, "EAN-13", "125")}.

конец примера

Для формата EAN-8 в строке должно быть не больше восьми цифр: $numberstring = «59012341».

Функция JobPosition()

Эта функция используется для получения должности пользователя.

Синтаксис функции: JobPosition(param1: пользователь, формат: строка).

Вы можете использовать переменную first для передачи первой должности, и переменную all — для всех должностей пользователя.

начало примера

Пример

{JobPosition({$__createdBy}, all)} —> функция передаст все должности пользователя, записанного в поле Автор.

конец примера

Функция PasteImage()

Чтобы вставить в шаблон документа изображение из контекстной переменной типа Изображение и Файлы, используйте функцию PasteImage().

Синтаксис функции: PasteImage(param1: изображение/файл, ширина в пикселях, высота в пикселях, обрезать вместо сжатия: true/false).

Начало примера

Примеры

  • {PasteImage({$image})} — вставка изображения с исходными значениями ширины и высоты из переменной типа Изображение;
  • {PasteImage({$file.__id})} — вставка изображения с исходными значениями ширины и высоты из переменной типа Файлы;
  • {PasteImage({$image}, 200)} — изображение из свойства типа Изображение отобразится с шириной 200 пикселей. Значение высоты изменится, исходные пропорции сохранятся;
  • {PasteImage({$file.__id}, 200, 400)} — функция масштабирует изображение из свойства типа Файлы до строго заданного размера;
  • {PasteImage({$image}, auto, 400)} — изображение из переменной типа Изображение отобразится с высотой 400 пикселей. При этом значение ширины масштабируется, исходные пропорции сохранятся;
  • {PasteImage({$file.__id}, 200, 400, true)} — функция обрежет изображение из переменной типа Файлы до указанного размера без учёта исходных пропорций.

Конец примера

По умолчанию функция PasteImage() позволяет вставить в документ только одно изображение или файл. Чтобы вывести несколько данных, примените функцию внутри цикла for.

Начало примера

Пример

  1. В документе нужно отобразить список изображений. Список передаётся в переменную шаблона image1 типа Изображение (несколько).
  2. Цикл for позволяет неоднократно применить функцию PasteImage(), чтобы последовательно вставить в документ все изображения из списка.
    Для корректной работы цикла нужно использовать две переменные:
  • image1 — содержит несколько изображений;
  • image — временная переменная, в которую по очереди помещается каждое изображение из image1.

{for image in {$image1}}
{PasteImage({$image}, 400, 200)}
{end}

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

Конец примера

Функция Hyperlink()

Функция Hyperlink() используется в шаблонах формата .docx, .xls и .xlsx и позволяет преобразовать заданное значение в гиперссылку.

В качестве аргументов функции можно использовать переменные типа Строка из контекста приложения, а также задать значения вручную. Для корректной работы функции указывается полный URL‑адрес ссылки.  

Синтаксис функции:

  1. {Hyperlink("URL-адрес", "Текст ссылки")} — отобразится текст‑гиперссылка, в которой настроен переход на указанный сайт;
  2. {Hyperlink("URL-адрес")} — гиперссылка отобразится в виде URL-адреса.

начало примера

Примеры функции с использованием переменных из контекста приложения:

  • {Hyperlink("{$site}", "Смотрите на официальном сайте")} — адрес сайта указан в виде строки в элементе приложения, значение гиперссылки задано вручную;
  • {Hyperlink ("https://elma365.com/ru/", "{$__name}")} — адрес сайта прописан вручную, значение гиперссылки формируется из поля в элементе приложения.

конец примера

Функция ExtText()

Если для настройки шаблона системных функций недостаточно, вы можете использовать пользовательскую функцию ExtText(). Она позволяет вызывать методы API, созданные в пользовательских модулях, и подставлять результаты их работы в генерируемый по шаблону документ.

Синтаксис функции

Функция задаётся следующим образом:

{ExtText("ID модуля", "адрес метода", {$дополнительный параметр 1}, "дополнительный параметр 2")},

где:

  • ID модуля — символы из URL модуля, идущие после /ext_. Например, если URL модуля mycompany.elma365.ru/admin/extensions/ext_12ab-1212ab-12, в функцию передаётся значение "12ab-1212ab-12";
  • адрес метода — для получения адреса перейдите в настройки модуля, где создан метод, откройте вкладку Методы API. В списке найдите нужный метод и скопируйте значение из поля Адрес;
  • дополнительные параметры — один или несколько параметров, которые передаются в метод API. В синтаксисе функции параметры указываются через запятую в нужном порядке. Свойства приложения заключаются в фигурные скобки, например {$app_field}. Другие параметры прописываются в кавычках, например "function". В скрипте метода API параметры доступны как ключи p1, p2 и далее в том порядке, в котором они перечислены в функции ExtText().

Ускорение обработки пользовательских функций

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

Для этого включается фича-флаг enableConcurrencyTemplateMapper, а в конфигурационном файле с помощью специального параметра задаётся количество параллельных потоков обработки.

Подробнее читайте в статьях «Изменение параметров ELMA365 Enterprise» и «Изменение параметров ELMA365 Standard». Если вы используете поставку SaaS Enterprise, для включения фича‑флага обратитесь к вашему менеджеру ELMA365.

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

С помощью метода API в модуле и функции ExtText() вы можете вывести в документе, сгенерированном по шаблону, результат арифметических операций: сложение, вычитание, деление, умножение. В качестве аргументов для операций в функции можно использовать произвольные числа или поля приложения типа Число, Деньги, Строка — если в виде строки указано число.  

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

  • итоговую сумму с учётом фиксированной стоимости доставки;
  • остаток по платежу после оплаты аванса;
  • сумму неустойки в размере двойного аванса;
  • ежемесячную выплату клиента при рассрочке на указанное количество месяцев.

Шаг 1. Настроить контекст приложения

Для реализации примера в приложении Договоры нужно создать следующие свойства:

  • Сумма договора (sum_total) — поле типа Деньги;
  • Авансовый платёж (advance_payment) — поле типа Деньги;
  • Срок рассрочки (installment_months) — поле типа Число. Менеджер указывает в карточке договора срок в месяцах, на который клиенту предоставляется рассрочка на оплату суммы по договору.

Шаг 2. Создать метод API в модуле

Все вычисления будут выполняться с помощью скрипта в методе API. Для настройки:

  1. Перейдите в раздел Администрирование > Модули. Создайте пользовательский модуль или откройте управление существующего. Убедитесь, что модуль включён.
  2. Перейдите на вкладку Методы API, откройте редактор методов и нажмите + Добавить.
  3. В качестве параметров метода укажите:
  • название — Выполнение расчёта;
  • адрес — выберите метод Get и укажите значение arithmetic, которое в дальнейшем будет указано в функции ExtText();
  • название функции — doArithmetic.
  1. Сохраните настройки метода.

Подробнее читайте в статье о создании метода в модуле.

Шаг 3. Задать скрипт метода API

В редакторе методов перейдите на вкладку Скрипты и объявите функцию doArithmetic.

Она будет вызываться из шаблона для генерации документа с помощью указанной в нём функции: {ExtText("ID модуля", "адрес метода", {$операнд 1}, {$операнд 2}, "операция")}. Параметры из функции автоматически передаются в объект с ключами p1, p2, p3.

Скрипт принимает аргументы, преобразует значения переменных в числа и выполняет выбранную арифметическую операцию: сложение — add, вычитание — subtract, умножение — multiply, деление — divide.

Скрипт для выполнения арифметических операций через API модуля

 
async function doArithmetic(req: HttpApiRequest): Promise<HttpResponse | void> {
   console.log(`Арифметическая функция вызвана`);
 
// Создаём объект ответа, который будет возвращён в шаблон
   const resp = new HttpResponse();
 
// Получаем тело запроса как строку. В нём содержатся параметры, переданные в функцию ExtText()
   const bodystr = req.body!.toString();
   console.log(`Сырые данные запроса: ${bodystr}`);
 
// Преобразуем JSON-строку в объект для удобной работы с параметрами
   const parsed = JSON.parse(bodystr);
 
// Вспомогательная функция для преобразования значения в число. Необходима, чтобы обработать любой формат числа из шаблона, например из переменной типа Деньги или дробное число  
   function parseNumber(value: any): number {
// если число корректного формата — возвращаем в исходном виде. Подходит и для свойств типа Деньги
       if (typeof value === 'number') return value;
 
// если число передано в строке — заменяем запятую на точку и преобразуем в число
       if (typeof value === 'string') {
// убираем пробелы и заменяем запятую на точку
           const cleaned = value.replace(/\s/g, '').replace(',', '.');
           const result = Number(cleaned);
           return result;
       }
 
// для всех остальных типов (boolean, null, undefined) преобразовываем стандартным способом
       return Number(value);
   }
 
// Извлекаем параметры из запроса. В функцию ExtText() параметры передаются как ключи p1, p2, p3 и т. д. в порядке их перечисления
   const a = parseNumber(parsed.p1); // первое число (операнд 1)
   const b = parseNumber(parsed.p2); // второе число (операнд 2)
   const operator = parsed.p3; // операция: "add", "subtract", "multiply" или "divide".
   console.log(`Парсинг: a = ${a} (${typeof a}), b = ${b} (${typeof b}), оператор = "${operator}"`);
 
// Проверяем, что оба числа корректны.
   if (!isFinite(a) || !isFinite(b)) {
       const errorMsg = `Ошибка: неверные числа (a=${parsed.p1}, b=${parsed.p2})`;
       console.log(errorMsg);
       resp.status(200)
           .content(errorMsg)
           .set('Content-Type', 'text/html');
       return resp;
   }
 
// Выполняем арифметическую операцию в зависимости от переданного оператора
   let result: string;
    switch (operator) {
       case 'add':
           result = String(a + b);
           break;
                  case 'subtract':
           result = String(a - b);
           break;          
                  case 'multiply':
           result = String(a * b);
           break;
                  case 'divide':
// проверяем деление на ноль, чтобы избежать ошибки
           if (b === 0) {
               result = 'Ошибка: деление на ноль!';
           } else {
               result = String(a / b);
           }
           break;
                  default:
// если передан неизвестный оператор, сообщаем об ошибке
           result = `Ошибка: неизвестная операция "${operator}"`;
           break;
   }
 
    console.log(`Результат вычисления: ${result}`);
 
// Формируем HTTP-ответ:
 статус 200 — успешное выполнение
 Content-Type: text/html — используется, чтобы результат корректно отображался в шаблоне
 В теле ответа передаём вычисленный результат
 
   resp
       .status(200)
       .content(result)
       .set('Content-Type', 'text/html');
 
    return resp;
}

 

Шаг 4. Добавить функцию ExtText() в шаблон документа

В файле шаблона договора добавьте вызовы функции ExtText() для каждой операции. В функции укажите идентификатор созданного модуля, например 8ca92961-2c8a-418e-abff-7761a962265a, адрес метода, например arithmetic, свойства приложения или числовой аргумент и операцию:

  1. Операция сложения: {ExtText("8ca92961-2c8a-418e-abff-7761a962265a", "arithmetic", {$sum_total}, "15 000", "add")} — получим итоговую стоимость по договору с учётом фиксированной суммы доставки в 15 000 рублей.
  2. Операция вычитания: {ExtText("8ca92961-2c8a-418e-abff-7761a962265a", "arithmetic", {$sum_total}, {$advance_payment}, "subtract")} — получим остаток к оплате по договору после внесения авансового платежа.
  3. Операция умножения: {ExtText("8ca92961-2c8a-418e-abff-7761a962265a", "arithmetic", {$advance_payment}, "2", "multiply")} — получим неустойку при досрочном расторжении договора в размере двойного авансового платежа.
  4. Операция деления: {ExtText("8ca92961-2c8a-418e-abff-7761a962265a", "arithmetic", {$sum_total}, {$installment_months}, "divide")} — получим ежемесячный платёж при рассрочке в указанное количество месяцев.

Подробнее читайте в статье о добавлении и настройке шаблона для документов.

Предположим, что в карточке договора указано: общая сумма договора — 500 000, авансовый платёж — 100 000, срок рассрочки — 4 месяца. Тогда в сгенерированном по шаблону договоре рассчитаются следующие значения:

  • итоговая сумма — 515 000;
  • остаток к оплате — 400 000;
  • неустойка — 200 000;
  • ежемесячный платёж — 125 000.
360027003711.html service-portal.html