Differences

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

--- devel:common_plugin_functions [2008-11-07 21:44] – 70.103.232.219
+++ devel:common_plugin_functions [2023-02-28 22:24] (current) – Aleksandr
@@ Line 1: / Line 1: @@
 ====== Common Plugin Functions ======
-Each of the currently implemented [[:DokuWiki]] plugin classes, [[devel:Syntax Plugins|syntax]], [[devel:Admin Plugins|admin]], [[devel:Action Plugins|action]], [[devel:Helper Plugins|helper]] and [[devel:Renderer Plugins|renderer]] provide a common set of methods and properties enabling standard [[#configuration]], [[#introspection]], [[#localisation]] and [[#output]] facilities.  These functions produce their results taking into account local installation settings and specific DokuWiki requirements.
+Each of the currently implemented [[:DokuWiki]] plugin classes, [[devel:Syntax Plugins|syntax]], [[devel:Admin Plugins|admin]], [[devel:Action Plugins|action]], [[devel:Helper Plugins|helper]], [[devel:remote_plugins|remote]] and [[devel:Renderer Plugins|renderer]] provide a common set of methods and properties enabling standard [[#configuration]], [[#introspection]], [[#localization]] and [[#output]] facilities.  These functions produce their results taking into account local installation settings and specific DokuWiki requirements.
 These functions are declared in the foundation plugin class, ''DokuWiki_Plugin'', defined in ''inc/plugin.php''.
-A summary of the functions and properties are shown below. For full and up-to-date details refer to [[http://dev.splitbrain.org/reference/dokuwiki/lib/plugins/base.php.html|base.php]] in the [[http://dev.splitbrain.org/reference/dokuwiki/|API Reference]] and the source itself in the [[http://dev.splitbrain.org/browse/darcs/dokuwiki|Source Repository]]
+A summary of the functions and properties are shown below. For full and up-to-date details refer to [[xref>inc/plugin.php]] in the [[https://xref.dokuwiki.org/reference/dokuwiki|API Reference]] (search field is mouseover popup on the right) and the DokuWikis source code itself in the [[https://github.com/dokuwiki/dokuwiki|Source Repository]] on Github.
+**Inherited methods** available in all plugins (also see [[xref>inc/plugin.php]]):
+^Name                                                  ^Description ^
+|[[xref>inc/plugin.php#getinfo|getInfo()]]             |Returns associative array with basic information  read from ''plugin.info.txt'' from plugin directory. For more details read [[plugin info]].|
+|[[xref>inc/plugin.php#getconf|getConf()]]             |Returns the value of a named plugin configuration variable. For more details read [[#configuration]] below.|
+|[[xref>inc/plugin.php#getlang|getLang()]]             |Returns text for the supplied key in the current language. Refer [[#localization]] below 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]] below for details.|
+|[[xref>inc/plugin.php#email|email()]]                 |Returns a properly formatted ''mailto:'' link, taking into account the wiki installation's ''mailguard'' setting. (exception: use in syntax plugins ''%%$renderer->emaillink()%%'')|
+|[[xref>inc/plugin.php#external_link|external_link()]] |Returns a properly formatted external link, taking into account wiki config settings. (exception: use in syntax plugins ''%%$renderer->externallink()%%'')|
+|[[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. (exception: not available in syntax plugins)|
+|[[xref>inc/plugin.php#loadhelper|loadHelper()]]       |Loads a given helper plugin (if the plugin is enabled). Details and example in [[helper plugins]].|
+|[[xref>inc/plugin.php#getplugintype|getPluginType()]] |Returns the plugin type, e.g. ''syntax'', ''admin'' or ''action''. |
+|[[xref>inc/plugin.php#getpluginname|getPluginName()]] |Returns the plugin name|
+|[[xref>inc/plugin.php#getplugincomponent|getPluginComponent()]] |Returns the plugin component name, for a component, an empty string'|
+The following additional methods can be **overridden** when required:
+^Name                                                  ^Description ^
+|[[xref>inc/plugin.php#isSingleton|isSingleton()]]     |Default DokuWiki reuses instances of the plugin. This can be prevented by adding the function ''isSingleton()'' that returns false.|
 ===== Configuration =====
-  * ''$conf'' --- An array containing the plugin's configuration settings, setting => value. It is empty until populated by ''loadConfig()''
+Please refer to [[Configuration]] for more info. The additional files used by plugins are:
-  * ''$configloaded'' --- bool, set to true by ''loadConfig()'' after it has established the current settings
+  * ''<dokuwiki>/lib/plugins/<pluginname>/''\\ \\
-  * ''getConf($setting)'' --- return the value of ''$setting'', will call ''loadConfig()'' if required.
+    * ''conf/default.php''
-  * ''loadConfig()'' --- merges local settings with the plugin's default settings and populates ''$this->conf'' array.
+      * contains the [[configuration#default settings]] for the plugin
-  * ''readDefaultSettings()'' --- reads the default settings file, ''lib/plugins/<plugin_name>/conf/default.php''
+      * accessible via ''$this%%->%%getConf()''
+      * :!: modified settings (configuration changes) are stored within DokuWiki's 'local' settings file **''<dokuwiki>/conf/local.php''**\\ \\
+    * ''conf/metadata.php'' -- [[configuration#config metadata]] describing the settings for use by [[plugin:config|configuration manager]]\\ \\
+    * ''lang/<language>/settings.php'' -- localized strings used in the [[plugin:config|configuration manager]]
-The plugin's configuration settings are stored in the installation local settings file, local.php and in the plugin specific file, default.php (refer plugin [[plugin file structure]]).
+> Use ''conf/metadata.php'' and the localized ''settings.php'' files to tell the [[plugin:config|Configuration Manager]] about the plugin's settings.  E.g. to provide a list of valid values or to flag a setting as a security alert.  All of the metadata settings available to DokuWiki's own configuration settings are useable by plugins, see [[configuration#Configuration Metadata]] for more detail.
-If a plugin handles its configuration through these functions, the wiki admin will be able to manage the settings interactively through the [[plugin:config|Configuration Manager]]. See [[configuration#Configuration Metadata]] to learn more about how to tell the Configuration Manager what to do with your settings.
+If a plugin complies to the above structure the wiki admin will be able to manage the settings interactively through the [[plugin:config|Configuration Manager]].
+===Example===
+Read setting 'sortkey' from config:
+<code php>
+$sort = $this->getConf('sortkey');
+</code>
 ===== Introspection =====
@@ Line 26: / Line 57: @@
-===== Localisation =====
+===== Localization =====
-For information on where the localised strings and files are stored see plugin [[deveL:plugin_file_structure]].
+Localizations are stored in the plugin folder. The next files can be provided:
+  * ''<dokuwiki>/lib/plugins/<pluginname>/''
+    * ''lang/<language>/lang.php'' -- Localized language strings
+      * accessible via ''$this%%->%%[[xref>getLang()]]''\\ \\
+    * ''lang/<language>/settings.php'' -- localized strings used in the configuration manager
+      * Shows up in the [[plugin:config|configuration manager]]\\ \\
+    * ''lang/<language>/<filename>.txt'' -- localized text including DokuWiki markup
+      * accessible via ''$this%%->%%[[xref>locale_xhtml()]]''
-  * ''$lang'' --- An array containing the plugin's localised strings, id => localised string, may contain English strings where a localised version doesn't exist.  It is empty until populated by ''setupLocale()''.
+Please see the developer info about [[devel:localization]], inclusive javascript localization and examples.
-  * ''$localised'' --- bool, set to true by ''setupLocale()'' after it has populated ''$this->lang''.
-  * ''getLang($id)'' --- return the localised string for ''$id'', or English string if localised version doesn't exist.  Will call ''setupLocale()'' if required.
-  * ''locale_xhtml($id)'' --- uses DokuWiki's rendering engine to return xhtml created from the localised file, ''$id'', containing DokuWiki markup.
-  * ''setupLocale()'' --- populates ''$this->lang'' with strings based on localisation settings
+===== Instantiating =====
+Default DokuWiki reuses instances of plugins. This can be prevented by adding the function ''[[xref>isSingleton()]]'' that returns false, so ''plugin_load('<plugin type> '<plugin name>')'' and ''loadHelper('<plugin name>, true)'' will return an new plugin object on each call.
+<code php>
+/**
+ * Return false to prevent DokuWiki reusing instances of the plugin
+ *
+ * @return bool
+ */
+public function isSingleton() {
+    return false;
+}
+</code>
+=====Load Helper plugins=====
+In all plugins Helper plugins can be loaded by ''[[xref>loadHelper|$this->loadHelper('tag', true)]]''. First argument is helper plugin name, second argument if English error message should be displayed (cannot be localized). It will reuses the instance of the requested plugin, so it will return always the same plugin object. To prevent this behaviour see [[#instantiating]] above.
+It loads a given helper plugin if the plugin is enabled. Details and examples in [[helper plugins]].
+===Example===
+Load helper of the tag plugin:
+<code php>
+//get the instance of Tag Helper
+$tag = $this->loadHelper('tag', true);
+if($tag) {
+    $entries = $tag->tagRefine($entries, $refine);
+}
+</code>
+===== Load other plugins =====
+If you want to use another plugin in your 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.
+It will return a plugin object. Default this object is the unique plugin instance stored by the plugin controller, but when the requested plugin is marked as not singleton by ''[[#Instantiating|isSingleton()]]'' it will return a new plugin object at each request.
+Or use instead the additional parameter options of [[xref>plugin_load|plugin_load($type, $name, $new = false, $disabled = false)]].
+Load helper plugin component from Tag plugin, which has only one helper component:
+<code php>
+if(!plugin_isdisabled('tag')) {
+    $tag =& plugin_load('helper', 'tag');
+    if($tag) {
+        $entries = $tag->tagRefine($entries, $refine);
+    }
+}
+</code>
+Or load syntax plugin component from Data plugin, which has several syntax components, so specifying of the component needed:
+<code php>
+if(!plugin_isdisabled('data')) {
+    $table =& plugin_load('syntax', 'data_table');
+    if($table) {
+        $hasfilter = $table->hasRequestFilter();
+    }
+}
+</code>
 ===== Output ====
-  * ''email()'' --- output an email link using the installation's email obfuscation settings.
+  * ''%%email($email, $name='', $class='', $more='')%%''\\ Output an email link using the installation's email obfuscation settings. Default class ''mail'' is added to emaillink, ''$class'' overrides this. ''$more'' adds extra attributes to email link.
-  * ''external_link()'' --- output an external link using the installation's target settings.
+  * ''%%external_link($link, $title='', $class='', $target='', $more='')%%'' \\ Output an external link using the installation's target settings, setting the optional argument will overrides it. ''$more'' adds extra attributes to the link.
-  * ''render()'' --- uses the parser to parse and output a string containing wiki markup.
+  * ''render($text, $format='xhtml')'' \\ Uses the parser to parse and output a string containing wiki markup. Very inefficient for small pieces of data -- try not to use
+===== See also =====
+  * [[Plugin file structure]]
+  * [[Plugin file structure#CSS styles]] and [[Plugin file structure#javascript]]
+  * [[Plugin programming tips]]
+  * [[devel:plugins|Plugin Development]]