Differences

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

--- devel:common_plugin_functions [2008-10-28 00:34] – 70.103.232.219
+++ devel:common_plugin_functions [2023-02-28 22:24] – 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]], [[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 [[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 =====
+Please refer to [[Configuration]] for more info. The additional files used by plugins are:
+  * ''<dokuwiki>/lib/plugins/<pluginname>/''\\ \\
+    * ''conf/default.php''
+      * contains the [[configuration#default settings]] for the plugin
+      * 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]]
+> 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 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 =====
+  * ''getPluginType()'' --- return the plugin type, e.g. ''syntax'', ''admin'' or ''action''.
+  * ''getPluginName()'' --- return the plugin name
+  * ''getPluginComponent()'' --- return the plugin component name
+===== Localization =====
+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()]]''
+Please see the developer info about [[devel:localization]], inclusive javascript localization and examples.
+===== 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($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($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($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]]