Шорткоды, хуки и обработчики

В Moguta.CMS внедрена система хуков или попросту говоря событий. Благодаря хукам можно повесить собственный обработчик из плагинана на стандартную функцию из файлов библиотек, контролеров и моделей движка и изменить ее стандартное поведение. Hook в переводе означает крючок и с помощью таких крючков появляется возможность встраивать в код ядра системы код плагинов. Таким образом можно создавать новый дополнительный функционал движка не изменяя код его ядра.

Как это работает. Представим что пользователь добавляет в корзину товар. В этот момент срабатывает определенная функция в ядре движка, в которой объявлен хук, а это значит, что можно обработать это событие в собственном плагине и например, к данному товару добавить в корзину еще один подарочный товар.

Таким же образом можно влиять на любые другие события движка.

Примеры системных событий

• mg_start – срабатывает перед формированием страницы движком;
• mg_end – срабатывает после формирования страницы движком;
• models_order_addorder – срабатывает при создании нового заказа;
• models_order_updateorder – срабатывает при изменении заказа.

Вот полный перечень доступыных событий.

Шорткоды

Шорткоды ( [short-code] - короткий код ) – это короткие символьные записи, обрамленные квадратными скобками.
С помощью плагинов можно регистрировать обработчики хуков для дальнейшей обработки нужных шорткодов. В том месте HTML кода страницы где вставлен шорткод с зарегистрированным обработчиком в плагине, будет создан хук или другими словами событие, которое можно обрабатывать.

Шорткоды могут выглядеть так:

• [nameplugin]
• [nameplugin attr="1" atr="2"]
• [nameplugin] Текст [/nameplugin]
• [nameplugin attr="1" atr="2"] Текст [/nameplugin]

Добавлять такие вставки можно в любое место верстки страницы: в файлы шаблона, в описание товаров на сайте, в содержание страниц на сайте и любые другие места в HTML коде страницы.

Как зарегистрировать обработчик события для нового шорткода в плагине

Чтобы объявить свой шорткод и назначить ему обработчик нужно в файле плагина index.php выполнить функцию: mgAddShortcode();
Первым параметром функции задается наименование шорткода 'mg-test-shortcode', вторым параметром задается функция 'testHandleShortCode', которая будет обрабатывать шорткод.

mgAddShortcode('mg-test-shortcode', 'testHandleShortCode'); 
function testHandleShortCode($args) {
  echo "Hello world!";
  var_dump($args);
}

Как создать свой хук в методе контроллера или модели

Чтобы повесить обработчик на метод содержащийся в контроллере или моделе, нужно перед возвратом результата объявить хук.
Такая задача редко встречается, поскольку методы и контроллеры разрабатываются в основном официальными разработчиками, но движок позволяет создавать в шаблонах свои доплнительные контроллеры и модели и возможно, в редкиз ситуация придется создавать свои хуки.

Для создания хуков в коде предусмотрена статическая функция MG::createHook(), которая позволяет создает hook, в месте ее вызова следующими способами:

1. MG::createHook('eventname'); - создает событие с хуком 'eventname' в любом месте программного кода движка;
2. MG::createHook('eventname', $args); - создает событие с хуком 'eventname' в любом месте программного кода движка, и передает в обработчик массив данных $args;
3. MG::createHook('eventname', $result, $args); - создает событие перед возвращением результата выполняемой функции. В качестве параметров передается: $result - результат работы выполненной функции и $args - начальные параметры, которые были переданы на момент её вызова.

Подобный третьему типу событий чаще всего используется при возвращении результата работы метода:

class tempCart {
  /**
   * Пример метода с хуком.
   * @return array
   */
  public static function getCart($param) {
    $args = func_get_args();
    $result = array('test','test2');
    return MG::createHook(__CLASS__."_".__FUNCTION__, $result, $args);
  }
}

__CLASS__ ."_". __FUNCTION__ – это строковое название хука, в нижнем регистре, состоящее из имени класса и метода, в котором он создан в данном случае tempCart_getCart
$result – результат работы исходной функции, в данном случае $_SESSION['cart'];
$args – массив входящих параметров в исходную функцию,в данном случае значение параметра $param.

Теперь в плагине в файле index.php можно будет создать свой обработчик newGetCart, перехватить и изменить возвращаемый результат метода getCart() следующим образом:

mgAddAction('tempCart_getCart', 'newGetCart',1,10);

function newGetCart($args){
  print_r($args);   
  return $args['result'];
}