Helper Plugins

Helper plugins make it simple for plugin developers to use functionality of other, existing plugins. For example to display a list of wiki pages, there's no need to reinvent the wheel. - Instead use the Pagelist Plugin. Take a look at the list of helper plugins.

Helper plugins can be used from another plugin in a simple manner.

$tag = $this->loadHelper('tag'); // or $this->loadHelper('tag', true);
 
if($tag instanceof PluginInterface) {
    $entries = $tag->tagRefine($entries, $refine);
}

The loadHelper($name, $showmsg = true) is a method inherited by all plugins. It takes two parameters, while the second is optional.

• The first parameter is the name of the wanted helper plugin.
• The second indicates if an error message should be displayed in case loading the helper plugin fails (this message isn't localized and can't be localized currently).

As alternative, you can use the general code for loading plugin components:

You have to use the plugin_load($type, $name) function. It takes two parameters:

• the first is the plugin type,
• and the second the name of the plugin you like to use.

Additionally plugin_isdisabled($name) can be used to check if a plugin is available or not.

if(!plugin_isdisabled('tag')) {
    $tag = plugin_load('helper', 'tag');
    $entries = $tag->tagRefine($entries, $refine);
}

Default DokuWiki reuses instances of its plugins. This can be prevented by adding a isSingleton() function to the plugin class. See instantiating.

For example, the Sqlite helper keeps separate instances for every call.

<?php
use dokuwiki\Extension\Plugin;
 
class helper_plugin_sqlite extends Plugin {
    ...
 
    /**
     * Keep separate instances for every call to keep database connections
     */
    public function isSingleton() {
        return false;
    }
    ...
}

So you can have more database instances:

if(!plugin_isdisabled('sqlite')) {
    $DBInstanceA = plugin_load('helper', 'sqlite');
    if($DBInstanceA) {
        $DBInstanceA->init('test_a', dirname(__FILE__) . '/db/');
    }
 
    $DBInstanceB = plugin_load('helper', 'sqlite');
    ...
}

A Helper Plugin Example needs:

• class name helper_plugin_example
• which extends dokuwiki\Extension\Plugin¹⁾.
• to be stored in a file lib/plugins/example/helper.php.

Moreover, a plugin.info.txt file is needed. For full details of plugins and their files and how to create more helper components refer to plugin file structure.

• public getMethods() Returns info about the methods supported
• public <helper methods>() Your public Helper methods, listed by getMethods()
• protected/private <protected methods() (optional) When you need protected/private methods

• See common plugin functions for inherited functions available to all plugins. e.g. localisation, configuration and introspection.

Helper plugins should also return info about the methods supported. getMethods() should return an array of methods, each of them with an array of method name, description, parameters and return value. Parameters and return values are arrays with parameter description as key and PHP object type as value.

Example:

public function getMethods() {
    $result = [];
    $result[] = [
        'name' => 'getThreads',
        'desc' => 'returns pages with discussion sections, sorted by recent comments',
        'params' => [
            'namespace' => 'string',
            'number (optional)' => 'integer'
        ],
        'return' => ['pages' => 'array'],
    ];
    // and more supported methods...
    return $result;
}

The work is done by methods according to the methods listed in getMethods(). Of course, the helper plugin class can contain more, private methods. Also they should not be listed in getMethods().

Some function are shared between the plugins, refer to next sections for info about:

• Plugin configuration settings
• Localization
• Using CSS styles and javascript

• Plugin programming tips
• Plugin Development
• Available helper plugins