- added more hooks
[squirrelmail.git] / doc / plugin.txt
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.
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
82   left_main_before               src/left_main.php
83   left_main_after                src/left_main.php
84   options_save                   src/options.php  (see note on options)
85   options_link_and_description   src/options.php  (see note on options)
86   logout                         src/signout.php
87   login_before                   src/webmail.php
88   login_verified                 src/webmail.php
89   loading_prefs                  src/load_prefs.php
90   mailbox_index_before           functions/mailbox_display.php
91   mailbox_index_after            functions/mailbox_display.php
92
93
94 Options
95 -------
96
97 It is possible to create your own options sections with plugins.  There are
98 three hooks you will need to use.
99
100 1.  options_link_and_description
101     This creates the link and has a description that are shown on the options
102     page.  This should output HTML that looks like this:
103
104     -----cut here-----  
105       function my_function() {
106          global $color
107          ?>
108          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
109             <tr>
110                <td bgcolor="<? echo $color[9] ?>">
111                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
112                </td>
113             </tr>
114             <tr>
115                <td bgcolor="<? echo $color[0] ?>">
116                   YOUR DESCRIPTION
117                </td>
118             </tr>
119          </table>
120          <?php
121       }
122     -----cut here-----  
123
124 2.  options_save
125     Here is the code that you need to do to save your options in the 
126     preference files or manipulate whatever data you are trying to change
127     through the options section.  You can look at options.php for details 
128     on how this is to be done.
129
130 3.  loading_prefs (optional)
131     If you are wanting to save preferences to the preference files, then
132     you need to do this step as well.  Otherwise if you are manipulating
133     other data, ignore this step.
134
135     You should put the code in here that loads your preferences back
136     into usable variables.  Examples of this can be found in the file
137     src/load_prefs.php