waPlugin

Базовый класс плагина приложения

Содержание...

Класс waPlugin используется для создания плагинов к приложениям Webasyst. Основной класс плагина должен быть унаследован от базового класса waPlugin или его наследника, например, от класса shopPlugin в приложении Shop-Script.

Методы

  • addCss

    Добавляет URL CSS-файла в список файлов, возвращаемых методом {$wa->css()}.

  • addJs

    Добавляет URL JavaScript-файла в список файлов, возвращаемых методом {$wa->js()}.

  • getId

    Возвращает ID плагина.

  • getInfo

    Возвращает информацию о плагине.

  • getName

    Возвращает локализованное название плагина.

  • getPluginStaticUrl

    Возвращает URL корневой директории плагина.

  • getRights

    Возвращает информацию об уровне доступа текущего пользователя к функциям бекенда плагина.

  • getSettings

    Возвращает информацию о настройках плагина.

  • getSettingsDisclaimerHtml

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

  • saveSettings

    Сохраняет настройки плагина.

  • getVersion

    Возвращает номер версии плагина.

protected function addCss ($url, $is_plugin = true)

Добавляет URL CSS-файла в список файлов, возвращаемых методом {$wa->css()}.

Параметры

  • $url

    URL CSS-файла.

    Если значение параметра $is_plugin эквивалентно true, то в параметре $url нужно передать относительный URL CSS-файла с учетом URL корневой директории плагина.

    Если в URL отсутствуют GET-параметры, то к URL добавляется пустой GET-параметр с именем, состоящим из номера версии плагина. Если включен режим отладки, то к URL файла в этом случае дополнительно добавляется точка и текущая метка времени. Это полезно для автоматического обновления CSS-файлов в кеше браузера во время разработки плагина.

  • $is_plugin

    Флаг, обозначающий, передан ли в параметре $url относительный URL CSS-файла с учетом URL корневой директории плагина. В противном случае URL считается абсолютным или указанным без учета корневой директории плагина.

Пример

//относительно корневой директории плагина
$this->addCss('css/backend.css');
//абсолютный
$this->addCss(wa()->getConfig()->getRootUrl(true).'wa-content/css/wa/design.css', false);

protected function addJs ($url, $is_plugin = true)

Добавляет URL JavaScript-файла в список файлов, возвращаемых методом {$wa->js()}.

Параметры

  • $url

    URL JavaScript-файла.

    Если значение параметра $is_plugin эквивалентно true, то в параметре $url нужно передать относительный URL JavaScript-файла с учетом URL корневой директории плагина.

    Если в URL отсутствуют GET-параметры с символом ?, то к URL добавляется пустой GET-параметр с именем, состоящим из номера версии плагина. Если включен режим отладки, то к URL файла в этом случае дополнительно добавляется точка и текущая метка времени. Это полезно для автоматического обновления JavaScript-файлов в кеше браузера во время разработки плагина.

  • $is_plugin

    Флаг, обозначающий, передан ли в параметре $url относительный URL JavaScript-файла с учетом URL корневой директории плагина. В противном случае URL считается абсолютным или указанным без учета корневой директории плагина.

Пример

//относительно корневой директории плагина
$this->addJs('js/backend.js');
//абсолютный
$this->addJs(wa()->getConfig()->getRootUrl(true).'wa-content/js/jquery-wa/editor.js', false);

public function getId()

Возвращает ID плагина.

Пример

$plugin_id = wa('someapp')->getPlugin('myplugin')->getId();

public function getInfo()

Возвращает информацию о плагине: содержимое его конфигурационного файла plugin.php.

Пример

wa('shop')->getPlugin('migrate')->getInfo();

Результат

[
    'name' => 'Переход на Shop-Script',
    'description' => 'Перенос данных в Shop-Script из других CMS для интернет-магазинов',
    'img' => 'wa-apps/shop/plugins/migrate/img/migrate.png',
    'vendor' => 'webasyst',
    'version' => '2.3.0',
    'importexport' => true,
    'handlers' => [
        'backend_welcome' => 'backendWelcomeHandler',
    ],
    'id' => 'migrate',
    'app_id' => 'shop',
    'build' => 1732284507,
]

