This is an old revision of the document!
Table of Contents
Admin Plugins
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:
- The whyspam plugin consist of a single admin component/file, allowing admins (superusers and managers) to check why certain text were blocked as spam, interacting with DokuWiki's bundled stopword file.
- Structured data plugin uses two separate admin components/files (requires a special plugin file structure), one to manage field aliases and another to do database maintenance. This plugin also have several syntax components and shows how to use a helper plugin.
Admin plugin trigger
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.
Admin plugin class
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. |
Hello World admin plugin
Here is the hello world example.
Programming tips
- If you haven't read plugins about naming and deployment, do that. There is also a link to the plugin wizard which creates a skeleton with comments to get you started.
- A plugin may vary its menu text on the main admin menu depending on its status or the state of what it administers. The user manager plugin does it to indicate if authentication is used or not.
Safety
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.
- Use the
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. - When using forms you should include a hidden form field with the session-based security token by calling the function formsecuritytoken(). Before you process the form input, call checkSecurityToken(). This function checks if the sent security token is correct. This protect against Cross-site request forgery attacks. See the hello world example. If you use the Doku_Form class the security token is included automaticly.
Core API & globals
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.
Localization & configuration
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
- lang.php
<?php // language file for DokuWiki admin plugin $lang['menu'] = 'FooBar admin';
JavaScript & CSS
The user experience can be enhanced by using JavaScript and CSS Stylesheets. The plugin file structure shows where to include files.