DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
devel:admin_plugins

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
devel:admin_plugins [2016-01-27 13:26] – [Admin plugin trigger] fix link of Admin Plugin Example 126.237.117.2devel:admin_plugins [2023-09-01 23:55] (current) – Klap-in
Line 13: Line 13:
 An Admin Plugin //Example// needs: An Admin Plugin //Example// needs:
   * class name  ''admin_plugin_example''   * class name  ''admin_plugin_example''
-  * which extends [[xref>DokuWiki_Admin_Plugin]]((defined in ''[[xref>lib/plugins/admin.php]]'')). +  * 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''.   * 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]]. 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]].
Line 21: Line 21:
  
 ^Name ^Description ^ ^Name ^Description ^
-|[[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>inc/Extension/AdminPlugin::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.|+|[[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.|
  
 ===Optional methods=== ===Optional methods===
 (Override only if needed): (Override only if needed):
  
-^Name ^Description ^ +^ Name                                                        ^ Description                                                                                                                                                                                                                                                                                                                                                ^ 
-|[[xref>lib/plugins/admin.php#foradminonly|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>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#getmenutext|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>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/admin.php#getmenusort|getMenuSort()]]   |Return a number which is used to determine the position in the admin menu on [[:admin window]]. | +| [[xref>getMenuSort()]]    | Return a number which is used to determine the position in the admin menu on [[:admin window]].                                                                                                                                                                                                                                                            | 
-|[[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. |+| [[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.                                                                                                                                                                                                      |
  
 ===Inherited methods===  ===Inherited methods=== 
Line 37: Line 38:
 See [[common plugin functions]] for inherited functions available to all plugins. e.g. localisation, configuration and introspection. 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 [[https://material.io/guidelines/style/icons.html|Material Design Guidelines]] when designing your own icon. 
  
 ===== Admin plugin trigger ===== ===== Admin plugin trigger =====
Line 48: Line 62:
   * ''%%$_REQUEST['do'] = 'admin'%%'' \\ This tells DokuWiki its in admin mode.   * ''%%$_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['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. FIXME is id really needed, is this not twice? +  * ''%%$_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>Doku_Form]] class is used.+  * ''%%$_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>Doku_Form]] class ''%%$form->addHidden('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.+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.
  
  
Line 63: Line 77:
   * 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.   * 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. See its [[xref>lib/plugins/usermanager/admin.php#getmenutext|getMenuText()]] implementation.+  * 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 ==== ==== Safety ====
Line 71: Line 85:
   * 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.    * 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. 
  
-  * 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. +  * 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.
  
-  * 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>Doku_Form]] class the security token is automatically included. 
 ==== Core API & globals ==== ==== Core API & globals ====
  
devel/admin_plugins.1453897615.txt.gz · Last modified: 2016-01-27 13:26 by 126.237.117.2
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

Global DokuWiki Links