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