Plugins’ helpers for templates

How to safely call plugins’ code in Smarty templates

Contents...
Available as of Webasyst version 1.14.11.

Apps’ plugins can have their own helpers for the use in templates, similar to apps’ helpers. Helpers are used to add dynamic content to various templates such as design templates or email notifications templates.

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

In this example, method helper() of a plugin with the identifier my is called, which has been developed for an app with the identifier someapp.

How to create helpers

  1. Create a PHP class within a plugin, which must extend system class waPluginViewHelper. For example, someappMyPluginViewHelper.
  2. Add public methods to that class, which you want to call as helpers in templates.
Example
class someappMyPluginViewHelper extends waPluginViewHelper
 {
    public function helperOne()
    {
        ...
    }
    
    public function helperTwo()
    {
        ...
    }
 
    ...
 }

Better than static methods

Instead of helpers, you can use simple static methods of a plugin’s PHP classes.

Example
{someappMyPlugin::methodName()}

Even though such static methods are simpler to create (all you need is to declare a public static method in any PHP class within a plugin), they have some drawbacks as compared to helpers:

  1. If a plugin is disabled in the framework configuration then the call of a static method will continue to work without any changes. It is less convenient for users to temporarily disable such plugin calls in templates.
  2. If a user uninstalls the plugin then an error will occur during the processing of a template.
  3. If a method was not available in the very first version of a plugin then you need to use additional checks for the current plugin version when you want to call that method in a template.

We recommend you to use special helpers rather than static methods to avoid such hassle.

Methods of system class waPluginViewHelper

We recommend that your plugin helper classes extend this system class to ensure that they have the full functionality described on this page.

public function version()

If a plugin is installed and enabled in the framework configuration then the call of this method returns the plugin’s version number as string.

Example
{$wa->someapp->myPlugin->version()}
Result
'1.0.0'

If a plugin is disabled then this method returns an empty string.

protected function plugin()

The call of this method within an helper class returns a cached instance of the main plugin class.

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

Handling calls of of non-existent app helpers

Suppose there is a call of an app helper in some template while no such helper is defined within the corresponding app:

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

You can handle such calls of non-existent app helper calls in your plugins; e.g., to return some content to a template. If more than one plugin return non-empty content in this case then only the first of such results is returned to a template.

How to implement

  1. Subscribe to the view_helper_call event in the plugin’s configuration file plugin.php.
  2. Return the desired content in the event handler.
Example
class someappMyPlugin extends waPlugin
{
    public function viewHelperCall($params = [])
    {
        return sprintf(_wp('Call of an unknown method with parameters "%s"'), var_export($params, true));
    }
 }

Reading of non-existent properties of an app helper class

Similar to the calls of non-existent helper methods, you may handle attempts to read non-existent properties of an app helper class in templates:

{$wa->someapp->test}

If a plugin has subscribed for attempts to read such non-existent properties then it can return some value in this case. If multiple plugins return a non-empty value on such an attempt then only the first returned value is passed on to the template.

How to implement

  1. Subscribe to the view_helper_read event in the plugin’s configuration file plugin.php.
  2. Return the desired content in the event handler.
Example
class someappMyPlugin extends waPlugin
{
    public function viewHelperRead($params = [])
    {
        return sprintf(_wp('Attempt to read an unknown property "%s"'), $params['name']);
    }
}