Создание плагинов для Shop-Script

Плагины используются для добавления в интернет-магазин дополнительной функциональности без изменения исходного кода приложения. Каждый плагин хранится в отдельной поддиректории внутри wa-apps/shop/plugins/.

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

обработка событий
обработка запросов URL
обработка вызовов из командной строки (например, с помощью планировщика cron)

Основные принципы создания и работы плагинов описаны в документации разработчика Webasyst. Далее более подробно описаны особенности, относящиеся к разработке плагинов для приложения Shop-Script.

1. Обработка событий

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

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

У каждого хука есть собственный идентификатор (имя) — с его помощью можно для каждого плагина однозначно указать, в каком месте и в какой момент этот плагин должен сработать. Список хуков, которые должен обрабатывать плагин, описывается в файле lib/config/plugin.php в поддиректории плагина. В этом файле для каждого хука указывается имя метода, который должен быть вызван при наступлении соответствующего события. Если какое-то событие не должно обрабатываться плагином, то его не нужно указывать в файле lib/config/plugin.php. Методы, имена которых указываются в файле lib/config/plugin.php, должны быть описаны в основном классе плагина lib/shop[Plugin_id].plugin.php, расположенного в директории плагина.

Пример файла wa-apps/shop/plugins/someplugin/lib/config/plugin.php:

<?php
return array(
    'name' => 'НАЗВАНИЕ ПЛАГИНА',
    'version' => '1.0',
    // соответствие событие => обработчик (название метода в классе плагина)
    'handlers' => array(
      'frontend_homepage' => 'frontendHomepage',
    ),
    // остальные параметры — необязательные
    'img' => 'img/plugin.png', // иконка (будет показываться в Инсталлере) размером 16x16
    'description' => 'ОПИСАНИЕ ПЛАГИНА'
);

В выделенном выше фрагменте для события с хуком frontend_homepage определяется в качестве обработчика метод frontendHomepage. Название хука «frontend_homepage» должно быть именно таким, потому что в таком виде хук определен в исходном коде Shop-Script. Название же метода «frontendHomepage» может быть произвольным — к примеру, метод может называться «homepageEventHandler» — на усмотрение разработчика. Необходимо лишь следить за тем, чтобы указанное здесь имя метода соответствовало содержимому основного класса плагина. В данном примере исходный код этого класса может иметь следующий вид:

<?php
class shopSomepluginPlugin extends waPlugin
{
    public function frontendHomepage ($params)  //вместо frontendHomepage имя метода может быть другим — в зависимости от того, как оно указано в конфигурационном файле плагина lib/config/plugin.php
    {
        // исходный код метода-обработчика
        return ...;    //возврат значения необязателен; например, плагин может лишь сохранить некоторую информацию в базу данных при наступлении какого-то события
    }
    // ... остальные обработчики
}

Если метод-обработчик возвращает значение, то это значение будет включено в HTML-код страницы, при запросе которой сработал плагин — в том месте, в котором находится код подключения хука. Каждый хук может предоставлять одно или несколько мест отображения возвращаемого значения на одной странице. Например, хук frontend_homepage предоставляет только одно такое место — с помощью следующего фрагмента в шаблоне home.html темы дизайна:

<!-- plugin hook: 'frontend_homepage' -->
{* @event frontend_homepage.%plugin_id% *}
{foreach $frontend_homepage as $_}{$_}{/foreach}

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

Другие хуки могут предоставлять несколько мест для отображения результата. Например, хук frontend_product (в шаблоне product.html):

<!-- plugin hook: 'frontend_product.cart' -->
{* @event frontend_product.%plugin_id%.cart *}
{foreach $frontend_product as $_}{$_.cart}{/foreach}

<!-- plugin hook: 'frontend_product.block_aux' -->
{* @event frontend_product.%plugin_id%.block_aux *}
{if !empty($frontend_product)}
<div class="aux">
    {foreach $frontend_product as $_}{$_.block_aux}{/foreach}    
</div>
{/if}

<!-- plugin hook: 'frontend_product.menu' -->
{* @event frontend_product.%plugin_id%.menu *}
{foreach $frontend_product as $_}{$_.menu}{/foreach}

<!-- plugin hook: 'frontend_product.block' -->
{* @event frontend_product.%plugin_id%.block *}
{foreach $frontend_product as $_}{$_.block}{/foreach}

Когда хук предоставляет только одно место отображения результата, метод-обработчик должен вернуть простую строку.

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

<?php
class shopSomepluginPlugin extends waPlugin
{
    public function frontendHomepage ($params)
    {
        ...
        return array(
            'cart'      => 'value1',
            'block_aux' => 'value2',
            'menu'      => 'value3',
            'block'     => 'value4',
        );
    }
}

Значения, обозначенные в этом примере как 'value1', 'value2', 'value3', 'value4', будут включены в HTML-код страницы в тех местах, где в шаблоне (в данном случае product.html) расположены соответствующие им точки подключения.

2. Обработка запросов URL

Маршрутизация запросов

Независимо от обработки событий плагин также может обрабатывать запросы к произвольным URL, соответствующим определенному шаблону (маске) наподобие того, как фреймворк обрабатывает запросы пользователей в соответствии с правилами маршрутизации, настроенными с помощью приложения «Сайт». Аналогично тому, как правила маршрутизации фреймворка хранятся в конфигурационном файле wa-config/routing.php, правила маршрутизации плагина следует указывать в файле lib/config/routing.php в поддиректории плагина.

Ниже показан формат файла lib/config/routing.php:

<?php
return array(
    'path/<name1>/<name2>/' => 'module/action',
    '...' => 'module/action',
    /* другие правила маршрутизации */
);

В качестве ключа элемента массива (вместо path/<name1>/<name2>/ в этом примере) нужно указать маску URL, которые должны обрабатываться плагином. Динамические фрагменты URL должны быть записаны в виде <name1>, <name2> и т. д. Значения, соответствующие этим фрагментам, доступны в экшене-обработчике с помощью метода waRequest::param($name).

Порядок следования и количество динамических фрагментов в маске URL могут быть произвольными и необязательно должны совпадать с тем, как они показаны в примере!

Например, если маска URL имеет вид extra/<section_id>/<item_id>/, то в коде экшена значения, содержащиеся вместо <section_id> и <item_id>, можно получить с помощью вызова waRequest::param('section_id') и waRequest::param('item_id').

Маска URL должна быть относительной, т. е. не должна начинаться с косой черты /. URL, при запросе которых должен вызываться исходный код плагина, отсчитываются относительно адреса поселения интернет-магазина. Например, если для магазина настроено поселение по адресу yourdomain.ru/shop/, то в приведенном выше примере плагин будет обрабатывать адреса вида yourdomain.ru/shop/extra/some/value/, где «some» будет соответствовать фрагменту <section_id>, а «value» — фрагменту <item_id> (согласно правилу маршрутизации extra/<section_id>/<item_id>/).

Вместо элементов module и action в значении элемента массива нужно указать следующие значения:

module — идентификатор модуля, экшен которого должен обрабатывать запросы, направленные на адреса, соответствующие указанной маске
action — идентификатор экшена для обработки запросов; экшены для обработки запросов следует оформлять так же, как и для приложений (подробнее об оформлении файлов экшенов)

Пример файла lib/config/routing.php:

<?php
return array(
    'extra/<section_id>/<item_id>/' => 'frontend/extra',
);

Исходный код экшена с идентификатором extra, указанным в таком конфигурационном файле, может содержаться:

в файле wa-apps/shop/plugins/someplugin/lib/actions/frontend/shopSomepluginPluginFrontend.actions.php в виде метода actionExtra() либо
в файле wa-apps/shop/plugins/someplugin/lib/actions/frontend/shopSomepluginPluginFrontendExtra.action.php в виде метода execute().

Запросы к бекенду

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

yourdomain.ru/webasyst/shop/?plugin=someplugin — вызов экшена с идентификатором extra модуля backend

3. Обработка вызовов из командной строки

Вызовы из командной строки сервера прежде всего могут быть полезны для работы планировщика (cron) либо для отладки программного кода. О создании обработчиков таких вызовов читайте в статье о создании плагинов в документации разработчика Webasyst.