Создание плагинов для 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:

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

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

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

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

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

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

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

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

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

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

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

Например, если маска 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:

Исходный код экшена с идентификатором 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.