Формулы и переменные в шаблонах

Данные попадают в бланк через формулы jXLS в синтаксисе ${...}. Разберём объект документа, переменные шапки, цикл по позициям, дополнительные поля и форматирование чисел и дат — то, из чего собирается любой шаблон.

Как устроены формулы jXLS

Шаблон МойСклад — это xls-файл, в ячейки которого вписаны формулы библиотеки jXLS. Синтаксис единый: выражение заключается в фигурные скобки с долларом — ${...}. При печати сервис вычисляет каждое такое выражение и подставляет вместо него значение.

Ключевой объект — o: это текущий документ, из которого читаются все данные. Обращение к его полям идёт через точку: ${o.name} — номер, ${o.moment} — дата и время. Внутри строки позиций появляется второй объект — row, текущая строка списка товаров.

Важно понимать разделение труда: за подстановку данных отвечают формулы jXLS, а за арифметику и внешний вид — штатные средства Excel. Одна ячейка может содержать и формулу подстановки, и обычную формулу таблицы, которая посчитает итог поверх подставленных значений. Такое сочетание и делает шаблон «умным» — он не просто показывает поля, а считает суммы, скидки и НДС.

Переменные шапки документа

Поля шапки читаются напрямую из объекта o. Набор зависит от типа документа, но базовые переменные общие:

Через точку можно спускаться глубже — например, к реквизитам организации или банковским данным, если они заведены в карточке.

Цикл по позициям документа

Список товаров строится циклом. Открывающая метка ставится в пустой строке над строкой-образцом, закрывающая — под ней:

<jx:forEach items="${o.positions}" var="row">

Внутри цикла обращайтесь к текущей строке через row:

• ${row.assortment.name} — наименование товара;
• ${row.quantity} — количество;
• ${row.price} — цена;
• ${row.sum} — сумма по строке.

Дополнительные поля

Собственные атрибуты документа (например, «Срок оплаты» или «Ответственный менеджер») выводятся через функцию formatter.findAttribute. Общая структура формулы такая:

${formatter.findAttribute(o, "Название поля").value}

Где важно:

• o — текущий документ, из которого берётся поле;
• «Название поля» — точное имя дополнительного поля с учётом регистра и пробелов;
• .value — само значение атрибута.

Форматирование чисел и дат

Внешний вид значений задаётся двумя способами — форматом ячейки Excel и функциями форматирования jXLS.

• Даты размещайте в отдельных ячейках с форматом «Дата» — тогда ${o.moment} выведется как дата, а не как техническое число.
• Числа и валюта оформляются функцией formatter.format, например для разбивки рублей и копеек.
• Сложные вычисления над коллекциями делаются через formatter.evaluateJexl — небольшой скрипт прямо в формуле.

Простую арифметику (сумма со скидкой, выделение НДС) удобно считать штатными формулами Excel поверх подставленных значений.

Сумма прописью и спецформулы

Для суммы прописью в МойСклад есть специальная конструкция с тегами [SPELL]...[/SPELL]. Внутрь помещается ссылка на нужное числовое значение — итоговую сумму документа. Так в бланке появляется строка вида «Десять тысяч рублей 00 копеек» без ручного ввода.

Тем же приёмом выводят прописью значения дополнительных числовых полей. Главное — чтобы поле имело тип «Число» или «Целое число», иначе конструкция не сработает.

Итог

Формулы шаблона МойСклад держатся на нескольких сущностях: объект документа o, строка позиций row внутри цикла jx:forEach, функция formatter.findAttribute для доп.полей и теги [SPELL] для суммы прописью. Освоив их, вы соберёте практически любой бланк.

Если формулы упираются в нестандартные расчёты — многоуровневые скидки, особый расчёт НДС, условные блоки — мы настраиваем такие шаблоны в рамках работ по функционалу и поддержке МойСклад, чтобы документы считались верно и не ломались со временем.