DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

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) {
    $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).

Since 2013-05-10 Weatherwax loadHelper() is also available in Syntax Plugins.

If you want to use a helper plugin in a syntax plugin in the release 2012-10-13 “Adora Belle” and before 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. So you can have more database instances:

if(!plugin_isdisabled('sqlite')) {
    $DBIa = plugin_load('helper', 'sqlite');
    if($DBIa) {
        $DBIa->init('testa',dirname(__FILE__).'/db/');
    }
 
    $DBIb = plugin_load('helper', 'sqlite');
    ...
}

How to Write a Helper Plugin

A Helper Plugin Example needs:

  • class name helper_plugin_example
  • which extends DokuWiki_Plugin1).
  • 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.

Required functions

  • getMethods() Returns info about the methods supported
  • <helper methods>() Your public Helper methods, listed by getMethods()
  • _<private methods() (optional) When you need private methods, prefix the name with a underscore.

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 = array();
    $result[] = array(
        'name' => 'getThreads',
        'desc' => 'returns pages with discussion sections, sorted by recent comments',
        'params' => array(
            'namespace' => 'string',
            'number (optional)' => 'integer'
        ),
        'return' => array('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. It's good practice that names of private methods begin with an underscore. 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 inc/plugin.php
devel/helper_plugins.txt · Last modified: 2015-05-04 17:09 by ach