DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:admin_plugins

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.

How to Write an Admin Plugin

An Admin Plugin Example needs:

  • class name admin_plugin_example
  • which extends AdminPlugin1).
  • to be stored in a file lib/plugins/example/admin.php.

Moreover, a plugin.info.txt file is needed. For full details of plugins and their files and how to create more admin components refer to plugin file structure.

Required methods

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.

Optional methods

(Override only if needed):

Name Description
forAdminOnly() Inherited method returns default true, what means the plugin can only be accessed by wiki admins (who are indicated by superuser config option). This method only needs to be overridden, to let it return false, if the plugin can be accessed by managers (who are indicated by manager config option).
getMenuText() Return the menu string to be displayed in the main admin menu. If you have followed the localisation guidelines below 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 localisation files.
getMenuSort() Return a number which is used to determine the position in the admin menu on admin window.
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.
getMenuIcon() Allows you to override which icon to load on the Admin screen. Useful if you have multiple admin components and want to use different icons for them.

Inherited methods

See common plugin functions for inherited functions available to all plugins. e.g. localisation, configuration and introspection.

Icon

Since the 2017 Frusterick Manners release, admin plugins can provide an icon to be shown next to the plugin's name on the admin screen. By default this icon will be searched at lib/plugins/<yourplugin>/admin.svg. You can override the location with the getMenuIcon() method.

There are a few restrictions the icon has to adhere to for it to be displayed:

  • It has to be in SVG format
  • The file has to be smaller than 2 kB
  • It should only contain a single path object

The fill color of the path will be set by CSS and match the link color (unless your template does something different).

To match the style of other icons, we recommend to either pick an icon from the huge, free selection at https://materialdesignicons.com/ or adhere to the Material Design Guidelines when designing your own icon.

Admin plugin trigger

A admin or moderator 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.

Requests

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 or component to call. When not set the admin menu will be shown.
  • $_REQUEST['id'] = <name current wikipage>
    The current page, if the user presses the show page button they will be shown this page. If urlrewriting is enabled this is part of the page url, use of wl() handles this for you. Access via the global $ID variable.
  • $_REQUEST['sectok'] = <random token>
    Security token, from the form field generated by function formSecurityToken() or auto-included when Form class is used.

Best practice is to include these variables in your plugin's HTML output as hidden form controls (<input type=“hidden” …> or when using Form class $form->addHiddenField('page','data_clean')) and on links as part of the query string as done in the admin window. See Hello World admin plugin for an example. Use the global $INPUT object for accessing these or your own $_REQUEST variables.

Example Hello World admin plugin

Here is the hello world example.

Programming tips

  • If you haven't read plugins development page 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. See its getMenuText() implementation.

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. Take special care to follow the next rules and please read security guidelines for plugin authors for more details.

  • All user entered data must be treated with suspicion, even from users identified as admins by ACL settings. It is recommended to use DokuWiki Input Class. This class gives you type safe access to the request variables, makes sure they are correctly initialized and allows you to set defaults.
  • Use the hsc(), the DokuWiki shortcut of htmlspecialchars(), 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 Form class the security token is automatically included.

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

The plugin configuration and localization explains the files and the functions needed for using these features.

  • Be sure to add at least the menu entry to the language file, because this will automatically be used for the admin menu on admin window.

Example Making the admin window menu link to your plugin called FooBar admin:

lang.php
<?php
// minimal 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.

Further reading

1)
defined in lib/Extension/AdminPlugin.php, before called DokuWiki_Admin_Plugin which is still available as alias
devel/admin_plugins.txt · Last modified: 2023-09-01 23:55 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki