DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:helper_plugins

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.

How to Use a Helper Plugin

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);
}

Reusing of plugin objects

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');
    ...
}

How to Write a Helper Plugin

A Helper Plugin Example needs:

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.

Required functions

  • 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

Inherited functions

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

getMethods()

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;
}

Helper Methods

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().

Common plugin functions

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

Further reading

1)
defined in lib/Extension/Plugin.php, before called DokuWiki_Plugin which is still available as alias
devel/helper_plugins.txt · Last modified: 2023-09-01 23:54 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki