99098885 |
1 | $Id$ |
2 | |
3 | It is best if you check out the SquirrelMail development FAQ for more |
b2978b37 |
4 | information. This document is currently quite out of date. Help writing |
5 | plugins is easily obtained by posting to the squirrelmail-plugins mailing |
6 | list. (See details about mailing lists on the website) |
99098885 |
7 | |
8 | FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ |
9 | Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins |
10 | |
11 | |
1aaef171 |
12 | A FEW NOTES ON THE PLUGIN ARCHITECTURE |
13 | ====================================== |
14 | |
97ca984f |
15 | The plugin architecture of SquirrelMail is designed to make it possible to |
16 | add new features without having to patch SquirrelMail itself. Functionality |
17 | like password changing, displaying ads and calendars should be possible to |
18 | add as plugins. |
1aaef171 |
19 | |
20 | |
21 | The idea |
22 | -------- |
23 | |
24 | The idea is to be able to run random code at given places in the |
25 | SquirrelMail code. This random code should then be able to do whatever |
26 | needed to enhance the functionality of SquirrelMail. The places where |
27 | code can be executed are called "hooks". |
28 | |
29 | There are some limitations in what these hooks can do. It is difficult |
30 | to use them to change the layout and to change functionality that |
31 | already is in SquirrelMail. |
32 | |
33 | Some way for the plugins to interact with the help subsystem and |
34 | translations will be provided. |
35 | |
36 | |
37 | The implementation |
38 | ------------------ |
39 | |
40 | In the main SquirrelMail files the file functions/plugin.php. In |
41 | places where hooks are made available they are executed by calling the |
97ca984f |
42 | function do_hook('hookname'). |
1aaef171 |
43 | |
97ca984f |
44 | The do_hook traverses the array $squirrelmail_plugin_hooks['hookname'] |
1aaef171 |
45 | and executes all the functions that are named in that array. |
46 | |
47 | A plugin must reside in a subdirectory in the plugins/ directory. The |
48 | name of the subdirectory is considered the name of the plugin. |
49 | |
50 | To start using a plugin, its name must be added to the $plugins array |
51 | in config.php like this: |
52 | |
97ca984f |
53 | $plugins[0] = 'plugin_name'; |
1aaef171 |
54 | |
55 | When a plugin is registered the file plugins/plugin_name/setup.php is |
56 | included and the function squirrelmail_plugin_init_plugin_name is |
57 | called with no parameters. |
58 | |
59 | |
60 | Writing plugins |
61 | --------------- |
62 | |
63 | A plugin must consist of at least a file called setup.php. All other |
64 | files the plugin consist of should also be in the plugin directory. |
65 | |
66 | The function squirrelmail_plugin_init_plugin_name is called to |
67 | initalize a plugin. This function could look something like this: |
68 | |
69 | function 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 | |
76 | Note that the SquirrelMail files assume that all other SquirrelMail |
77 | files are available as ../directory/file. This means that if some file |
97ca984f |
78 | in the plugin directory is requested, it must do a chdir('..') before |
1aaef171 |
79 | including any of the standard SquirrelMail files. |
6b638171 |
80 | |
81 | |
a3a95e4a |
82 | Hook Data Passed |
83 | ---------------- |
84 | Hooks, when executed, are called with one parameter, an array of data |
85 | that is passed to the hook. The first element in the array is the name |
86 | of the hook that is being called. Any other elements in the array are |
87 | dependant on the type of hook that is being called. |
88 | |
89 | Some of the information in the array may be changed. By default, the |
90 | plugins should never change data unless it is documented otherwise. |
91 | |
92 | |
6b638171 |
93 | List 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 | ----------- |
153 | There are two ways to do options for your plugin. First, you can incorporate it |
154 | into an existing section of the preferences (Display, Personal, or Folders). |
155 | The second way, you create your own section that they can choose from and it |
156 | displays its own range of options. |
157 | |
158 | |
159 | First: Integrating into existing options |
160 | ----------------------------------------- |
161 | There are two hooks you need to use for this one: |
162 | |
163 | 1. 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 | |
177 | 2. 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 | |
182 | Second: Create your own section |
183 | ------------------------------- |
6b638171 |
184 | It is possible to create your own options sections with plugins. There are |
185 | three hooks you will need to use. |
186 | |
187 | 1. 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 | |
212 | 2. 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 | |
218 | 3. 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 | ------------------ |
230 | Some hooks are passed special information in the array of arguments. See |
231 | the SpamCop plugin for how to use them. |
232 | |
233 | options_identities_process |
234 | [0] = Hook's name |
235 | [1] = Should I run the SaveUpdateFunction() (alterable) |
236 | |
237 | options_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 | |
242 | options_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 | |
249 | options_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 | -------------------- |
257 | When a message has attachments, this hook is called with the MIME types. For |
258 | instance, a .zip file hook is "attachment application/x-zip". The hook should |
259 | probably show a link to do a specific action, such as "Verify" or "View" for a |
260 | .zip file. |
261 | |
262 | This 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 | |
275 | To 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 |
280 | It's also possible to specify a hook as "attachment type0/*", |
281 | for example "attachment text/*". This hook will be executed whenever there's |
282 | no more specific rule available for that type. |
283 | |
57945c53 |
284 | |
285 | Outputting Your Own Pages |
286 | ------------------------- |
287 | |
288 | Often, when you want to provide your own customized options screen or create |
289 | another web page instead of just using standard hooks, you will be creating |
290 | your own .php files. An example of this is the attachment_common plugin's |
291 | image.php file. |
292 | |
293 | To make sure that security is maintained and standards are followed, the top |
294 | of 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 | |
304 | The validate.php script will include internationalization support, |
305 | config.php variables, strings.php functions, and also authenticate that the |
1e63b430 |
306 | user is truly logged in. validate.php also calls stripslashes() on incoming |
57945c53 |
307 | data (if gpc_magic_quotes() is on). You should never need to worry about |
308 | that stuff again. As a warning, this has only really been ironed out in |
309 | 1.1.1. If you create/modify a plugin to follow these rules, you must |
310 | mention that it requires SquirrelMail 1.1.1 or later. |
311 | |
312 | After that, if you need further functions, just use |
313 | |
314 | include('../functions/filename.php'); |
315 | |
316 | in your script. Since 1.0.5, it was no longer necessary (nor recommended) |
317 | to use the "if (! isset($filename_php))" syntax. |