Дополнения blocks

Блоки дополнения

Цель применения

Блоки являются рекомендуемой альтернативой применению модификаторов. Цель использования блоков - удобная интеграция HTML блоков дополнений в файлы шаблоны тем или модулей посредством специальных комментариев (тегов).
Тег - это комментарий, содержащий необходимые для блока дополнения параметры локальных переменных шаблона в виде JSON-строки, идентифицирующийся по названию дополнения и ключу блока имеющего следующий вид:

<!-- [extension_p0bc5sa_block1{"param1":"<?= $id ?>"}] -->

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

Настройки блоков дополнения

В настройках дополнения блоки будут доступны в разделе "Инструкция / Блоки". Блоки будут добавлены нумерованным списком, содержащим информацию о названии блока, его описании, код для вставки, а также инструкцию где в файле шаблоне данный код рекомендуется добавить. Зелёным будут помечены файлы шаблона, в которых блоки были найдены. Также есть кнопка "Обновить" для проверки наличия комментариев (тегов) в необходимых файлах шаблонах.

Пример разработки блока

Блоки объявляются в методе init() дополнения сразу после добавления настроек и вызова метода $this->configSettings(), путем вызова метода дополнения blockAdd. Далее устанавливаются параметы блока, посредством вызова вспомогательных методов возвращаемого объекта класса ExtensionBlock. Пример объявления блока:

$this->blockAdd('block1', function($params){
    // Функция обработчик формирующая HTML блока
    return 'HTML';
})
// Название блока можно использовать для краткого описания места на странице
// Например: Профиль пользователя, блок пользователя.
->title($this->langAdmin('Заголовок блока'))
// Указываем файл шаблона приложения в котором следует добавить код блока
// Если файлов несколько, данных вызовов может быть также несколько
->template('/modules/users/tpl/def/profile.php')
// Указываем дополнительные параметры блока (доступные в виде переменных в файле шаблона)
->param('param1', '?$id')
->param('param2', '?$user_id')
// Описываем точное место в файле
// Поддерживается Markdown разметка, в частности однострочный и многострочный код
->integration($this->langAdmin('Подробное описание места интеграции ...'))
// Указываем описание блока
// Также поддерживается Markdown разметка
->description($this->langAdmin('Описание блока'));

$this->blockAdd('block2', array($this, 'blockMethod')) // Метод дополнения
 ->title($this->langAdmin('Заголовок блока №2'))
 ->template('/modules/shops/tpl/def/view.php')
 ->param('shop', '?$shop_id')
 ->description($this->langAdmin('Описание блока №2'));

Опишем подробнее аргументы метода blockAdd('block_key', callable $callback):

  • block_key - ID блока (уникальный ключ в рамках дополнения), допустимые символы: a-z,A-Z,0-9,-,_
  • callback - функция обработчик, отвечающая за отрисовку блока, может быть объявлена непосредственно в самом блоке или публичным методом дополнения.
    Пример подобного метода:
/**
 * Пример метода формирующего HTML код блока дополнения
 * @param array $params параметры блока (указанные при объявлении блока): 'param1', 'param2', ...
 * @return string HTML (или пустая строка)
 */
public function blockMethod($params)
{
    // Формируем HTML шаблон путем подключения файла шаблона дополнения /tpl/template.php
    return $this->view($params, 'template');
}

Параметрами метода $params являются параметры передаваемые в теге посредством JSON-строки. В местах вставки как правило есть данные в виде локальных переменных, которые и необходимы для отрисовки блока на странице. Тег вставляется непосредственно в файл шаблона, объявленный при инициализации блока.

Для того чтобы избежать ошибки в случае отсутствия переменной в файле шаблона при объявлении параметров используется специальный синтаксис, а именно знак ? перед её названием:

param('shop', '?$shop_id')

Таким образом в результирующем коде тега переменная будет иметь следующий вид:

<!-- [extension_p0bc5sa_block1{"shop":"<?= isset($shop_id) ? $shop_id : '' ?>"}] -->