Хелперы плагинов

Доступно начиная с версии Webasyst 1.14.11.

Плагины, разработанные для приложений, могут иметь собственные хелперы для вызова в шаблонах — наподобие хелперов приложений. Хелперы нужны для того, чтобы добавлять динамическое содержимое в шаблоны, например, шаблоны дизайна или email-уведомлений.

Пример

{$wa->someapp->myPlugin->helper()}

В этом примере вызывается метод helper() плагина с идентификатором my, созданного для приложения с идентификатором someapp.

Как создавать хелперы

1. Создайте класс в составе плагина, унаследованный от системного класса waPluginViewHelper. Например, someappMyPluginViewHelper.
2. Опишите в этом классе публичные методы, которые нужно вызывать в шаблонах в качестве хелперов.

Пример

class someappMyPluginViewHelper extends waPluginViewHelper
{
    public function helperOne()
    {
        ...
    }

    public function helperTwo()
    {
        ...
    }

    ...
}

Лучше, чем статические методы

Вместо специальных хелперов можно использовать и просто вызов статических методов PHP-классов плагина.

Пример

{someappMyPlugin::methodName()}

Хотя такие статические методы проще оформлять (достаточно просто добавить публичный статический метод в любой класс плагина), у них есть недостатки по сравнению с хелперами:

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

Используйте хелперы, чтобы не сталкиваться с такими неудобствами.

Методы системного класса waPluginViewHelper

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

public function version()

Если плагин установлен и активирован в конфигурации фреймворка, то вызов этого метода вернёт номер версии плагина в виде строки.

Пример

{$wa->someapp->myPlugin->version()}

Результат

'1.0.0'

Если плагин установлен, но отключён в конфигурации, то этот метод возвращает пустую строку.

protected function plugin()

Вызов этого метода в пределах класса-хелпера вернёт кешируемый экземпляр основного класса плагина.

Пример

public function helper()
{
    $some_setting_value = $this->plugin()->getSettings('setting_name');
    // ...
}

Обработка вызовов несуществующих хелперов приложения

Допустим, в шаблоне вызывается метод-хелпер с именем, которого нет у указанного приложения:

{$wa->someapp->test()}

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

Как реализовать

1. В конфигурационном файле плагина plugin.php подписаться на событие view_helper_call.
2. В обработчике события вернуть строку с нужным содержимым.

Пример

class someappMyPlugin extends waPlugin
{
    public function viewHelperCall($params = [])
    {
        return sprintf(
            _wp('Вызов неизвестного метода с параметрами "%s"'),
            var_export($params, true)
        );
    }
}

Чтение несуществующих свойств класса-хелпера приложения

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

{$wa->someapp->test}

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

Как реализовать

1. В конфигурационном файле плагина plugin.php подписаться на событие view_helper_read.
2. В обработчике события вернуть строку с нужным содержимым.

Пример

class someappMyPlugin extends waPlugin
{
    public function viewHelperRead($params = []) {
        return sprintf(
            _wp('Попытка чтения неизвестного свойства "%s"'),
            $params['name']
        );
    }
}