🌍
English
Differences
This shows you the differences between two versions of the page.
|
dev:extensions:plugins [2006/11/10 01:33] rvelices |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | Plugins are intended to extend the functionnality of PhpWebGallery. | ||
| - | Plugins are available in PhpWebGallery starting with version 1.7. Starting with this version PhpWebGallery provides an architecture allowing plugins to hook themselves in the core. This version also allows site administrators to install/activate/deactivate and uninstall plugins. | ||
| - | ====== Managing plugins ====== | ||
| - | FIXME | ||
| - | |||
| - | ====== Plugin developpement ====== | ||
| - | |||
| - | ===== Plugin architecture ===== | ||
| - | A plugin can hook into the core of PWG by registering **event handlers** with PWG. An **event handler** is nothing more than a function that PWG 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. PWG will automatically call your function when a user is deleted. | ||
| - | |||
| - | PWG will trigger **actions** and **events**. The only difference between **actions** and **events** 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 PWG). | ||
| - | |||
| - | An example of **action** 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 PWG, but you can modify any global variable in order to change the general behaviour. | ||
| - | |||
| - | An example of **event** is 'render_user_comment_content'. PWG 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(':)', 'http://example.com/icon_smile.gif', $content); | ||
| - | return $content; //<-- NOTE: this is how you return the value to PWG | ||
| - | } | ||
| - | </code> | ||
| - | |||
| - | ===== Taxonomy of a plugin ===== | ||
| - | FIXME | ||
| - | |||
| - | ===== 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 PWG, 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> | ||
| - | // class 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> | ||
| - | |||
| - | ==== Code size ==== | ||
| - | When PWG 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. | ||
| - | |||
| - | ==== 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. | ||
| - | |||
| - | ===== Quick Tips & tricks ===== | ||
| - | ==== Add content to html <head> element output ==== | ||
| - | <code php> | ||
| - | function my_add() | ||
| - | { | ||
| - | global $template; | ||
| - | $url_to_me = get_root_url().'plugins/my_plugin/'; | ||
| - | // add a stylesheet | ||
| - | $template->assign_block_vars('head_element', array ( | ||
| - | 'CONTENT' => '<link rel="stylesheet" type="text/css" href="'.$url_to_me.'style.css">' | ||
| - | )); | ||
| - | // add a javascript | ||
| - | $template->assign_block_vars('head_element', array ( | ||
| - | 'CONTENT' => '<script type="text/javascript" src="'.$url_to_me.'my_script.js"></script>' | ||
| - | )); | ||
| - | } | ||
| - | |||
| - | add_event_handler('loc_end_page_header', 'my_add' ); | ||
| - | </code> | ||
| - | ==== Add content to the administration page ==== | ||
| - | <code php> | ||
| - | add_event_handler('plugin_admin_menu', 'pwg_wants_menu' ); | ||
| - | |||
| - | function pwg_wants_menu() | ||
| - | { | ||
| - | add_plugin_admin_menu( "The title to be displayed", 'my_admin'); | ||
| - | } | ||
| - | |||
| - | function my_admin($my_url) | ||
| - | {//$my_url is the url that should be put as action attribute for a form html document | ||
| - | global $template; | ||
| - | $template->set_filenames( array( | ||
| - | 'something_here' => dirname(__FILE__).'/admin.tpl' //<- some template in plugin directory | ||
| - | ) ); | ||
| - | ... DO WHATEVER YOU WANT AND CALL $template->assign_... | ||
| - | $template->assign_var_from_handle( 'PLUGIN_ADMIN_CONTENT', 'something_here'); | ||
| - | } | ||
| - | |||
| - | </code> | ||