Differences

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

--- devel:helper_plugins [2009-03-21 04:18] – efege
+++ devel:helper_plugins [2022-09-18 23:12] (current) – [How to Write a Helper Plugin] Klap-in
@@ Line 1: / Line 1: @@
 ====== Helper Plugins ======
-Helper plugins make it simple for plugin developers to use functionality of other, existing plugins. For example to display a list of wiki pages, there's no need to reinvent the wheel. - Instead use the [[plugin:pagelist|Pagelist Plugin]]. Take a look at the list of [[doku>plugins?plugintype=16|existing helper plugins]].
+Helper plugins make it simple for plugin developers to use functionality of other, existing plugins. For example to display a list of wiki pages, there's no need to reinvent the wheel. - Instead use the [[plugin:pagelist|Pagelist Plugin]]. Take a look at the list of [[plugintype>16#extension__table|helper plugins]].
+===== How to Use a Helper Plugin =====
-===== How to Use a Helper Plugin =====
 Helper plugins can be used from another plugin in a simple manner.
 <code php>
-$tag = $this->loadHelper('tag', true);
+$tag = $this->loadHelper('tag'); // or $this->loadHelper('tag', true);
 if($tag) {
@@ Line 13: / Line 12: @@
 </code>
-''loadHelper()'' is a method of the base ''DokuWiki_Plugin'' class inherited by all plugins but syntax plugins. It takes two parameters, while the second is optional. The first parameter is the name of the wanted helper plugin. The second indicates if an error message should be displayed in case loading the helper plugin fails (this message isn't localized and can't be localized currently).
+The ''[[xref>loadHelper|loadHelper($name, $showmsg = true)]]'' is a method inherited by all plugins. It takes two parameters, while the second is optional.
+    * The first parameter is the name of the wanted helper plugin.
+    * The second indicates if an error message should be displayed in case loading the helper plugin fails (this message isn't localized and can't be localized currently).
-If you want to use a helper plugin in a syntax plugin you have to use the ''plugin_load()'' function. It takes two parameters, the first is the plugin type, and the second the name of the plugin you like to use. Additionally ''plugin_isdisabled()'' can be used to check if a plugin is available or not.
+As alternative, you can use the general code for loading plugin components:
+You have to use the ''[[xref>plugin_load|plugin_load($type, $name)]]'' function. It takes two parameters:
+  * the first is the plugin type,
+  * and the second the name of the plugin you like to use.
+Additionally ''[[xref>plugin_isdisabled|plugin_isdisabled($name)]]'' can be used to check if a plugin is available or not.
 <code php>
 if(!plugin_isdisabled('tag')) {
-    $tag =& plugin_load('helper', 'tag');
+    $tag = plugin_load('helper', 'tag');
     $entries = $tag->tagRefine($entries, $refine);
+}
+</code>
+====Reusing of plugin objects ====
+Default DokuWiki reuses instances of its plugins. This can be prevented by adding a ''isSingleton()'' function to the plugin class. See [[common plugin functions#instantiating]].
+For example, the [[plugin:Sqlite|Sqlite helper]] keeps separate instances for every call.
+<code php>
+class helper_plugin_sqlite extends DokuWiki_Plugin {
+    ...
+    /**
+     * Keep separate instances for every call to keep database connections
+     */
+    public function isSingleton() {
+        return false;
+    }
+    ...
+}
+</code>
+So you can have more database instances:
+<code php>
+if(!plugin_isdisabled('sqlite')) {
+    $DBIa = plugin_load('helper', 'sqlite');
+    if($DBIa) {
+        $DBIa->init('testa',dirname(__FILE__).'/db/');
+    }
+    $DBIb = plugin_load('helper', 'sqlite');
+    ...
 }
 </code>
@@ Line 26: / Line 62: @@
 ===== How to Write a Helper Plugin =====
-A helper plugin component is a class ''helper_plugin_<plugin name>'' to extend ''DokuWiki_Plugin'' in a file called ''helper.php'' in the plugin's main directory. It should support the following standard methods:
+A Helper Plugin //Example// needs:
+  * class name  ''helper_plugin_example''
+  * which extends [[xref>DokuWiki_Plugin]]((defined in ''[[xref>inc/plugin.php]]'')).
+  * to be stored in a file ''lib/plugins/example/helper.php''.
+Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more helper components refer to [[plugin file structure]].
-==== getInfo() ====
+===Required functions===
-Like other plugin types, helper plugin's ''getInfo()'' method should return an array with info about author name
+  * **''public getMethods()''** Returns info about the methods supported
-and email, plugin date, name, description and URL.
+  * **''public <helper methods>()''** Your public Helper methods, listed by getMethods()
+  * **''protected <protected methods()''** (optional) When you need protected/private methods
+===Inherited functions===
+  * See [[common plugin functions]] for inherited functions available to all plugins. e.g. localisation, configuration and introspection.
 ==== getMethods() ====
-Helper plugins should also return info about the methods supported. ''getMethods()'' should return an array of methods, each of them with an array of method name, description, parameters and return value. Parameters and return values are arrays with parameter description as key and PHP object type as value.
+Helper plugins should also return info about the methods supported. ''[[xref>getMethods()]]'' should return an array of methods, each of them with an array of method name, description, parameters and return value. Parameters and return values are arrays with parameter description as key and PHP object type as value.
 Example:
 <code php>
-  function getMethods(){
+public function getMethods() {
     $result = array();
     $result[] = array(
-      'name'   => 'getThreads',
+        'name' => 'getThreads',
-      'desc'   => 'returns pages with discussion sections, sorted by recent comments',
+        'desc' => 'returns pages with discussion sections, sorted by recent comments',
-      'params' => array(
+        'params' => array(
-        'namespace' => 'string',
+            'namespace' => 'string',
-        'number (optional)' => 'integer'),
+            'number (optional)' => 'integer'
-      'return' => array('pages' => 'array'),
+        ),
+        'return' => array('pages' => 'array'),
     );
     // and more supported methods...
     return $result;
-  }
+}
 </code>
 ==== Helper Methods ====
-The work is done by methods according to the methods listed in ''getMethods()''. Of course, the helper plugin class can contain more, private methods. It's good practice that names of private methods (not listed in ''getMethods()'') begin with an underscore.
+The work is done by methods according to the methods listed in ''getMethods()''. Of course, the helper plugin class can contain more, private methods. It's good practice that names of private methods begin with an underscore. Also they should not be listed in ''getMethods()''.
+===== Common plugin functions =====
+Some function are shared between the plugins, refer to next sections for info about:
+  * [[common_plugin_functions#Configuration|Plugin configuration settings]]
+  * [[common_plugin_functions#localisation|Localisation]]
+  * Using [[plugin_file_structure#CSS styles]] and [[plugin_file_structure#javascript]]
+===== Further reading =====
+  * [[Plugin programming tips]]
+  * [[plugins|Plugin Development]]
+  * [[plugintype>16#extension__table|Available helper plugins]]