The goal of this tutorial is to explain the concepts involved in a DokuWiki admin plugin and to go through the steps involved in writing your own plugin.

For those who are really impatient to get started, grab a copy of the admin plugin Skeleton. Its a bare bones plugin which outputs "Hello World!" when selected from the admin menu.

There are four components to an admin plugin

1. admin menu prompt
   • can be provided in three ways:
     1. via the $lang['menu'] string in the localised lang.php file, use this method if the admin menu prompt will always be the same.
     2. via the getMenuText() method. Use this method if you need to display different strings at different times or to represent different states.
     3. if neither of the above two are used the plugin's name per getInfo() function will be used.
2. handle() function.
   • carries out any and all of the processing to be done by the plugin. It must not output any html.
3. html() function.
   • takes any results left behind by the handle() function and outputs the html required to keep the user informed on what has just happened and ask them what they would like to do next.
   • any links or forms that should return control back to the plugin must include do=admin & page=plugin name and should include id=current wiki page to allow the user to return to where they came from.
4. localised language strings and files

For Dokuwiki to know to return to the admin plugin the user page request must include two variables set to specific values:

• $_REQUEST['do'] = "admin"
• $_REQUEST['page'] = "plugin_name"

For other buttons and links on the Dokuwiki page to allow the user to return to the wiki page they came from you should also set one further value:

• $REQUEST['id'] = $ID

The values can be set as input controls of type hidden or as part of the link query string:

e.g.

<form action="<?php echo wl($ID) ?>" method="post">
<input type='hidden' name="do"   value="admin" />
<input type='hidden' name="page" value="mypluginname" />
...
</form>
 
or 
 
<form action="<?php echo wl($ID, 'do=admin&amp;page=mypluginname') ?>" method="post">

Any data received from the user must be treated with suspicion. Form data and query strings can be spoofed by malicious users. Don't echo anything back to the user without filtering it to remove any html special characters. Don't act on any user data (e.g. filenames) without first verifying its a valid and acceptable value.

Ok, so you have decided you want to extend Dokuwiki's admin section with your own plugin. You have worked out what the facility you are going to provide and how you are going to provide it. Now you need to write the plugin.

1. Decide on a name for the plugin. You may want to check the list of available plugin's to make sure you aren't choosing a name that is already in use.
2. In your own Dokuwiki installation create a new sub directory in the lib/plugins/ directory. That directory will have the same name as your plugin.
3. Create the file admin.php in the new directory. As a starting point, use a copy of the skeleton plugin.
4. Edit that file to make it yours.
   • change the class name to be syntax_plugin_<your plugin name>.
   • change the getInfo() to report information about your plugin.

… …

1. Test and post your completed plugin on the Dokuwiki plugin page.

And that's our plugin finished.