В статье описаны правила использования дополнительных функций синтаксиса шаблонов:
- 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)}
— функция обрежет изображение в переменной типа Файлы до указанного размера без учёта исходных пропорций.
Конец примера
Функция HYPERLINK для таблиц
При формировании шаблона в файле формата .xls и .xlsx можно использовать функцию HYPERLINK
. Это стандартная функция программы Excel, которая позволяет преобразовать заданное значение в гиперссылку.
В качестве аргументов можно использовать переменные типа Строка из контекста приложения, а также задать значения вручную. Для корректной работы функции указывается полный URL‑адрес ссылки.
Синтаксис функции: HYPERLINK("{$param1: строка}" или "<полный URL-адрес>";"{$param2: строка}" или "<значение гиперссылки>")
.
начало примера
Примеры
=HYPERLINK("{$site}";"Смотрите на официальном сайте")
— адрес сайта указан в виде строки в элементе приложения, значение гиперссылки задано вручную;=HYPERLINK("https://elma365.com/ru/";"{$__name}")
— адрес сайта прописан вручную, значение гиперссылки формируется из поля в элементе приложения.
конец примера
Функция ExtText
Если для настройки шаблона системных функций недостаточно, вы можете создать пользовательскую функцию ExtText
. Функция позволяет вызывать методы API, описанные в пользовательских модулях, и применять их к генерируемому шаблону.
Синтаксис функции: {ExtText("ID модуля", "адрес метода", {$дополнительный параметр})}
:
- ID модуля — символы из URL модуля, идущие после /ext_. Например, если URL модуля mycompany.elma365.ru/admin/extensions/ext_12ab-1212, в функцию нужно вставить 12ab-1212;
- адрес метода — значение поля Адрес из таблицы, расположенной на вкладке Методы API в настройках модуля.
- дополнительный параметр — опциональный параметр, который передаётся в указанный метод, например, свойство приложения. В теле запроса дополнительные параметры отображаются в виде p1, p2 и т. д. Они передаются в функцию
ExtText
через запятую после обязательных параметров. Значения будут присваиваться параметрам в том порядке, в котором они объявлены в теле запроса.
Начало примера
Пример
Вы можете применить функцию ExtText
в названии элемента приложения. Для этого:
- Создайте модуль и настройте в нём метод API, который будет использоваться для генерации названия элемента.
- Сформируйте название элемента по шаблону, использовав функцию
ExtText
.
Например:
{ExtText("4c34-822c", "name", "Текст для примера", {$_index})}
- Функция запустит метод, внутри которого будут обрабатываться переданные параметры. После выполнения заданных в методе условий получим результат, который будет использоваться в качестве названия элемента приложения.
Пример скрипта метода API для формирования названия элемента:
async function name(req: HttpApiRequest): Promise<HttpResponse | void> { |
Конец примера
При использовании сложных пользовательских функций вы можете изменить режим их обработки для ускорения генерации документов по шаблону. Все переменные и функции будут обрабатываться не последовательно друг за другом, а параллельно.
Задать количество параллельных потоков обработки с помощью дополнительных параметров можно после включения фича-флага enableConcurrencyTemplateMapper
. Подробнее читайте в статьях «Изменение параметров ELMA365 Enterprise» и «Изменение параметров ELMA365 Standard». Если вы используете поставку SaaS Enterprise, для включения фича‑флага обратитесь к вашему менеджеру ELMA365.