copy of the page from DokuWiki

Plugin-developpement.md

@@ -0,0 +1,201 @@
+# Plugin developpement
+
+Plugins are designed to extend the Piwigo features.
+
+You will find in the
+[Skeleton](https://github.com/Piwigo/Piwigo-Skeleton) a good bootstrap for you plugin.
+
+## Plugin architecture
+
+A plugin can hook into the core of Piwigo by registering **event
+handlers** with Piwigo. An **event handler** is nothing more than a
+function that Piwigo will call.
+
+``` php
+register_event_handler('delete_user', 'my_action_on_delete_user');
+```
+
+In this case, 'delete_user' is the name of the event to which the plugin
+will hook. Piwigo will automatically call your function when a user is
+deleted.
+
+Piwigo will trigger **notices** and **changes**. The only difference
+from a coding perspective is that you are required to return a value in
+the case of an event (this return value will be used later by Piwigo).
+
+An example of **trigger_notify** is 'delete_user' or 'delete_elements'.
+Your plugin can take any required actions when a user is deleted by
+registering an event handler for 'delete_user'. While handling actions
+you are not expected to directly return a value that will be used by
+Piwigo, but you can modify any global variable in order to change the
+general behaviour.
+
+An example of **trigger_change** is 'render_user_comment_content'.
+Piwigo will give in input the raw content of a comment, you can modify
+it at your will (for example allow bbcode or add smilies) and return the
+value:
+
+``` php
+register_event_handler('render_user_comment_content', 'my_function');
+function my_function($content)
+{
+  $content = str_replace(':)', '<img src="http://example.com/icon_smile.gif" alt=":)" />', $content);
+  return $content; //<-- NOTE: this is how you return the value to Piwigo 
+}
+```
+
+A complete reference of core triggers is available at
+**tools/triggers_list.php** into your Piwigo installation, or
+[here](http://piwigo.us/dev/mistic100/triggers) (not always up to date).
+
+## Taxonomy of a plugin
+
+The minimal plugin is a file called main.inc.php (in the directory
+plugins/my_plugin if your plugin is called my_plugin). It MUST have the
+header below:
+
+``` php
+<?php /*
+Version: 1.0
+Plugin Name: Short Name (shown on the plugins management page)
+Plugin URI: http://piwigo.org/ext/extension_view.php?eid=1234
+Author: My Name
+Author URI: http://my-website.com
+Description: This a little bit longer description is also shown on the plugins management page
+*/
+
+// REAL PLUGIN CODE GOES HERE
+?>
+```
+
+Note that the version number is saved into database, so keep it short
+and in a good style ( 1.1 or 1.a.b ...)
+
+## DO and DONT
+
+While nobody will impose a coding standard here are some things you
+should consider:
+
+### Name collisions
+
+PHP does not allow several function names to be defined at the same
+time. Keep in mind that your plugin will need to work with other plugins
+activated, as well as the core of Piwigo, so please avoid function names
+such as 'send', 'delete', 'delete_user'... You have two options:
+
+A. Prefix function names with something unique:
+'download_multi_delete_user', 'download_multi_delete_elements', etc...
+
+B. Use objects and classes
+
+``` php
+// static EXAMPLE
+class MyClass
+{
+  function on_delete_user() { ... }
+}
+add_event_handler('delete_user', array('MyClass', 'on_delete_user'));
+
+// object EXAMPLE
+class MyClass
+{
+  function on_delete_user() { ... }
+}
+
+$myObj = new MyClass();
+add_event_handler('delete_user', array(&$myObj, 'on_delete_user') );
+```
+
+### Extensions compatibility
+
+If your plugin adds or load custom tpl, to the public part, you should
+let to the theme the ability to define their own tpl file. If your
+plugin defines a new index page, like *index.php?/xxxx*,
+`$page['title']`, `$page['body_id']` and `$page['section']` needs to be
+defined with custom values by the plugin, using the
+**loc_end_section_init** trigger. This is useful for other plugins and
+themes, in order to declare what type of page is currently running.
+
+### Code size
+
+When Piwigo loads the plugins, it will include every main.inc.php. Don't
+put in your main.inc.php 3000 lines of code just to add a page on the
+administration menu. Split you main.inc.php in several files and feel
+free to add include_once inside functions defined in main.inc.php as
+much as you want.
+
+Also use the lazy loading feature of **add_event_handler** (Piwigo 2.7
+and above)
+
+``` php
+// without lazy loading, necessary code is loaded immediately
+include_once(SKELETON_PATH . 'include/events.inc.php');
+
+add_event_handler('rare_trigger', 'my_function');
+
+// with lazy loading, code loaded only id needed
+add_event_handler('rare_trigger', 'my_function', 50,
+  SKELETON_PATH . 'include/events.inc.php');
+```
+
+### Do not 'die()'
+
+If you call functions such as die or exit within your plugin, keep in
+mind that the final user will have no other choice than modify his
+config file so that no plugin is loaded or modify the #plugins table (if
+he knows that the cause is your plugin). So please whenever something is
+wrong, the plugins should display a message for the administrators and
+silently do nothing.
+
+### What can be done when main.inc.php is executed ?
+
+Piwigo will include main.inc.php at some point during the
+initialization. At this time, do not make any assumption that the user
+is logged in, the language is defined, the template is created, etc. The
+only safe assumptions are:
+
+-   the connection to the database has been established
+-   the configuration has been loaded
+-   you can safely call add_event_handler, remove_event_handler. For all
+    other cases, you must hook the event 'init'. The 'init' event is
+    triggered only once and at that point the common initialization of
+    the current page is finished
+
+## Plugin maintenance
+
+When a plugin is installed, activated, deactivated or uninstalled,
+Piwigo will allow you to take some special steps by executing some php
+code. If you have a php file named **maintain.inc.php** or
+**maintain.class.php** in your plugin directory, Piwigo will include
+this file and will call some maintenance functions.
+
+#### Piwigo 2.7 and above
+
+Maintenance functions have to be declared in **maintain.class.php** by
+class extending **PluginMaintain** :
+
+``` php
+/**
+ * PLUGINID must be replaced by the directory name of your plugin
+ */
+class PLUGINID_maintain extends PluginMaintain
+{
+  function install($plugin_version, &$errors=array()) { ... }
+  function activate($plugin_version, &$errors=array()) { ... }
+  function update($old_version, $new_version, &$errors=array()) { ... }
+  function deactivate() { ... }
+  function uninstall() { ... }
+}
+```
+
+#### Piwigo 2.6 and bellow
+
+Maintenance functions are declared in **maintain.inc.php** and are all
+optional :
+
+``` php
+function plugin_install($plugin_id, $plugin_version, &$errors) { ... }
+function plugin_activate($plugin_id, $plugin_version, &$errors) { ... }
+function plugin_deactivate($plugin_id) { ... }
+function plugin_uninstall($plugin_id) { ... }
+```