Admin Plugins are plugins that provide DokuWiki with extra functions accessible via the admin window. It is not necessary to create an admin component to enable plugin configuration, it is already included, see configuration.
Some examples:
A user initiates interaction with the admin plugin by clicking the plugin's menu link in the admin window. Following that request, the plugin handle() method will be called and the result of html() be output in current template.
If the plugin needs to receive information back from the user it needs to ensure the following $_REQUEST variables are set in any forms the user may submit or links the user may click.
$_REQUEST['do'] = 'admin' — this tells DokuWiki its in admin mode.$_REQUEST['page'] = plugin name — this tells DokuWiki which plugin to call. If its not present the admin menu will be shown.$_REQUEST['id'] = page name — the current page, if the user presses the show page button they will be shown this page.
Best practice is to include these in your plugin's HTML output as hidden form controls (<input> with type=“hidden”), although you could pass them on links as part of the query string as done in the admin window. See Hello World admin plugin for an example.
Inheritance Hierarchy:
The simple admin plugin foobar needs to define a class named admin_plugin_foobar which extends DokuWiki_Admin_Plugin. The class needs to be stored in a file called lib/plugins/foobar/admin.php. For full details of plugins and their files and how to include more than one admin component refer to plugin file structure.
Class needs to implement the following methods (Must override):
| Name | Description |
|---|---|
| handle() | Called from act_dispatch() in inc/action.php. Should carry out any processing required by the plugin. |
| html() | Called from tpl_admin() in inc/template.php. Render HTML output for the plugin. Most admin plugins displays a helpful text and a HTML form. |
Methods & properties (Override only if needed):
| Name | Description |
|---|---|
| forAdminOnly() | Return true if the plugin should only be accessed by wiki admins (as indicated by $conf['superuser'] ). Return false if the plugin may be accessed by wiki managers (as indicated by $conf['manager'] ) also. This method only needs to be overridden if the plugin can be accessed by managers. The implementation in the base class returns true. |
| getMenuText() | Return the menu string to be displayed in the main admin menu. If you have followed the localisation guidelines you do not need to override this function, the text for the correct language will be provided from the plugin's $lang['menu'] value found in the plugin's lang/<ISO-code>/lang.php file. |
| getMenuSort() | Return a number which is used to determine the position in the admin menu of the plugin's menu text. |
| getTOC() | Use this function to create a table of contents for potentially long pages, see config plugin for an example. Should return an array of tocitems created by the html_mktocitem() method. |
Inherited methods (also see inc/plugin.php):
| Name | Description |
|---|---|
| getConf() | Returns the value of a named plugin configuration variable. For more details read configuration. |
| getLang() | Returns text for the supplied key in the current language. Refer localization guidelines for details. |
| locale_xhtml() | Will pass local version of a resource file to the renderer for immediate output. Refer localization for details. |
| email() | Returns a properly formatted mailto: link, taking into account the wiki installation's mailguard setting. |
| external_link() | Returns a properly formatted external link, taking into account wiki config settings. |
| 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. |
| loadHelper() | Loads a given helper plugin (if the plugin is enabled). Details and example in helper plugins. |
Here is the hello world example.
The admin plugin has the opportunity to interact with the DokuWiki admin user through the data returned by forms and/or query strings, i.e. the $_REQUEST, $_POST or $_GET variables. All user entered data must be treated with suspicion, even from users identified as admins by ACL settings. Take special care to follow these two rules and please read security guidelines for plugin authors for more details.
htmlspecialchars() or the DokuWiki shortcut hsc() to ensure any raw data output has all HTML special characters converted to HTML entities to protect from Cross-site scripting. Also any wiki data extracted and used internally (eg. user names) should be treated with suspicion. DokuWiki uses a number of global variables to hold information about the current page, current user and the actions being performed. Details of these can be found on the environment page.
Adding configuration to any plugin is as easy as adding two files, one for the default values and another with metadata to make the settings available in the configuration manager. Then access the values using getConf() method.
Localization isn't much harder. Translated plugins help making DokuWiki easy to administer. Both single strings and text files containing wiki markup are supported. The language file for admin plugins should at least contain a menu entry that will automatically be used in the admin window.
Example making the admin window link to your plugin read FooBar admin
<?php // language file for DokuWiki admin plugin $lang['menu'] = 'FooBar admin';
The user experience can be enhanced by using JavaScript and CSS Stylesheets. The plugin file structure shows where to include files.