[squirrelmail.git] / doc / plugin.txt

A FEW NOTES ON THE PLUGIN ARCHITECTURE
======================================

The plugin architecture of SquirrelMail is designed to make it
possible to add new features without having to patch SquirrelMail
itself. At the moment the plugin part of SquirrelMail should be
considered "alpha" or "beta" quality code.

Until the functionality and code is more stable, be prepared for
plugins to suddenly stop working.

Functionality like password changing, displaying ads and calendars
should be possible to add as plugins.


The idea
--------

The idea is to be able to run random code at given places in the
SquirrelMail code. This random code should then be able to do whatever
needed to enhance the functionality of SquirrelMail. The places where
code can be executed are called "hooks".

There are some limitations in what these hooks can do. It is difficult
to use them to change the layout and to change functionality that
already is in SquirrelMail.

Some way for the plugins to interact with the help subsystem and
translations will be provided.


The implementation
------------------

In the main SquirrelMail files the file functions/plugin.php. In
places where hooks are made available they are executed by calling the
function do_hook("hookname").

The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"]
and executes all the functions that are named in that array.

A plugin must reside in a subdirectory in the plugins/ directory. The
name of the subdirectory is considered the name of the plugin.

To start using a plugin, its name must be added to the $plugins array
in config.php like this:

  $plugins[0] = "plugin_name";

When a plugin is registered the file plugins/plugin_name/setup.php is
included and the function squirrelmail_plugin_init_plugin_name is
called with no parameters.


Writing plugins
---------------

A plugin must consist of at least a file called setup.php. All other
files the plugin consist of should also be in the plugin directory.

The function squirrelmail_plugin_init_plugin_name is called to
initalize a plugin. This function could look something like this:

function squirrelmail_plugin_init_demo () {
  global $squirrelmail_plugin_hooks;

  $squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header";
  $squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline";
}

Note that the SquirrelMail files assume that all other SquirrelMail
files are available as ../directory/file. This means that if some file
in the plugin directory is requested, it must do a chdir("..") before
including any of the standard SquirrelMail files.


List of hooks
-------------
  generic_header                 functions/page_header.php
  menuline                       functions/page_header.php
  compose_button_row             src/compose.php
  compose_bottom                 src/compose.php
  left_main_before               src/left_main.php
  left_main_after                src/left_main.php
  options_save                   src/options.php  (see note on options)
  options_link_and_description   src/options.php  (see note on options)
  options_highlight_bottom       src/options_highlight.php
  options_personal_bottom        src/options_personal.php
  options_display_bottom         src/options_display.php
  options_folders_bottom         src/options_folders.php
  logout                         src/signout.php
  login_before                   src/webmail.php
  login_verified                 src/webmail.php
  loading_prefs                  src/load_prefs.php
  mailbox_index_before           functions/mailbox_display.php
  mailbox_index_after            functions/mailbox_display.php
  right_main_after_header        src/right_main.php
  right_main_bottom              src/right_main.php
  login_top                      src/login.php
  login_bottom                   src/login.php
  read_body_top                  src/read_body.php
  read_body_bottom               src/read_body.php
  search_before_form             src/search.php
  search_after_form              src/search.php
  search_bottom                  src/search.php
  help_top                       src/help.php
  help_bottom                    src/help.php
  help_chapter                   src/help.php
  abook_html_search_below        src/addrbook_search_html.php
  addressbook_bottom		 src/addressbook.php
   
Options
-------

It is possible to create your own options sections with plugins.  There are
three hooks you will need to use.

1.  options_link_and_description
    This creates the link and has a description that are shown on the options
    page.  This should output HTML that looks like this:

    -----cut here-----  
      function my_function() {
         global $color
         ?>
         <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
            <tr>
               <td bgcolor="<? echo $color[9] ?>">
                  <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
               </td>
            </tr>
            <tr>
               <td bgcolor="<? echo $color[0] ?>">
                  YOUR DESCRIPTION
               </td>
            </tr>
         </table>
         <?php
      }
    -----cut here-----  

2.  options_save
    Here is the code that you need to do to save your options in the 
    preference files or manipulate whatever data you are trying to change
    through the options section.  You can look at options.php for details 
    on how this is to be done.

3.  loading_prefs (optional)
    If you are wanting to save preferences to the preference files, then
    you need to do this step as well.  Otherwise if you are manipulating
    other data, ignore this step.

    You should put the code in here that loads your preferences back
    into usable variables.  Examples of this can be found in the file
    src/load_prefs.php
