Модульные скрипты

Модульный скрипт — основной строительный блок платформы Melbis. Каждый модуль решает одну изолированную задачу: формирует меню каталога, выводит карточку товара, обрабатывает корзину, выполняет фоновую задачу. Из таких блоков складывается весь сайт.

Работа с модулями в IDE

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

При открытии модуля в редакторе его интерфейс состоит из трёх частей:

Структура PHP-файла

Типовой модуль выглядит так:

<?php
/**
 * Function MELBIS_CATALOGE
 **/
function MELBIS_CATALOGE($mVars)
{
    // Создать указатель шаблонизатора
    $tpl = MELBIS()->TplCreate();

    // Получить данные из БД
    $command = "SELECT id, name
                  FROM {DBNICK}_topic
                 WHERE no_visible = 0
              ORDER BY absindex";
    $menu = MELBIS()->SqlSelect(__LINE__, $command);

    // Передать данные в шаблонизатор
    MELBIS()->TplAssign($tpl, 'MENU', $menu);

    // Вернуть результат
    return MELBIS()->TplFinal($tpl, 'main');
}

Главная функция — единственная обязательная часть модуля. Её имя совпадает с именем файла в верхнем регистре. Парсер вызывает именно её, передавая входные параметры в виде массива $mVars.

Внутри модуля может быть любое количество вспомогательных функций — они именуются с префиксом главной функции (см. раздел «Принятые обозначения»).

Рабочий цикл модуля

Большинство модулей следуют одному и тому же паттерну:

1. Создать указатель шаблонизатора:

$tpl = MELBIS()->TplCreate();

2. Получить данные из базы данных методами MELBIS()->Sql*:

// Вернуть плоский массив одной записи
$topic = MELBIS()->SqlSelectFlat(__LINE__, $command, $params);

// Вернуть массив записей
$menu = MELBIS()->SqlSelect(__LINE__, $command, $params);

// Вернуть массив с индексацией по ключу
$image = MELBIS()->SqlSelectEnumFlat(__LINE__, $command, 'id', $id, $params);

// Вернуть страницу записей и общее число строк
$goods = MELBIS()->SqlSelectLimit(__LINE__, $command, $offset, $limit, $params);

Постраничный вывод, запись данных, транзакции и блокировки таблиц описаны в разделе «Работа с базой данных».

3. Передать данные в шаблонизатор методами MELBIS()->Tpl*:

// Передать одно значение
MELBIS()->TplAssign($tpl, 'TITLE', $topic['name']);

// Передать массив целиком
MELBIS()->TplAssign($tpl, $topic);

// Распарсить шаблон и поместить результат в переменную
MELBIS()->TplParse($tpl, 'CONTENT', 'page_index');

4. Вернуть результат — финальный парсинг главного шаблона:

return MELBIS()->TplFinal($tpl, 'main');

Полный перечень методов Sql* и Tpl* описан в соответствующих разделах документации.

Входные параметры

Параметры поступают в модуль через массив $mVars. Способ формирования массива зависит от того, как был вызван модуль.

Если модуль вызван как входная точка (через MELBIS()->Run()), параметры передаются из корневого скрипта явно:

// В index.php:
$entry_param = [serialize($_GET), serialize($_POST)];
MELBIS()->Run('melbis_base_page', $entry_param);

В модуле объявлено get: serial, post: serial — и внутри функции:

$id = (int) ( $mVars['get']['topic_id'] ?? 0 );

Если модуль вызван из шаблона, параметры передаются прямо в теге вызова — позиционно, через запятую:

{MELBIS:melbis_store_image([ID],kDefault)}
{MELBIS:melbis_store_random(8)}
{MELBIS:melbis_cataloge_sub(,,[ID])}

Значения переменных подставляются в квадратных скобках — [ID], а не {ID}. Аргументы разбираются по запятой и по закрывающей скобке, поэтому любое «грязное» значение — название с запятой, текст с кавычкой, сериализованный массив — при подстановке через {ID} разорвёт список аргументов и модуль получит мусор. Квадратные скобки прогоняют значение через urlencode, а парсер на приёме делает парный urldecode, так что содержимое доезжает целиком и в любом виде. Правило действует и для переменных текущей строки цикла:

{#GOODS}
    {MELBIS:melbis_store_card([VAR:LANG],[ID],[PRIOR])}
{GOODS#}

Литералы (kDefault, 8) пишутся как есть — они не переменные, кодировать нечего.

В модуле должны быть объявлены соответствующие параметры, например id: int, key: str, и внутри функции:

$id  = $mVars['id'];
$key = $mVars['key'];

Типы параметров объявляются в поле над редактором в IDE:

Тип Описание
int Целое число
float Число с плавающей точкой
bool Булево значение
str Строка
fix Фиксированный набор значений; первое — по умолчанию. Пример: mode: fix=list\|grid
serial Сериализованный массив PHP (для передачи $_GET/$_POST). При пустом или некорректном значении вернётся [] — проверять is_array в модуле не нужно

Способы вызова модуля

Из шаблона — основной и безопасный способ. Парсер встречает тег {MELBIS:имя_модуля(...)} в HTML-шаблоне, запускает модуль и подставляет его HTML-результат на место тега. Доступен для любого модуля без ограничений.

Как входная точка — вызов через MELBIS()->Run() в корневом скрипте. URL при этом может быть любым — главный критерий именно вызов через Run. Чтобы разрешить такой вызов, в правой панели IDE необходимо включить опцию «Модуль входной точки». Без этого флага парсер откажется запускать модуль напрямую. Входными точками, как правило, являются модули-роутеры страниц, обработчики форм и cron-задачи.

Вложенность модулей

Фрагмент HTML, который вернул модуль, может содержать теги вызова других модулей — и так до любой глубины: парсер обрабатывает всю цепочку сам. Разбор на примере страницы демонстрационного магазина — в разделе «Архитектура витрины».

Библиотеки и таблицы

В правой панели IDE отображаются все доступные библиотечные модули (inc). Чтобы подключить библиотеку, достаточно поставить галочку — парсер автоматически загрузит её перед запуском текущего модуля, и все её функции станут доступны.

На вкладке «Таблицы» отображаются два списка: - Левый — таблицы БД, к которым напрямую обращается текущий модуль. Разработчик отмечает нужные таблицы. - Правый — таблицы от подключённых библиотек (только для информации, изменить нельзя).

Эти данные используются системой кеширования: когда данные в отслеживаемой таблице меняются, платформа знает, кеш каких модулей нужно сбросить. Подробнее — в разделе «Кеширование».

Служебные методы

Помимо работы с шаблонами и базой данных модулю время от времени нужны служебные вызовы платформы — имя текущего модуля, вызов собственной функции, путь к загруженному файлу. Они собраны в разделе «Служебные методы».