Differences

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

Link to this comparison view

dev:extensions:plugins [2014/06/09 17:37]
mistic100 [Plugin developpement]
— (current)
Line 1: Line 1:
-====== Plugin developpement ====== 
- 
-Plugins are designed to extend the Piwigo features. 
- 
-You will find in the [[http://piwigo.org/dev/browser/extensions/skeleton/trunk|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. 
-<code php>register_event_handler('delete_user', 'my_action_on_delete_user');</code> 
-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: 
-<code 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  
-} 
-</code> 
- 
-A complete reference of core triggers is available at **tool/triggers_list.php** into your Piwigo installation, or [[http://piwigo.us/dev/mistic100/triggers|here]] (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: 
-<code 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 
-?> 
-</code> 
-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 
-<code 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') ); 
-</code> 
- 
-==== 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**. 
- 
-<code 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'); 
-</code> 
- 
- 
-==== 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** : 
-<code 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() { ... } 
-} 
-</code> 
- 
-=== Piwigo 2.6 and bellow === 
-Maintenance functions are declared in **maintain.inc.php** and are all optional : 
-<code 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) { ... } 
-</code> 
  
 
Back to top
dev/extensions/plugins.1402335460.txt.gz · Last modified: 2014/06/09 17:37 by mistic100
 
 
github twitter newsletter Donate Piwigo.org © 2002-2024 · Contact