Admin Plugins

Admin Plugins are plugins that provide Dokuwiki with extra functions accessible via the Admin menu.

For more information on writing your own admin plugin, see the tutorial.

An Admin Plugin example needs to define a class named admin_plugin_example which extends DokuWiki_Admin_Plugin¹⁾. The class needs to be stored in a file called lib/plugins/example/admin.php. For full details of plugins and their files refer to plugin file structure.

The class needs to implement at least the following functions:

• getInfo() — Return a Hash with plugin info [author, email, date, name, dest, url]
• handle() — Carry out any processing required by the plugin.
• html() — Render html output for the plugin.

The following additional methods can be overridden when required:

• 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'] ). This method only needs to be overridden if the plugin can be accessed by managers. The implementation in the base class returns true.
• getMenuText($language) — 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/[language]/lang.php file.
• getMenuSort() return a number which is used to determine the position in the admin menu of the plugin's menu text.

Additional functions can be defined as needed. It is recommended to prepend an underscore to self defined functions to avoid possible name clashes with future plugin specification enhancements.

Inherited Functions & Properties

• getLang($string_name) — return text for $string_name in the current language. Refer localisation guidelines.
• locale_xhtml($id) — will pass local version of file $id.txt to the renderer for immediate output.
• email($email, $name='', $class='', $more='') — return a properly formatted mailto: link, taking into account the wiki installation's mailguard setting.
• external_link($link, $title='', $class='', $target='', $more='') — return a properly formatted external link, taking into account wiki config settings.
• render($text, $format='xhtml') — will pass $text 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.

(regaining control from Dokuwiki)

A user initiates interaction with the admin plugin by clicking the plugin's menu option on the Admin menu. 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 Dokwiki 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.

The base admin plugin class (DokuWiki_Admin_Plugin) provides support for localisation of the plugin. There are four public methods and two properties:

• Methods
  • getLang('string name') — will return the local language version of string name or the US English version if it is not present.
  • locale_xhtml('filename') — will pass the local language version of 'filename.txt' to the renderer for immediate output. If a local language file does not exist the US English version will be used.
  • localFN('id') — will return the full path for local language file 'id.txt' or if that file doesn't exist it will return the full path for the US English version of 'id.txt'.
  • setupLocale() — will read in the plugins language strings for the current language - any missing strings will be filled with the US English version. If retrieval of language strings is handled by getLang() there is no need to access this method.

• Properties
  • $lang — an array of language dependent strings. This array is initially empty and needs to be filled either by calling setupLocale() or making a call to getLang(). If all retrieval of language strings is handled by getLang() there is no need to access this property.
  • $localised — boolean, indicates whether or not localisation has been setup. Initially false, set to true by setupLocale(). If all retrieval of language strings is handled by getLang() there is no need to access this property.

Localisation files must be placed in the following folder structure:

lib/plugins/[plugin name]/lang/[xx]/

where [xx] is the two digit localisation code. All plugins should at least provide data for “en” (US English). This data will be used if data for the actual locale is not present.

Text strings displayed by the plugin should be defined in the file

.../lang/[xx]/lang.php

and be of the form

$lang['string name'] = 'text';

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. A malicious user may attempt to subvert the wiki or server by sending data to exploit security vulnerabilities.

A plugin may vary its menu text on the main admin menu depending on its status or the state of what it administers.

There is a meatier skeleton too.

lib/plugin/skeleton/admin.php

<?php
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'admin.php');
 
/**
 * All DokuWiki plugins to extend the admin function
 * need to inherit from this class
 */
class admin_plugin_skeleton extends DokuWiki_Admin_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
      return array(
        'author' => 'me',
        'email'  => 'me@somesite.com',
        'date'   => '20yy-mm-dd',
        'name'   => 'admin plugin skeleton',
        'desc'   => 'demonstration skeleton',
        'url'    => 'http://wiki.splitbrain.org/plugin:admin',
      );
    }
 
    /**
     * return sort order for position in admin menu
     */
    function getMenuSort() {
      return 999;
    }
 
    /**
     * handle user request
     */
    function handle() {
    }
 
    /**
     * output appropriate html
     */
    function html() {
    }
 
}

lib/plugins/skeleton/lang/en/lang.php

<?php
/**
 * english language file
 */
 
// settings must be present and set appropriately for the language
$lang['encoding']   = 'utf-8';
$lang['direction']  = 'ltr';
 
// for admin plugins, the menu prompt to be displayed in the admin menu
// if set here, the plugin doesn't need to override the getMenuText() method
$lang['menu'] = 'Skeleton Plugin...'; 
 
// custom language strings for the plugin

E-Razor: Nice, i thought about some kind of darcs plugin to update dokuwiki via web.

Another Idea would be adding functions like install() remove() update() and get_version() in every plugin and walk through each plugin.

Maybe an interface should show all aviable plugins in a table aviable version and installed version. I suggest some buttons to the right update (if the plugin is installed) remove (if the plugin is installed) and install (if the plugin is not installed).
At the button of that page should be something like update all.

Anyway, i'm going to write some functions to manage darcs repositories in the next few days.

For all that you need the plugin manager plugin - available now with the development version

I found myself getting annoyed at the arbitrary sort order of the Admin plugins, so I made a change to inc/html.php to sort the plugin list alphabetically on the first character of the name. Replace 'sort' ⇒ $obj→getMenuSort() with 'sort ⇒ ord($obj→getMenuText($conf['lang'])) to make the plugin page a bit less annoying.