public function getName()

Возвращает локализованное название плагина.

Пример

$plugin_name = wa('someapp')->getPlugin('myplugin')->getName();

public function getPluginStaticUrl ($absolute = false)

Возвращает URL корневой директории плагина.

Параметры

  • $absolute

    Флаг, требующий вернуть абсолютный URL. По умолчанию метод возвращает относительный URL.

Пример

//относительный
$plugin_url = wa('someapp')->getPlugin('myplugin')->getPluginStaticUrl();
//абсолютный
$plugin_url = wa('someapp')->getPlugin('myplugin')->getPluginStaticUrl(true);

Результат

'/wa-apps/someapp/plugins/myplugin/'
'https://mydomain.ru/wa-apps/someapp/plugins/myplugin/'

public function getRights ($name = '', $assoc = true)

Возвращает информацию об уровне доступа текущего пользователя к функциям бекенда плагина.

Параметры

  • $name

    Идентификатор уровня доступа. Для настроек прав доступа с типом list в конце идентификатора нужно добавить точку и символ «%», чтобы получить массив выбранных значений. Структура массива, возвращаемого методом, в этом случае зависит от значения параметра $assoc.

  • $assoc

    Флаг, с помощью которого можно выбрать структуру возвращаемого массива выбранных значений настройки прав доступа с типом list:

    • true (значение по умолчанию): в качестве ключей массива используются идентификаторы выбранных элементов (флажков) настройки права доступа, включённых для данного пользователя, а в качестве значений массива — число 1.
    • false: ключи массива нумеруются автоматически начиная с 0, а в качестве значений используются идентификаторы выбранных элементов настройки права доступа.

Пример

// в обработчике хука 'rights.config'
$config->addItem('plugin.myplugin.checkbox_setting', _wp('Can do something'));
$config->addItem('plugin.myplugin.groupbox_setting', _wp('Can do the following'), 'list', [
    'items' => [
        'id1' => 'option 1',
        'id2' => 'option 2',
    ],
]);

// в коде, где нужна проверка прав доступа
$plugin = wa('someapp')->getPlugin('myplugin');

if ($plugin->getRights('checkbox_setting')) {
    // у пользователя включена настройка доступа с ключом 'checkbox_setting'
}

$enabled_groupbox_rights_options = $plugin->getRights('groupbox_setting.%', false);

if (in_array('id1', $enabled_groupbox_rights_options)) {
    // пользователь имеет доступ к функции 'option 1'
}

public function getSettings ($name = null)

Возвращает информацию о настройках плагина, описанных в конфигурационном файле settings.php.

Параметры

  • $name

    Идентификатор настройки, значение которой нужно вернуть. Если не указать идентификатор (поведение по умолчанию), то метод вернет информацию обо всех настройках плагина.

Пример

//все настройки
wa('someapp')->getPlugin('myplugin')->getSettings()
//одна настройка
wa('someapp')->getPlugin('myplugin')->getSettings('some_setting')

public function getSettingsDisclaimerHtml()

Позволяет показывать произвольное содержимое в бекенде вместо отсутствующего интерфейса настроек. Должен быть при необходимости переопределён в основном классе плагина.

Пример

public function getSettingsDisclaimerHtml()
{
    return '<!-- Свой HTML-/JavaScript-код -->';
}

public function saveSettings ($settings = [])

Сохраняет настройки плагина.

Параметры

  • $settings

    Массив настроек, ключи элементов которого соответствуют идентификаторам полей настроек плагина, описанных в его конфигурационном файле settings.php.

Пример

wa('someapp')->getPlugin('myplugin')->saveSettings([
    'some_setting' => '...',    // какое-то значение
    'another_setting' => '...', // какое-то значение
])

public function getVersion()

Возвращает номер версии плагина. Информация о версии извлекается из конфигурационного файла plugin.php. Если в этом файле есть значение с ключом 'build', то к номеру версии добавляется точка со значением этого параметра.

Пример

$plugin_version = wa('someapp')->getPlugin('myplugin')->getVersion();

Результат

//без 'build'
1.2.4
//с 'build'
1.2.4.382