DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:common_plugin_functions

Common Plugin Functions

Each of the currently implemented DokuWiki plugin classes, syntax, admin, action, helper, remote and renderer provide a common set of methods and properties enabling standard configuration, introspection, localization and output facilities. These functions produce their results taking into account local installation settings and specific DokuWiki requirements.

These functions are declared in the interface class, PluginInterface, defined in inc/Extension/PluginInterface.php and implemented in PluginTrait in inc/Extension/PluginTrait.php.

A summary of the functions and properties are shown below. For full and up-to-date details follow the links to the API reference and read DokuWikis source code itself in the Source Repository on Github.

Inherited methods available in all plugins:

Name Description
getInfo() Returns associative array with basic information read from plugin.info.txt from plugin directory. For more details read plugin info.
getConf() Returns the value of a named plugin configuration variable. For more details read configuration below.
getLang() Returns text for the supplied key in the current language. Refer localization below for details.
locale_xhtml() Will pass local version of a resource file to the renderer for immediate output. Refer localization below for details.
email() Returns a properly formatted mailto: link, taking into account the wiki installation's mailguard setting. (exception: use in syntax plugins $renderer->emaillink())
external_link() Returns a properly formatted external link, taking into account wiki config settings. (exception: use in syntax plugins $renderer->externallink())
render() Will pass text string to the parser & renderer for immediate output. The text may contain DokuWiki markup. Use this sparingly as there is a large overhead in setting up the parser for each use. (exception: not available in syntax plugins)
loadHelper() Loads a given helper plugin (if the plugin is enabled). Details and example in helper plugins.
getPluginType() Returns the plugin type, e.g. syntax, admin or action.
getPluginName() Returns the plugin name
getPluginComponent() Returns the plugin component name, for a component, an empty string'

The following additional methods can be overridden when required:

Name Description
isSingleton() Default DokuWiki reuses instances of the plugin. This can be prevented by adding the function isSingleton() that returns false.

Configuration

Please refer to Configuration for more info. The additional files used by plugins are:

  • <dokuwiki>/lib/plugins/<pluginname>/

    • conf/default.php
      • contains the default settings for the plugin
      • accessible via $this->getConf()
      • :!: modified settings (configuration changes) are stored within DokuWiki's 'local' settings file <dokuwiki>/conf/local.php

    • conf/metadata.phpconfig metadata describing the settings for use by configuration manager

    • lang/<language>/settings.php – localized strings used in the configuration manager
Use conf/metadata.php and the localized settings.php files to tell the Configuration Manager about the plugin's settings. E.g. to provide a list of valid values or to flag a setting as a security alert. All of the metadata settings available to DokuWiki's own configuration settings are useable by plugins, see Configuration Metadata for more detail.

If a plugin complies to the above structure the wiki admin will be able to manage the settings interactively through the Configuration Manager.

Example

Read setting 'sortkey' from config:

$sort = $this->getConf('sortkey');

Introspection

  • getPluginType() — return the plugin type, e.g. syntax, admin or action.
  • getPluginName() — return the plugin name
  • getPluginComponent() — return the plugin component name

Localization

Localizations are stored in the plugin folder. The next files can be provided:

  • <dokuwiki>/lib/plugins/<pluginname>/
    • lang/<language>/lang.php – Localized language strings
    • lang/<language>/settings.php – localized strings used in the configuration manager
    • lang/<language>/<filename>.txt – localized text including DokuWiki markup

Please see the developer info about localization, inclusive javascript localization and examples.

Instantiating

Default DokuWiki reuses instances of plugins. This can be prevented by adding the function isSingleton() that returns false, so plugin_load('<plugin type>', '<plugin name>') and loadHelper('<plugin name>', true) will return an new plugin object on each call.

/**
 * Return false to prevent DokuWiki reusing instances of the plugin
 * 
 * @return bool
 */
public function isSingleton() {
    return false;
}

Load Helper plugins

In all plugins Helper plugins can be loaded by $this->loadHelper('tag', true). First argument is helper plugin name, second argument if English error message should be displayed (cannot be localized). It will reuses the instance of the requested plugin, so it will return always the same plugin object. To prevent this behaviour see instantiating above.

It loads a given helper plugin if the plugin is enabled. Details and examples in helper plugins.

Example

Load helper of the tag plugin:

//get the instance of Tag Helper
$tag = $this->loadHelper('tag', true);
 
if($tag instanceof PluginInterface) {
    $entries = $tag->tagRefine($entries, $refine);
}

Load other plugins

If you want to use another plugin in your plugin you have to use the plugin_load() 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() can be used to check if a plugin is available or not.

It will return a plugin object. Default this object is the unique plugin instance stored by the plugin controller, but when the requested plugin is marked as not singleton by isSingleton() it will return a new plugin object at each request.

Or use instead the additional parameter options of plugin_load($type, $name, $new = false, $disabled = false).

Load helper plugin component from Tag plugin, which has only one helper component:

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

Or load syntax plugin component from Data plugin, which has several syntax components, so specifying of the component needed:

if(!plugin_isdisabled('data')) {
    $table = plugin_load('syntax', 'data_table');
    if($table instanceof PluginInterface) {
        $hasfilter = $table->hasRequestFilter();
    }
}

Output

  • email($email, $name='', $class='', $more='')
    Output an email link using the installation's email obfuscation settings. Default class mail is added to emaillink, $class overrides this. $more adds extra attributes to email link.
  • external_link($link, $title='', $class='', $target='', $more='')
    Output an external link using the installation's target settings, setting the optional argument will overrides it. $more adds extra attributes to the link.
  • render($text, $format='xhtml')
    Uses the parser to parse and output a string containing wiki markup. Very inefficient for small pieces of data – try not to use

See also

devel/common_plugin_functions.txt · Last modified: 2023-09-01 13:56 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