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