Модификаторы

Вызываются через символ пайпа |. Параметры передаются через двоеточие :. Модификаторы можно выстраивать в цепочку: {VAR|mod1|mod2:param}.

⚠️ Регистр в параметрах-ссылках на переменные: Если параметр модификатора — это имя переменной или ключ поля, а не статичный текст (как в calc, print, array_item), парсер ищет его строго в том регистре, в котором он записан — автоматического приведения к верхнему регистру не происходит. Все ключи данных в шаблонизаторе (включая вложенные массивы, переданные через TplAssign, и глобальный массив) хранятся в UPPERCASE, поэтому и такие параметры нужно писать заглавными буквами: {ROW|calc:PRICE*2}, а не {ROW|calc:price*2} — иначе имя не будет найдено.

Текст и HTML

Порядок важен: tag не экранирует содержимое значения — если оно пришло от пользователя (не доверенный HTML), сначала примените |html, и только потом |tag: {USER_COMMENT|html|tag:span,comment}.

Форматированный вывод

Числа и Математика

Даты

Мультиязычные форматы (intl)

Эти модификаторы автоматически адаптируют форматы вывода под текущий язык страницы (MELBIS()->LanguageSet('en')), используя библиотеку ICU. Идеально для проектов с en, ru, ua и т.д.

Массивы и JSON

Если путь у array_item/json_item указывает не на конечное скалярное значение, а на вложенный массив/объект — результатом будет массив; скомбинируйте с |join, если нужна строка.

Системные функции

Вызов штатных функций PHP

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

Экранирование спецсимволов в параметрах модификаторов

Поскольку запятая, двоеточие, |, {, } и пробел используются самим парсером как служебные разделители, передать их буквально в параметр (например, разделитель в split или значение в style у tag) можно через специальные подстановки:

Подстановка Символ
_nl_ перевод строки
_sp_ пробел
_cl_ :
_cm_ ,
_pl_ |
_bo_ {
_bc_ }

Например, {TEXT|split:_cm_,1} разобьёт строку по буквенной запятой (а не по служебной), а {VAR|tag:span,,font-family: Arial_cm_ sans-serif} вставит настоящую запятую в значение style.

Как передаются аргументы:

Синтаксис: {ПЕРЕМЕННАЯ|имя_функции:параметр2,параметр3}

Примеры использования:

Практически важный случай, который из общего правила не очевиден: {QUERY|rawurlencode} — кодирование для сегмента пути, в отличие от [QUERY] (см. «Синтаксис шаблонов»).

Передача массива в аргумент вызова модуля. Сериализуйте массив в PHP, а в шаблон передавайте готовую строку — модуль-приёмник объявит параметр типа serial, и парсер сам развернёт её обратно в массив:

$filters_line = serialize($filters);
MELBIS()->TplAssign($tpl, 'FILTERS', $filters_line);
{MELBIS:goods_navi([TOTAL],[PAGE_NUM],[FILTERS])}

Квадратные скобки обязательны: сериализованная строка полна кавычек, двоеточий и фигурных скобок, и без urlencode разбор списка аргументов сломается. Обратный urldecode парсер делает сам при разборе serial-параметра.

Сериализуйте именно в PHP, а не модификатором в шаблоне: TplAssign приводит ключи любого массива к верхнему регистру, поэтому serialize внутри тега сохранит ключи как ORDER, PRICE, а не исходные order, price.

⚠️ Регистр в параметрах, если они — ключи массива: У штатных PHP-функций параметры передаются буквально, как вы их написали — парсер их не ищет в контексте и не приводит к верхнему регистру (в отличие от calc/print/array_item, где параметр — это имя переменной, которую движок сам находит в UPPERCASE-контексте). Если параметр функции — это ключ, по которому она сама лезет внутрь строки массива (как второй аргумент array_column), он должен совпадать с реальным регистром ключей ваших данных, а они, пройдя через TplAssign, всегда в UPPERCASE:

{STORE|array_column:id|join}   — не сработает, вернёт пустую строку: array_column ищет ключ 'id',
                                  а в строках STORE ключ называется 'ID'
{STORE|array_column:ID|join}   — сработает: регистр параметра совпадает с реальным ключом

Это не то же самое правило, что регистр параметров у calc/print/array_item (там причина — поиск переменной движком), просто оба случая на практике требуют писать параметр заглавными буквами.

Вызов собственных функций (Модульные Коллбэки)

Для сложной бизнес-логики (например, перевод строк, мультивалютность, специфическое форматирование) вы можете регистрировать собственные функции. Они вызываются через модификатор, начинающийся со знака $ (например, |$trans).

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

1. Регистрация функций в PHP

У вас есть два уровня регистрации: глобальный и локальный (уровень конкретного модуля).

MELBIS()->DefineCallback('trans', 'MELBIS_INC_translate', ['from' => 'en']);
MELBIS()->UnitCallbackCustom('trans', 'MELBIS_INC_translate', ['from' => 'ru']);

2. Вызов в HTML-шаблоне

В шаблоне вы указываете алиас (со знаком $) и, при необходимости, через запятую перечисляете дополнительные аргументы. Аргументами могут выступать как ключи из текущего массива данных, так и статичные строки или числа.

Синтаксис: {ОСНОВНАЯ_ПЕРЕМЕННАЯ|$алиас:АРГ_1,АРГ_2}

Пример: {PRICE|$discount:GROUP_ID,10,USD} (где PRICE и GROUP_ID — переменные из базы данных, а 10 и USD — статичный текст, переданный прямо из верстки).

3. Как формируется массив данных (Payload) для функции

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

Структура массива на примере {PRICE|$discount:GROUP_ID,10,USD}:

[
    // === Универсальные числовые индексы ===
    0 => 1500,         // Индекс 0 ВСЕГДА содержит главное значение тега {PRICE}
    1 => 5,            // Значение переменной GROUP_ID (нашлось в текущих данных)
    2 => '10',         // Статичная строка (так как ключа '10' нет в данных)
    3 => 'USD',        // Статичная строка

    // === Строковые ключи ===
    'price' => 1500,   // Дубликат главного значения по имени тега
    'group_id' => 5,
    'usd' => 'USD',
    'from' => 'ru'     // Подтянулось из дефолтных настроек PHP (см. ниже)
]

(💡 Примечание: парсер умно защищает числовые индексы — статичный аргумент 10 не создаст строковый ключ '10', чтобы не сломать нумерацию).

🔥 Наложение приоритетов для строковых ключей (от низшего к высшему): Сборка ассоциативной части массива происходит с наложением приоритетов:

  1. (Низший) Дефолтные системные параметры из PHP: Берутся базовые настройки, указанные при регистрации. Пример: ['from' => 'en', 'color' => 'black']
  2. (Средний) Главная переменная из шаблона: Парсер берет имя переменной до знака | и помещает её в массив. Пример: ['from' => 'en', 'title' => 'Значение']
  3. (Наивысший) Дополнительные ключи из шаблона: Если верстальщик явно передал ключ (например, FROM), который совпадает с дефолтной настройкой PHP, значение из HTML-шаблона полностью перезапишет дефолтное.

Таким образом, современные функции могут просто обращаться к $mParam[0], $mParam[1], не привязываясь к тому, как переменная называлась в шаблоне, а сложные функции могут управлять бизнес-логикой через переопределение строковых ключей.