* Added 'motd' hook
[squirrelmail.git] / doc / plugin.txt
CommitLineData
99098885 1$Id$
2
3It is best if you check out the SquirrelMail development FAQ for more
4information. This document may be obsoleted at some point in the future (or
5maybe we'll write a script to get the wiki contents and dump them in here
6automatically).
7
8FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
9Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
10
11
1aaef171 12A FEW NOTES ON THE PLUGIN ARCHITECTURE
13======================================
14
15The plugin architecture of SquirrelMail is designed to make it
16possible to add new features without having to patch SquirrelMail
17itself. At the moment the plugin part of SquirrelMail should be
18considered "alpha" or "beta" quality code.
19
20Until the functionality and code is more stable, be prepared for
21plugins to suddenly stop working.
22
23Functionality like password changing, displaying ads and calendars
24should be possible to add as plugins.
25
26
27The idea
28--------
29
30The idea is to be able to run random code at given places in the
31SquirrelMail code. This random code should then be able to do whatever
32needed to enhance the functionality of SquirrelMail. The places where
33code can be executed are called "hooks".
34
35There are some limitations in what these hooks can do. It is difficult
36to use them to change the layout and to change functionality that
37already is in SquirrelMail.
38
39Some way for the plugins to interact with the help subsystem and
40translations will be provided.
41
42
43The implementation
44------------------
45
46In the main SquirrelMail files the file functions/plugin.php. In
47places where hooks are made available they are executed by calling the
48function do_hook("hookname").
49
50The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"]
51and executes all the functions that are named in that array.
52
53A plugin must reside in a subdirectory in the plugins/ directory. The
54name of the subdirectory is considered the name of the plugin.
55
56To start using a plugin, its name must be added to the $plugins array
57in config.php like this:
58
59 $plugins[0] = "plugin_name";
60
61When a plugin is registered the file plugins/plugin_name/setup.php is
62included and the function squirrelmail_plugin_init_plugin_name is
63called with no parameters.
64
65
66Writing plugins
67---------------
68
69A plugin must consist of at least a file called setup.php. All other
70files the plugin consist of should also be in the plugin directory.
71
72The function squirrelmail_plugin_init_plugin_name is called to
73initalize a plugin. This function could look something like this:
74
75function squirrelmail_plugin_init_demo () {
76 global $squirrelmail_plugin_hooks;
77
78 $squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header";
79 $squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline";
80}
81
82Note that the SquirrelMail files assume that all other SquirrelMail
83files are available as ../directory/file. This means that if some file
84in the plugin directory is requested, it must do a chdir("..") before
85including any of the standard SquirrelMail files.
6b638171 86
87
a3a95e4a 88Hook Data Passed
89----------------
90Hooks, when executed, are called with one parameter, an array of data
91that is passed to the hook. The first element in the array is the name
92of the hook that is being called. Any other elements in the array are
93dependant on the type of hook that is being called.
94
95Some of the information in the array may be changed. By default, the
96plugins should never change data unless it is documented otherwise.
97
98
6b638171 99List of hooks
100-------------
ef3c69f0 101 generic_header functions/page_header.php
102 menuline functions/page_header.php
103 compose_button_row src/compose.php
104 compose_bottom src/compose.php
b3911477 105 compose_form src/compose.php
0e8c1c9a 106 compose_send src/compose.php
ef3c69f0 107 left_main_before src/left_main.php
108 left_main_after src/left_main.php
109 * options_save src/options.php (see note on options)
110 * options_link_and_description src/options.php (see note on options)
111 * options_highlight_bottom src/options_highlight.php
112 * options_personal_bottom src/options_personal.php
113 * options_personal_inside src/options_personal.php
114 * options_personal_save src/options_personal.php
115 * options_display_bottom src/options_display.php
116 * options_display_inside src/options_display.php
3751dc7f 117 * options_display_save src/options_display.php
ef3c69f0 118 * options_folders_bottom src/options_folders.php
119 * options_folders_inside src/options_folders.php
120 * options_folders_save src/options_folders.php
0f101579 121 & options_identities_process src/options_identities.php
122 & options_identities_top src/options_identities.php
123 & options_identities_renumber src/options_identities.php (multiple places)
124 & options_identities_table src/options_identities.php
125 & options_identities_buttons src/options_identities.php
ef3c69f0 126 logout src/signout.php
cf6df86f 127 logout_above_text src/signout.php
ef3c69f0 128 login_before src/webmail.php
129 login_verified src/webmail.php
130 loading_prefs src/load_prefs.php
131 mailbox_index_before functions/mailbox_display.php
132 mailbox_index_after functions/mailbox_display.php
3751dc7f 133 mailbox_form_before functions/mailbox_display.php
1ffd5e31 134 subject_link functions/mailbox_display.php
99098885 135 motd src/right_main.php
ef3c69f0 136 right_main_after_header src/right_main.php
137 right_main_bottom src/right_main.php
138 login_top src/login.php
139 login_bottom src/login.php
441f2d33 140 html_top src/read_body.php
ef3c69f0 141 read_body_top src/read_body.php
142 read_body_bottom src/read_body.php
441f2d33 143 html_bottom src/read_body.php
7137f80f 144 read_body_header src/read_body.php
9736fafe 145 read_body_header_right src/read_body.php
ef3c69f0 146 search_before_form src/search.php
147 search_after_form src/search.php
148 search_bottom src/search.php
149 help_top src/help.php
150 help_bottom src/help.php
151 help_chapter src/help.php
3937dc89 152 addrbook_html_search_below src/addrbook_search_html.php
ef3c69f0 153 addressbook_bottom src/addressbook.php
a3a95e4a 154 ^ attachment $type0/$type1 functions/mime.php (see note on attachments)
155
06ad27a2 156
ef3c69f0 157(*) Options
158-----------
159There are two ways to do options for your plugin. First, you can incorporate it
160into an existing section of the preferences (Display, Personal, or Folders).
161The second way, you create your own section that they can choose from and it
162displays its own range of options.
163
164
165First: Integrating into existing options
166-----------------------------------------
167There are two hooks you need to use for this one:
168
1691. options_YOUCHOOSE_inside
170 This is the code that goes inside the table for the section you choose. Since
171 it is going inside an existing table, it must be in this form:
172 ------cut here-------
173 <tr>
174 <td>
175 OPTION_NAME
176 </td>
177 <td>
178 OPTION_INPUT
179 </td>
180 </tr>
181 ------cut here-------
182
1832. options_YOUCHOOSE_save
184 This is the code that saves your preferences into the users' preference
185 file. For an example of how to do this, see src/options.php.
186
187
188Second: Create your own section
189-------------------------------
6b638171 190It is possible to create your own options sections with plugins. There are
191three hooks you will need to use.
192
1931. options_link_and_description
194 This creates the link and has a description that are shown on the options
57945c53 195 page. This should output HTML that looks like this. Make sure to read
196 the section on outputting your own pages.
6b638171 197
198 -----cut here-----
57945c53 199 function my_plugin_name_my_function() {
6b638171 200 global $color
201 ?>
202 <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
203 <tr>
204 <td bgcolor="<? echo $color[9] ?>">
205 <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
206 </td>
207 </tr>
208 <tr>
209 <td bgcolor="<? echo $color[0] ?>">
210 YOUR DESCRIPTION
211 </td>
212 </tr>
213 </table>
214 <?php
215 }
216 -----cut here-----
217
2182. options_save
219 Here is the code that you need to do to save your options in the
220 preference files or manipulate whatever data you are trying to change
221 through the options section. You can look at options.php for details
222 on how this is to be done.
223
2243. loading_prefs (optional)
225 If you are wanting to save preferences to the preference files, then
226 you need to do this step as well. Otherwise if you are manipulating
227 other data, ignore this step.
228
229 You should put the code in here that loads your preferences back
230 into usable variables. Examples of this can be found in the file
231 src/load_prefs.php
a3a95e4a 232
233
0f101579 234(&) Identity Hooks
235------------------
236Some hooks are passed special information in the array of arguments. See
237the SpamCop plugin for how to use them.
238
239options_identities_process
240 [0] = Hook's name
241 [1] = Should I run the SaveUpdateFunction() (alterable)
242
243options_identities_renumber
244 [0] = Hook's name
245 [1] = Renumber it from ('default' or 1 through # idents - 1)
246 [2] = Renumber it to (same thing)
247
248options_identities_table
249 [0] = Hook's name
250 [1] = Color of table (use it like <tr<?PHP echo $Info[1]?>> in your
251 plugin)
252 [2] = Is this an empty section?
253 [3] = What is the 'post' value?
254
255options_identities_buttons
256 [0] = Hook's name
257 [1] = Is this an empty section (the one at the end of the list)?
258 [2] = What is the 'post' value?
259
260
a3a95e4a 261(^) Attachment Hooks
262--------------------
263When a message has attachments, this hook is called with the MIME types. For
264instance, a .zip file hook is "attachment application/x-zip". The hook should
265probably show a link to do a specific action, such as "Verify" or "View" for a
266.zip file.
267
268This is a breakdown of the data passed in the array to the hook that is called:
269
270 [0] = Hook's name ('attachment text/plain')
271 [1] = Array of links of actions (more below) (Alterable)
272 [2] = Used for returning to mail message (startMessage)
273 [3] = Used for finding message to display (id)
274 [4] = Mailbox name, urlencode()'d (urlMailbox)
275 [5] = Entity ID inside mail message (ent)
276 [6] = Default URL to go to when filename is clicked on (Alterable)
ef30bf50 277 [7] = Filename that is displayed for the attachment
278 [8] = Sent if message was found from a search (where)
279 [9] = Sent if message was found from a search (what)
a3a95e4a 280
281To set up links for actions, you assign them like this:
282
283 $Args[1]['your_plugin_name']['href'] = 'URL to link to';
284 $Args[1]['your_plugin_name']['text'] = 'What to display';
441f2d33 285
57945c53 286
287Outputting Your Own Pages
288-------------------------
289
290Often, when you want to provide your own customized options screen or create
291another web page instead of just using standard hooks, you will be creating
292your own .php files. An example of this is the attachment_common plugin's
293image.php file.
294
295To make sure that security is maintained and standards are followed, the top
296of your PHP script should look very similar to this:
297
298 <?PHP
299 /* This is my php file.
300 * description goes here.
301 */
302
303 chdir('..');
304 include('../src/validate.php');
305
306The validate.php script will include internationalization support,
307config.php variables, strings.php functions, and also authenticate that the
308user is truly logged in. Validate.php also calls stripslashes() on incoming
309data (if gpc_magic_quotes() is on). You should never need to worry about
310that stuff again. As a warning, this has only really been ironed out in
3111.1.1. If you create/modify a plugin to follow these rules, you must
312mention that it requires SquirrelMail 1.1.1 or later.
313
314After that, if you need further functions, just use
315
316 include('../functions/filename.php');
317
318in your script. Since 1.0.5, it was no longer necessary (nor recommended)
319to use the "if (! isset($filename_php))" syntax.