waPlugin

Base class for app plugins

Contents...

Class waPlugin is used to develop plugins for Webasyst apps. A plugin’s main class must extend base class waPlugin or its descendant; e.g., shopPlugin class in Shop-Script app.

Methods

  • addCss

    Adds a URL of a CSS file to the array returned by method {$wa->css()}.

  • addJs

    Adds a URL of a JavaScript file to the array returned by method {$wa->js()}.

  • getId

    Returns plugin ID.

  • getName

    Returns localized plugin name.

  • getPluginStaticUrl

    Returns plugin’s root directory URL.

  • getRights

    Returns information about user’s access rights to backend functions.

  • getSettings

    Returns plugin settings values.

  • saveSettings

    Saves plugin settings.

  • getVersion

    Returns plugin version number.

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

Adds a URL of a CSS file to the array returned by method {$wa->css()}.

Parameters

  • $url

    A URL of a CSS file.

    If parameter $is_plugin contains a non-empty value, then parameter $url must contain a relative URL of a CSS file within the plugin’s root directory.

    If a URL does not contain GET parameters, then an empty GET parameter is added to it, with the plugin version number as the GET parameter name. If the debug mode is enabled, then a period and the current timestamp value are also added to a URL in this case. It is useful for updating CSS files in the browser cache during the development.

  • $is_plugin

    Whether a relative URL within the plugin’s root directory is being passed in $url parameter. If otherwise, a URL is considered absolute or not relative to the plugin’s root directory.

Example

//relative to plugin’s root directory
$this->addCss('css/backend.css');
//absolute
$this->addCss(wa()->getConfig()->getRootUrl(true).'wa-content/css/wa/design.css', false);

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

Adds a URL of a JavaScript file to the array returned by method {$wa->js()}.

Parameters

  • $url

    A URL of a JavaScript file.

    If parameter $is_plugin contains a non-empty value, then parameter $url must contain a relative URL of a JavaScript file within the plugin’s root directory.

    If a URL does not contain GET parameters, then an empty GET parameter is added to it, with the plugin version number as the GET parameter name. If the debug mode is enabled, then a period and the current timestamp value are also added to a URL in this case. It is useful for updating JavaScript files in the browser cache during the development.

  • $is_plugin

    Whether a relative URL within the plugin’s root directory is being passed in $url parameter. If otherwise, a URL is considered absolute or not relative to the plugin’s root directory.

Example

//relative to plugin’s root directory
$this->addJs('js/backend.js');
//absolute
$this->addJs(wa()->getConfig()->getRootUrl(true).'wa-content/js/jquery-wa/editor.js', false);

public function getId()

Returns plugin ID.

Example

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

public function getName()

Returns localized plugin name.

Example

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

public function getPluginStaticUrl ($absolute = false)

Returns plugin’s root directory URL.

Parameters

  • $absolute

    Whether an absolute URL must be returned. By default, the method returns a relative URL.

Example

//relative
$plugin_url = wa('someapp')->getPlugin('myplugin')->getPluginStaticUrl();
//absolute
$plugin_url = wa('someapp')->getPlugin('myplugin')->getPluginStaticUrl(true);

Result

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

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

Returns information about user’s access rights to backend functions.

Parameters

  • $name

    Access setting ID. For access settings with the list type, add a period and a “%” character to return an array of selected options. The structure of the returned array in this case depends on the value of the $assoc parameter.

  • $assoc

    Flag allowing to select the structure of the returned array of options for access settings with the list type:

    • true (default): array keys are IDs of selected setting options (checkboxes) enabled for the current user and array item values are 1 numbers.
    • false: the method returns a zero-based array of IDs of selected access setting options enabled for the current user.

Example

// in the 'rights.config' hook handler
$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',
    ],
]);

// in the code where access rights must be checked
$plugin = wa('someapp')->getPlugin('myplugin');

if ($plugin->getRights('checkbox_setting')) {
    // access rights setting with the 'checkbox_setting' key is enabled
}

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

if (in_array('id1', $enabled_groupbox_rights_options)) {
    //access rights setting option named 'option 1' is enabled
}

public function getSettings ($name = null)

Returns the values of plugin settings described in configuration file settings.php.

Parameters

  • $name

    String ID of a setting whose value must be returned. If not specified, the method returns the values of all settings.

Example

//all settings’ values
wa('someapp')->getPlugin('myplugin')->getSettings()
//one setting value
wa('someapp')->getPlugin('myplugin')->getSettings('some_setting')

public function saveSettings ($settings = [])

Saves plugin settings.

Parameters

  • $settings

    Array of settings whose keys are names of plugin settings described in its configuration file settings.php.

Example

wa('someapp')->getPlugin('myplugin')->saveSettings([
    'some_setting' => '...',    // some value
    'another_setting' => '...', // some value
])

public function getVersion()

Returns plugin version number. The version number is read from configuration file plugin.php. If the file also contains a 'build' parameter, then a period and a build number are added to the version number.

Example

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

Result

//without a build number
1.2.4
//with a build number
1.2.4.382