Table of Contents
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
lang/<language>/settings.php
– localized strings used in the configuration manager
Useconf/metadata.php
and the localizedsettings.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
oraction
.getPluginName()
— return the plugin namegetPluginComponent()
— 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 stringslang/<language>/settings.php
– localized strings used in the configuration managerlang/<language>/<filename>.txt
– localized text including DokuWiki markup- accessible via
$this->locale_xhtml()
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 classmail
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