Commit	Line	Data
1aaef171	1	A FEW NOTES ON THE PLUGIN ARCHITECTURE
	2	======================================
	3
	4	The plugin architecture of SquirrelMail is designed to make it
	5	possible to add new features without having to patch SquirrelMail
	6	itself. At the moment the plugin part of SquirrelMail should be
	7	considered "alpha" or "beta" quality code.
	8
	9	Until the functionality and code is more stable, be prepared for
	10	plugins to suddenly stop working.
	11
	12	Functionality like password changing, displaying ads and calendars
	13	should be possible to add as plugins.
	14
	15
	16	The idea
	17	--------
	18
	19	The idea is to be able to run random code at given places in the
	20	SquirrelMail code. This random code should then be able to do whatever
	21	needed to enhance the functionality of SquirrelMail. The places where
	22	code can be executed are called "hooks".
	23
	24	There are some limitations in what these hooks can do. It is difficult
	25	to use them to change the layout and to change functionality that
	26	already is in SquirrelMail.
	27
	28	Some way for the plugins to interact with the help subsystem and
	29	translations will be provided.
	30
	31
	32	The implementation
	33	------------------
	34
	35	In the main SquirrelMail files the file functions/plugin.php. In
	36	places where hooks are made available they are executed by calling the
	37	function do_hook("hookname").
	38
	39	The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"]
	40	and executes all the functions that are named in that array.
	41
	42	A plugin must reside in a subdirectory in the plugins/ directory. The
	43	name of the subdirectory is considered the name of the plugin.
	44
	45	To start using a plugin, its name must be added to the $plugins array
	46	in config.php like this:
	47
	48	$plugins[0] = "plugin_name";
	49
	50	When a plugin is registered the file plugins/plugin_name/setup.php is
	51	included and the function squirrelmail_plugin_init_plugin_name is
	52	called with no parameters.
	53
	54
	55	Writing plugins
	56	---------------
	57
	58	A plugin must consist of at least a file called setup.php. All other
	59	files the plugin consist of should also be in the plugin directory.
	60
	61	The function squirrelmail_plugin_init_plugin_name is called to
	62	initalize a plugin. This function could look something like this:
	63
	64	function squirrelmail_plugin_init_demo () {
65	global $squirrelmail_plugin_hooks;
66
67	$squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header";
68	$squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline";
69	}
70
71	Note that the SquirrelMail files assume that all other SquirrelMail
72	files are available as ../directory/file. This means that if some file
73	in the plugin directory is requested, it must do a chdir("..") before
74	including any of the standard SquirrelMail files.
6b638171	75
	76
	77	List of hooks
	78	-------------
	79	generic_header functions/page_header.php
	80	menuline functions/page_header.php
	81	compose_button_row src/compose.php
d7d3c4d4	82	compose_bottom src/compose.php
6b638171	83	left_main_before src/left_main.php
	84	left_main_after src/left_main.php
	85	options_save src/options.php (see note on options)
	86	options_link_and_description src/options.php (see note on options)
d7d3c4d4	87	options_highlight_bottom src/options_highlight.php
	88	options_personal_bottom src/options_personal.php
	89	options_display_bottom src/options_display.php
	90	options_folders_bottom src/options_folders.php
6b638171	91	logout src/signout.php
	92	login_before src/webmail.php
	93	login_verified src/webmail.php
	94	loading_prefs src/load_prefs.php
	95	mailbox_index_before functions/mailbox_display.php
	96	mailbox_index_after functions/mailbox_display.php
06ad27a2	97	right_main_after_header src/right_main.php
	98	right_main_bottom src/right_main.php
	99	login_top src/login.php
	100	login_bottom src/login.php
	101	read_body_top src/read_body.php
	102	read_body_bottom src/read_body.php
	103	search_before_form src/search.php
	104	search_after_form src/search.php
	105	search_bottom src/search.php
	106	help_top src/help.php
	107	help_bottom src/help.php
	108	help_chapter src/help.php
d7d3c4d4	109	abook_html_search_below src/addrbook_search_html.php
ed7f686e	110	addressbook_bottom src/addressbook.php
06ad27a2	111
6b638171	112	Options
	113	-------
	114
	115	It is possible to create your own options sections with plugins. There are
	116	three hooks you will need to use.
	117
	118	1. options_link_and_description
	119	This creates the link and has a description that are shown on the options
	120	page. This should output HTML that looks like this:
	121
	122	-----cut here-----
	123	function my_function() {
	124	global $color
	125	?>
	126	<table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
	127	<tr>
	128	<td bgcolor="<? echo $color[9] ?>">
	129	<a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
	130	</td>
	131	</tr>
	132	<tr>
	133	<td bgcolor="<? echo $color[0] ?>">
	134	YOUR DESCRIPTION
	135	</td>
	136	</tr>
	137	</table>
	138	<?php
	139	}
	140	-----cut here-----
	141
	142	2. options_save
	143	Here is the code that you need to do to save your options in the
	144	preference files or manipulate whatever data you are trying to change
	145	through the options section. You can look at options.php for details
	146	on how this is to be done.
	147
	148	3. loading_prefs (optional)
	149	If you are wanting to save preferences to the preference files, then
	150	you need to do this step as well. Otherwise if you are manipulating
	151	other data, ignore this step.
	152
	153	You should put the code in here that loads your preferences back
	154	into usable variables. Examples of this can be found in the file
	155	src/load_prefs.php