This is an old revision of the document!


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.

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. 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:

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 PWG 
}

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 /*
Version: 1.0
Plugin Name: Short Name (shown on the plugins management page)
Plugin URI: http://www.somesite.com/where_i_keep_the_plugin_documentation_and_download_links
Author: My Name
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 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

// 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() { ... }
  }
//  New  object creation
  $myObj = new MyClass();
// I call the methode 'on_delete_user' in the new object 
  add_event_handler('delete_user', array(&$myObj, 'on_delete_user') );

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.

What can be done when main.inc.php is executed ?

PWG will include main.inc.php sometime 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 or set_plugin_data. For all other cases, you must hook the event 'init'. The 'init' action is triggered only once and at that point the common initialization of the current page is finished
  • the variable $plugin['id'] is defined and contains the identifier of your plugin. You will need this id when calling set_plugin_data

Quick Tips & tricks

Add content to html <head> element output

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' );

Add content to the administration page

In your file plugins/my_plugin/main.inc.php

add_event_handler('get_admin_plugin_menu_links', 'pwg_wants_menu' );
 
function pwg_wants_menu($menu)
{
  array_push($menu,
      array(
        'NAME' => 'The title to be displayed',
        'URL' => get_admin_plugin_menu_link(dirname(__FILE__).'/the_super_admin_page.php')
      )
    );
  return $menu;
}

In your file plugins/my_plugin/the_super_admin_page.php

if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
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( 'ADMIN_CONTENT', 'something_here');
}

In the same way you can add links to the advanced features page (event name is 'get_admin_advanced_features_links') or maintenance page (event name is 'get_admin_maintenance_links').

Plugin maintainance

When a plugin is installed, activated, deactivated or uninstalled, PWG will allow you to take some special steps by executing some php code. If you have a php file named maintain.inc.php in your plugin directory, PWG will include this file and will call one of the fuctions plugin_install, plugin_activate, plugin_deactivate or plugin_uninstall depending on the user action. The signature of these functions should be like:

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) { ... }
 
Back to top
dev/extensions/plugins.1315514850.txt.gz · Last modified: 2011/09/08 20:47 by plg
 
 
github twitter newsletter Donate Piwigo.org © 2002-2024 · Contact