Differences

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

--- devel:plugin_programming_tips [2015-05-27 13:51] – [Disabling syntax plugins in user comments] 130.112.1.3
+++ devel:plugin_programming_tips [2023-09-20 23:34] (current) – Klap-in
@@ Line 5: / Line 5: @@
 On this page are some tips (see ToC right). Useful resources elsewhere in the wiki are:
   * [[common plugin functions#Configuration]]
-  * [[common plugin functions#Localisation]]
+  * [[common plugin functions#Localization]]
   * Plugin [[plugin file structure|file structure]] and [[plugin file structure|name conventions]]
+  * [[devel:badextensions|Conflicting Versions and Basenames]]
@@ Line 20: / Line 20: @@
 <code php>
-    global $auth;
+global $auth;
-    if($auth->canDo('getUsers')) {  // is this feature available?
+if ($auth->canDo('getUsers')) {  // is this feature available?
-        $auth->retrieveUsers(0,0,$filter);
+    $auth->retrieveUsers(0, 0, $filter);
-    }
+}
 </code>
 Where ''$filter'' is an array with one or more of the following keys ''user'', ''name'', ''mail'', or ''grps''.
-Several values in each using '|' as a separator.\\
+Several values in each using ''|'' as a separator.
 For example, to retrieve all users in the group 'admin', one would use:
 <code php>
-    $filter['grps']="admin";
+$filter['grps'] = 'admin';
-    $array_of_matches = retrieveUsers(0,0,$filter);
+$array_of_matches = $auth->retrieveUsers(0, 0, $filter);
 </code>
-Be aware that the user backend needs to implement this function. Otherwise it returns always an empty array.
+Be aware that the authentication plugin needs to implement this function. Otherwise it returns always an empty array.
-See also [[devel:authentication_backends#optional_methods|authentication backend]] mention of ''retrieveUsers()'' and other auth functions.
+See also [[devel:auth_plugins#retrieveusers|authentication plugins]] mention of ''retrieveUsers()'' and other functions.
 ===== DokuWiki Global Variables =====
@@ Line 53: / Line 54: @@
 ===Protect forms and action urls===
-If you use forms in your plugins or urls that initiate actions, you should include a hidden form field with the session-based security token. In the current version of DokuWiki you can generate this field by calling the function ''formSecurityToken()''. Before you process the form input, call ''checkSecurityToken()''. This function checks if the sent security token is correct.
+If you use forms in your plugins or urls that initiate actions, you should include a hidden form field with the session-based security token. In the current version of DokuWiki you can generate this field 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.
 //Scenario// If you wonder, why this will make your plugins more secure, consider the following scenario:
@@ Line 163: / Line 164: @@
   * in PHP:
     * set a value ''[[xref>set_doku_pref|set_doku_pref($pref, $value)]]''
-    * delete an entry ''[[xref>set_doku_pref|set_doku_pref($pref, false)]]'' ([[devel:develonly]])
+    * delete an entry ''[[xref>set_doku_pref|set_doku_pref($pref, false)]]''
     * and retrieve its value with ''[[xref>get_doku_pref|get_doku_pref($pref, $default)]]''
   * and in javascript:
@@ Line 177: / Line 178: @@
 setCookie("yourCookieName", $value, $expire, $cookieDir, '', ($conf['securecookie'] && is_ssl()));
 </code>
-and in javascript (inclusive fallback for before Binky release):
+and in javascript:
 <code javascript>
 jQuery.cookie("yourCookieName", value, {
     expires: 7, //days
-    path: (typeof DOKU_COOKIE_PARAM.path === "undefined" ? JSINFO.DOKU_COOKIE_PARAM.path : DOKU_COOKIE_PARAM.path ),
+    path: DOKU_COOKIE_PARAM.path,
-    secure: (typeof DOKU_COOKIE_PARAM.secure === "undefined" ? JSINFO.DOKU_COOKIE_PARAM.secure : DOKU_COOKIE_PARAM.secure )
+    secure: DOKU_COOKIE_PARAM.secure
 });
-</code>
-As long ''DOKU_COOKIE_PARAM'' is not general available, you need to add ''JSINFO.DOKU_COOKIE_PARAM'' with an [[Action Plugin]] see for details at [[devel:javascript#JSINFO]] section of the javascript wiki page.
-<code php>
-public function register(Doku_Event_Handler $controller) {
-    $controller->register_hook('DOKUWIKI_STARTED', 'AFTER',  $this, '_cookiepath');
-}
-/**
- * Fallback cookie parameters for releases before the release 2013-12-08 "Binky"
- *
- * @deprecated 2013-12-08 Temporary fallback to JSINFO.DOKU_COOKIE_PARAM
- */
-public function _cookiepath(Doku_Event $event, $param) {
-    global $JSINFO, $conf;
-    $JSINFO['DOKU_COOKIE_PARAM'] = array(
-        'path' => empty($conf['cookiedir']) ? DOKU_REL : $conf['cookiedir'],
-        'secure' => $conf['securecookie'] && is_ssl()
-    );
-}
 </code>
@@ Line 209: / Line 191: @@
 ===== Handle JSON ajax request =====
-An action plugin that register the [[devel:event:ajax_call_unknown]] event, you can handle your own ajax requests. Here a sample how you can return JSON to your javascript. Plugin name is  ''example''.
+An action plugin that register the [[devel:event:ajax_call_unknown|AJAX_CALL_UNKNOWN]] event, you can handle your own ajax requests. Here a sample how you can return JSON to your javascript. Plugin name is  ''example''.
 Create an [[Action Plugin]] which should contain:
 <code php lib/plugin/example/action.php>
-/*
+use dokuwiki\Extension\ActionPlugin;
- * plugin should use this method to register its handlers
+use dokuwiki\Extension\EventHandler;
- * with the dokuwiki's event controller
+use dokuwiki\Extension\Event;
- */
-function register(Doku_Event_Handler $controller) {
+class action_plugin_example extends ActionPlugin {
-    $controller->register_hook('AJAX_CALL_UNKNOWN', 'BEFORE', $this,'_ajax_call');
-}
+    /**
+     * plugin should use this method to register its handlers
+     * with the dokuwiki's event controller
+     */
+    public function register(EventHandler $controller) {
+        $controller->register_hook('AJAX_CALL_UNKNOWN', 'BEFORE', $this, 'ajaxCall');
+    }
-/**
+    /**
- * handle ajax requests
+     * handle ajax requests
- */
+     */
-function _ajax_call(Doku_Event $event, $param) {
+    public function ajaxCall(Event $event) {
-    if ($event->data !== 'plugin_example') {
+        if ($event->data !== 'plugin_example') {
-        return;
+            return;
-    }
+        }
-    //no other ajax call handlers needed
+        //no other ajax call handlers needed
-    $event->stopPropagation();
+        $event->stopPropagation();
-    $event->preventDefault();
+        $event->preventDefault();
-    //e.g. access additional request variables
+        //e.g. access additional request variables
-    global $INPUT; //available since release 2012-10-13 "Adora Belle"
+        global $INPUT;
-    $name = $INPUT->str('name')) {
+        $name = $INPUT->str('name');
-    //data
+        //data
-    $data = array();
+        $data = [];
-    //json library of DokuWiki
+        //set content type
-    require_once DOKU_INC . 'inc/JSON.php';
+        header('Content-Type: application/json');
-    $json = new JSON();
+        echo json_encode($data);
+    }
-    //set content type
-    header('Content-Type: application/json');
-    echo $json->encode($data);
 }
 </code>
@@ Line 295: / Line 280: @@
 Example:
 <code php>
+global $INPUT;
 // we are parsing a submitted comment...
-if (isset($_REQUEST['comment'])) {
+if ($INPUT->has('comment')) {
     return false;
 }
@@ Line 302: / Line 289: @@
 ===== Sending popularity data =====
-[[devel:develonly]] -- //(this feature isn't released yet. Is has been [[https://github.com/splitbrain/dokuwiki/pull/1150|merged]] in master on 27th May 2015)//
+Since release 2015-08-10 "Detritus"
-/!\ As a plugin developer, beware: since popularity data is public, you must not send sensitive information with this feature /!\
+:!: As a plugin developer, beware: since popularity data is public, you must not send sensitive information with this feature.
 The [[plugin:popularity]] plugin already gather the number of time a plugin is installed on an instance of Dokuwiki.
-It also let the possibility to developers, to send more data about usage. It can be used by plugins developers to know if a given obsolete feature is still used. To do it, you need to subscribe to the [[devel:event:PLUGIN_POPULARITY_DATA_SETUP|PLUGIN_POPULARITY_DATA_SETUP]] event. This event contains a key-value array. You should add a key which is the name of your plugin. The value should be either a string, or a key-value array itself (in this latter case, the data will be sent with the key ''<plugin-name>_<key>'')
+It also let the possibility to developers, to send more data about usage. It can be used by plugins developers to know if a given obsolete feature is still used. To do it, you need to subscribe to the [[devel:event:PLUGIN_POPULARITY_DATA_SETUP]] event. This event contains a key-value array. You should add a key which is the name of your plugin. The value should be either a string, or a key-value array itself (in this latter case, the data will be sent with the key ''<plugin-name>_<key>'')
 Example:
 <code php action.php>
-public function register(Doku_Event_Handler $controller) {
+use dokuwiki\Extension\ActionPlugin;
-  $controller->register_hook('PLUGIN_POPULARITY_DATA_SETUP', 'AFTER', $this, 'usage_data');
+use dokuwiki\Extension\EventHandler;
-}
+use dokuwiki\Extension\Event;
+class action_plugin_example extends ActionPlugin {
+    public function register(EventHandler $controller) {
+        $controller->register_hook('PLUGIN_POPULARITY_DATA_SETUP', 'AFTER', $this, 'usageData');
+    }
-public function usage_data(Doku_Event $event){
+    public function usageData(Event $event){
-  $event->data['my_plugin_name'] = 'my usage data';
+        $event->data['my_plugin_name'] = 'my usage data';
- //or: $event->data['my_plugin_name'] = array ('k1' => 'v1', 'k2' => 'v2');
+    /* or:
+        $event->data['my_plugin_name'] = [
+            'k1' => 'v1',
+            'k2' => 'v2'
+        ];
+    */
+    }
 }
 </code>
-FIXME link to a plugin which uses this feature
+A plugin which uses this feature is the [[plugin:nspages]] Plugin.