Differences

This shows you the differences between two versions of the page.

--- devel:admin_plugins [2011-03-15 09:32] – [Safety] lupo49
+++ devel:admin_plugins [2023-09-01 23:55] (current) – Klap-in
@@ Line 1: / Line 1: @@
 ====== Admin Plugins ======
-Admin Plugins are [[:plugins]] that provide DokuWiki with extra functions accessible via the [[:admin_window|admin window]]. It is not necessary to create an admin component to enable plugin configuration, it is already included, see [[devel:configuration]].
+[[plugintype>2#extension__table|Admin Plugins]] are [[plugins]] that provide DokuWiki with extra functions accessible via the [[:admin_window|admin window]]. It is not necessary to create an admin component to enable plugin configuration, it is already included, see [[devel:configuration]].
 Some examples:
@@ Line 9: / Line 9: @@
-===== Admin plugin trigger =====
+===== How to Write an Admin Plugin =====
-A user initiates interaction with the admin plugin by clicking the plugin's menu link in the [[:admin_window|admin window]]. Following that request, the plugin **handle()** method will be called and the result of **html()** be output in current template.
+An Admin Plugin //Example// needs:
+  * class name  ''admin_plugin_example''
+  * which extends [[xref>AdminPlugin]]((defined in ''lib/Extension/AdminPlugin.php'', before called ''DokuWiki_Admin_Plugin'' which is still available as alias)).
+  * to be stored in a file ''lib/plugins/example/admin.php''.
+Moreover, a [[plugin_info|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]].
-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.
+===Required methods===
-  * ''%%$_REQUEST['do'] = 'admin'%%'' --- this tells DokuWiki its in admin mode.
+Class needs to implement the following methods (Must override):
-  * ''%%$_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.
+^Name ^Description ^
+|[[xref>inc/Extension/AdminPlugin::handle|handle()]] |Called from [[xref>act_dispatch()]] in ''inc/action.php''. Should carry out any processing required by the plugin. |
+|[[xref>inc/Extension/AdminPlugin::html|html()]]     |Called from [[xref>tpl_admin()]] in ''inc/template.php''. Render HTML output for the plugin. Most admin plugins displays a helpful text and a HTML form.|
-===== Admin plugin class =====
+===Optional methods===
+(Override only if needed):
-**Inheritance Hierarchy:**
+^ Name                                                        ^ Description                                                                                                                                                                                                                                                                                                                                                ^
-  * [[xref>inc/plugin.php|DokuWiki_Plugin]]
+| [[xref>forAdminOnly()]]  | Inherited method returns default ''true'', what means the plugin can only be accessed by wiki admins (who are indicated by [[config:superuser|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 [[config:manager|manager]] config option).  |
-    * **[[xref>lib/plugins/admin.php|DokuWiki_Admin_Plugin]]**
+| [[xref>getMenuText()]]    | Return the menu string to be displayed in the main admin menu.  If you have followed the [[#Localization & configuration|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.               |
-    * [[xref>lib/plugins/action.php|DokuWiki_Action_Plugin]]
+| [[xref>getMenuSort()]]    | Return a number which is used to determine the position in the admin menu on [[:admin window]].                                                                                                                                                                                                                                                            |
+| [[xref>getTOC()]]              | Use this function to create a table of contents for potentially long pages, see [[plugin:config|config plugin]] for an example. Should return an array of tocitems created by the [[xref>html_mktocitem()]] method.                                                                                                                                        |
+| [[xref>getMenuIcon|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.                                                                                                                                                                                                      |
-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 [[devel:plugin_file_structure|plugin file structure]].
+===Inherited methods===
-**Class needs to implement the following methods** (Must override):
+See [[common plugin functions]] for inherited functions available to all plugins. e.g. localisation, configuration and introspection.
-^Name ^Description ^
+=== Icon ===
-|[[xref>lib/plugins/admin.php#handle|handle()]] |Called from [[xref>act_dispatch()]] in ''inc/action.php''. Should carry out any processing required by the plugin. |
-|[[xref>lib/plugins/admin.php#html|html()]]     |Called from [[xref>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):
+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.
-^Name ^Description ^
+There are a few restrictions the icon has to adhere to for it to be displayed:
-|[[xref>lib/plugins/admin.php#foradminonly|forAdminOnly()]] |Return ''true'' if the plugin should only be accessed by wiki admins (as indicated by [[config:superuser|$conf['superuser'] ]]). Return ''false'' if the plugin may be accessed by wiki managers (as indicated by [[config:manager|$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''.|
-|[[xref>lib/plugins/admin.php#getmenutext|getMenuText()]]   |Return the menu string to be displayed in the main admin menu.  If you have followed the [[#Localisation & configuration|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. |
-|[[xref>lib/plugins/admin.php#getmenusort|getMenuSort()]]   |Return a number which is used to determine the position in the admin menu of the plugin's menu text. |
-|[[xref>lib/plugins/admin.php#gettoc|getTOC()]]             |Use this function to create a table of contents for potentially long pages, see [[plugin:config|config plugin]] for an example. Should return an array of tocitems created by the [[xref>html_mktocitem()]] method. |
-**Inherited methods** (also see [[xref>inc/plugin.php]]):
+  * It has to be in SVG format
+  * The file has to be smaller than 2 kB
+  * It should only contain a single path object
-^Name ^Description ^
+The fill color of the path will be set by CSS and match the link color (unless your template does something different).
-|[[xref>inc/plugin.php#getconf|getConf()]]             |Returns the value of a named plugin configuration variable. For more details read [[configuration]].|
-|[[xref>inc/plugin.php#getlang|getLang()]]             |Returns text for the supplied key in the current language. Refer [[#Localization & configuration|localization guidelines]] for details.|
-|[[xref>inc/plugin.php#locale_xhtml|locale_xhtml()]]   |Will pass local version of a resource file to the renderer for immediate output. Refer [[localization]] for details.|
-|[[xref>inc/plugin.php#email|email()]]                 |Returns a properly formatted ''mailto:'' link, taking into account the wiki installation's ''mailguard'' setting.|
-|[[xref>inc/plugin.php#external_link|external_link()]] |Returns a properly formatted external link, taking into account wiki config settings.|
-|[[xref>inc/plugin.php#render|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.|
-|[[xref>inc/plugin.php#loadhelper|loadHelper()]]       |Loads a given helper plugin (if the plugin is enabled). Details and example in [[helper plugins]].|
-===== Hello World admin plugin =====
+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 [[https://material.io/guidelines/style/icons.html|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|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 [[xref>wl()]] handles this for you. Access via the global $ID variable.
+  * ''%%$_REQUEST['sectok']%% = <random token>'' \\ Security token, from the form field generated by function [[xref>formSecurityToken()]] or auto-included when [[xref>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 [[xref>Form]] class ''%%$form->addHiddenField('page','data_clean')%%'') and on links as part of the query string as done in the admin window. See [[devel:admin_plugin_skeleton|Hello World admin plugin]] for an example. Use the global [[devel:request vars|$INPUT]] object for accessing these or your own ''$_REQUEST'' variables.
+===== Example Hello World admin plugin =====
 Here is the [[devel:admin_plugin_skeleton|hello world]] example.
@@ Line 60: / Line 75: @@
 ===== 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.
+  * If you haven't read [[plugins|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 [[plugin:usermanager|user manager]] plugin does it to indicate if authentication is used or not.
+  * A plugin may vary its menu text on the main admin menu depending on its status or the state of what it administers. The [[plugin:usermanager|user manager]] plugin does it to indicate if authentication is used or not. See its [[xref>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.  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 [[devel:security|security guidelines for plugin authors]] for more details.
+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 [[devel:security|security guidelines for plugin authors]] for more details.
-  * Use the ''htmlspecialchars()'' or the DokuWiki shortcut [[xref>hsc()]] to ensure any raw data output has all HTML special characters converted to HTML entities to protect from [[wp>Cross-site scripting]]. Also any wiki data extracted and used internally (eg. user names) should be treated with suspicion.
+  * All user entered data must be treated with suspicion, even from users identified as admins by ACL settings. It is recommended to use DokuWiki [[request_vars|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.
-  * When using forms you should include a hidden form field with the session-based security token by calling the function [[xref>formsecuritytoken()]]. Before you process the form input, call [[xref>checkSecurityToken()]]. This function checks if the sent security token is correct. This protect against [[wp>Cross-site request forgery]] attacks. See the [[#Hello World admin plugin|hello world]] example. FIXME - //No example of the token concept given in the example.//  --- [[user>lupo49|M. S.]] //2011/03/15 09:30//
+  * Use the  [[xref>hsc()]], the DokuWiki shortcut of [[phpfn>htmlspecialchars()]], to ensure any raw data output has all HTML special characters converted to HTML entities to protect from [[wp>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 [[xref>formSecurityToken()]]. Before you process the form input, call [[xref>checkSecurityToken()]]. This function checks if the sent security token is correct. This protect against [[wp>Cross-site request forgery]] attacks. See the [[#Hello World admin plugin|hello world]] example. If you use the [[xref>Form]] class the security token is automatically included.
 ==== Core API & globals ====
@@ Line 77: / Line 95: @@
 ==== Localization & configuration ====
-Adding [[devel:configuration|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.
+The plugin [[common plugin functions#Configuration|configuration]] and [[common plugin functions#localization]] explains the files and the functions needed for using these features.
-Example getting the setting named ''foobar''
+  * 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]].
-  $this->getConf('foobar')
+**Example** Making the admin window menu link to your plugin called //FooBar admin//:
-[[devel:localization|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**''
 <code php lang.php>
 <?php
-// language file for DokuWiki admin plugin
+// minimal language file for DokuWiki admin plugin
 $lang['menu'] = 'FooBar admin';
 </code>
@@ Line 95: / Line 109: @@
 The user experience can be enhanced by using [[devel:javascript|JavaScript]] and [[devel:css|CSS Stylesheets]]. The [[devel:plugin_file_structure|plugin file structure]] shows where to include files.
+===== Further reading =====
+  * [[Plugin programming tips]]
+  * [[security|Security Guidelines for Plugin Authors]]
+  * [[plugins|Plugin Development]]
+  * [[plugintype>2#extension__table|Available admin plugins]]