99098885 |
1 | $Id$ |
2 | |
b6522eb5 |
3 | In addition to this document, please check out the SquirrelMail |
4 | development FAQ for more information. Also, help writing plugins |
9cd2ae7d |
5 | is easily obtained by posting to the squirrelmail-plugins mailing |
b2978b37 |
6 | list. (See details about mailing lists on the website) |
99098885 |
7 | |
e07525be |
8 | FAQ -> http://www.squirrelmail.org/wiki/DeveloperFAQ |
b6522eb5 |
9 | Plugin Development -> |
e07525be |
10 | http://www.squirrelmail.org/wiki/DevelopingPlugins |
99098885 |
11 | |
12 | |
1aaef171 |
13 | A FEW NOTES ON THE PLUGIN ARCHITECTURE |
14 | ====================================== |
15 | |
b6522eb5 |
16 | The plugin architecture of SquirrelMail is designed to make it possible |
17 | to add new features without having to patch SquirrelMail itself. |
18 | Functionality like password changing, displaying ads and calendars should |
9cd2ae7d |
19 | be possible to add as plugins. |
1aaef171 |
20 | |
21 | |
9cd2ae7d |
22 | The Idea |
1aaef171 |
23 | -------- |
24 | |
25 | The idea is to be able to run random code at given places in the |
26 | SquirrelMail code. This random code should then be able to do whatever |
27 | needed to enhance the functionality of SquirrelMail. The places where |
28 | code can be executed are called "hooks". |
29 | |
30 | There are some limitations in what these hooks can do. It is difficult |
31 | to use them to change the layout and to change functionality that |
32 | already is in SquirrelMail. |
33 | |
34 | Some way for the plugins to interact with the help subsystem and |
35 | translations will be provided. |
36 | |
37 | |
9cd2ae7d |
38 | The Implementation |
1aaef171 |
39 | ------------------ |
40 | |
9cd2ae7d |
41 | The plugin jumping off point in the main SquirrelMail code is in the |
42 | file functions/plugin.php. In places where hooks are made available, |
b6522eb5 |
43 | they are executed by calling the function do_hook('hookname'). The |
44 | do_hook function then traverses the array |
45 | $squirrelmail_plugin_hooks['hookname'] and executes all the functions |
46 | that are named in that array. Those functions are placed there when |
47 | plugins register themselves with SquirrelMail as discussed below. A |
48 | plugin may add its own internal functions to this array under any |
9cd2ae7d |
49 | hook name provided by the SquirrelMail developers. |
1aaef171 |
50 | |
51 | A plugin must reside in a subdirectory in the plugins/ directory. The |
b6522eb5 |
52 | name of the subdirectory is considered to be the name of the plugin. |
9cd2ae7d |
53 | (The plugin will not function correctly if this is not the case.) |
1aaef171 |
54 | |
55 | To start using a plugin, its name must be added to the $plugins array |
56 | in config.php like this: |
57 | |
9cd2ae7d |
58 | $plugins[0] = 'plugin_name'; |
1aaef171 |
59 | |
9cd2ae7d |
60 | When a plugin is registered, the file plugins/plugin_name/setup.php is |
61 | included and the function squirrelmail_plugin_init_plugin_name() is |
b6522eb5 |
62 | called with no parameters. That function is where the plugin may |
9cd2ae7d |
63 | register itself against any hooks it wishes to take advantage of. |
1aaef171 |
64 | |
65 | |
9cd2ae7d |
66 | WRITING PLUGINS |
67 | =============== |
68 | |
b6522eb5 |
69 | All plugins must contain a file called setup.php and must include a |
70 | function called squirrelmail_plugin_init_plugin_name() therein. Since |
71 | including numerous plugins can slow SquirrelMail performance |
72 | considerably, the setup.php file should contain little else. Any |
73 | functions that are registered against plugin hooks should do little |
9cd2ae7d |
74 | more than call another function in a different file. |
75 | |
b6522eb5 |
76 | Any other files used by the plugin should also be placed in the |
77 | plugin directory (or subdirectory thereof) and should contain the |
9cd2ae7d |
78 | bulk of the plugin logic. |
1aaef171 |
79 | |
9cd2ae7d |
80 | The function squirrelmail_plugin_init_plugin_name() is called to |
b6522eb5 |
81 | initalize a plugin. This function could look something like this (if |
9cd2ae7d |
82 | the plugin was named "demo" and resided in the directory plugins/demo/): |
1aaef171 |
83 | |
b6522eb5 |
84 | function squirrelmail_plugin_init_demo () |
9cd2ae7d |
85 | { |
86 | global $squirrelmail_plugin_hooks; |
1aaef171 |
87 | |
9cd2ae7d |
88 | $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; |
89 | $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline'; |
90 | } |
91 | |
92 | Please note that as of SquirrelMail 1.5.0, this function will no longer |
93 | be called at run time and will instead be called only once at configure- |
b6522eb5 |
94 | time. Thus, the inclusion of any dynamic code (anything except hook |
9cd2ae7d |
95 | registration) here is strongly discouraged. |
1aaef171 |
96 | |
9cd2ae7d |
97 | In this example, the "demo" plugin should also have two other functions |
98 | in its setup.php file called plugin_demo_header() and plugin_demo_menuline(). |
99 | The first of these might look something like this: |
100 | |
101 | function plugin_demo_header() |
102 | { |
103 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
104 | plugin_demo_header_do(); |
1aaef171 |
105 | } |
106 | |
9cd2ae7d |
107 | The function called plugin_demo_header_do() would be in the file called |
108 | functions.php in the demo plugin directory and would contain the plugin's |
109 | core logic for the "generic_header" hook. |
110 | |
111 | |
112 | Including Other Files |
113 | --------------------- |
114 | |
b6522eb5 |
115 | A plugin may need to reference functionality provided in other |
9cd2ae7d |
116 | files, and therefore need to include those files. Most of the |
117 | core SquirrelMail functions are already available to your plugin |
118 | unless it has any files that are requested directly by the client |
b6522eb5 |
119 | browser (custom options page, etc.). In this case, you'll need |
9cd2ae7d |
120 | to make sure you include the files you need (see below). |
121 | |
122 | Note that as of SquirrelMail 1.4.0, all files are accessed using a |
123 | constant called SM_PATH that always contains the relative path to |
b6522eb5 |
124 | the main SquirrelMail directory. This constant is always available |
125 | for you to use when including other files from the SquirrelMail core, |
126 | your own plugin, or other plugins, should the need arise. If any of |
127 | your plugin files are requested directly from the client browser, |
6b7579a0 |
128 | you will need to include the SquirrelMail initialization file which is present |
129 | since SquirrelMail 1.5.2. |
9cd2ae7d |
130 | |
6b7579a0 |
131 | The SquirrelMail initialization file which is located in include/init.php does |
132 | take care of setting up the session, defining the constants like SM_PATH and |
133 | it take care of including a minimum set of required files. |
9cd2ae7d |
134 | |
6b7579a0 |
135 | The files which are included depends on which file the hook operates on. |
136 | For all hook locations the following files are included: |
9cd2ae7d |
137 | |
6b7579a0 |
138 | require(SM_PATH . 'functions/global.php'); |
139 | require(SM_PATH . 'config/config.php'); |
140 | require(SM_PATH . 'functions/plugin.php'); |
141 | require(SM_PATH . 'include/constants.php'); |
142 | require(SM_PATH . 'include/languages.php'); |
143 | require(SM_PATH . 'functions/display_messages.php' ); |
144 | require(SM_PATH . 'functions/page_header.php'); |
145 | require(SM_PATH . 'functions/html.php'); |
146 | |
147 | Except login.php also the following files are included: |
148 | require(SM_PATH . 'functions/prefs.php'); |
149 | |
150 | require(SM_PATH . 'functions/db_prefs.php'); |
151 | OR |
152 | require(SM_PATH . 'functions/file_prefs.php'); |
153 | (dependent of the configured preference backend) |
154 | |
155 | For all files except login.php and redirect.php also the following files are |
156 | included: |
157 | require(SM_PATH . 'functions/strings.php'); |
158 | require(SM_PATH . 'functions/auth.php'); |
159 | |
160 | Because the use of "require" in include/init.php your plugin will fail if it |
161 | tries to include the file in the plugin as well. |
162 | Be aware of that. |
163 | |
164 | To include the init.php file add the following in your plugin: |
165 | |
166 | /** |
167 | * Include the SquirrelMail initialization file. |
168 | */ |
169 | require('../../include/init.php'); |
170 | |
171 | Other files then the files mentioned above can be included by your plugin |
172 | like this: |
173 | |
174 | include_once(SM_PATH . 'functions/imap_general.php'); |
9cd2ae7d |
175 | |
176 | When including files, please make sure to use the include_once() function |
6b7579a0 |
177 | and NOT include(), require() because they can cause fatal errors when other |
178 | plugins or SquirrelMail files include the same file. |
179 | If you use require_once() instead of include_once() then if something cause |
180 | wrong with the include then php will raise a fatal error. That's the reason |
181 | plugins MUST use include_once() instead of require_once(). |
9cd2ae7d |
182 | |
183 | The files that you may need to include in a plugin will vary greatly |
184 | depending upon what the plugin is designed to do. For files that are |
6b7579a0 |
185 | requested directly by the client browser, you MUST includey the file |
186 | include/init.php |
187 | , since it will set up the SquirrelMail environment automatically. |
188 | It will ensure the the user has been authenticated and is currently logged in, |
189 | load all user preferences, include internationalization support, |
190 | call stripslashes() on all incoming data (if magic_quotes_gpc is on), and |
191 | initialize and include all other basic SquirrelMail resources and functions. |
192 | You may see other plugins that directly include other SquirrelMail files, but |
b6522eb5 |
193 | that is no longer necessary and is a hold-over from older SquirrelMail |
9cd2ae7d |
194 | versions. |
6b638171 |
195 | |
e398ba12 |
196 | List of files, that are included by include/validate.php (If SquirrelMail |
867fed37 |
197 | version is not listed, files are included from v.1.3.2.). This table is |
198 | specific to SquirrelMail 1.3.2 - 1.5.1. Script layout was changed in 1.5.2. |
e398ba12 |
199 | 1. class/mime.class.php |
200 | 1.1. class/mime/Rfc822Header.class.php |
201 | 1.2. class/mime/MessageHeader.class.php |
202 | 1.3. class/mime/AddressStructure.class.php |
203 | 1.4. class/mime/Message.class.php |
204 | 1.5. class/mime/SMimeMessage.class.php |
205 | 1.6. class/mime/Disposition.class.php |
206 | 1.7. class/mime/Language.class.php |
207 | 1.8. class/mime/ContentType.class.php |
208 | 2. functions/global.php |
6b7579a0 |
209 | * fixes differences between php 4.0.x and 4.1+ globals (only in 1.4.x). |
e07525be |
210 | * undoes magic_quotes_gpc=on sanitizing |
211 | * sets $PHP_SELF (since 1.5.1) |
212 | * starts session |
e398ba12 |
213 | 3. functions/strings.php |
e07525be |
214 | 3.1. functions/global.php |
215 | 3.2. plugins/compatibility/functions.php (compatibility v.2.0.4+, requires |
216 | code patching) |
217 | * sets squirrelmail version variable and constant. |
218 | * sets $PHP_SELF (before 1.5.1) |
e398ba12 |
219 | 4. config/config.php |
220 | 4.1. config/config_local.php (from 1.4.0rc1) |
221 | 5. functions/i18n.php |
222 | 5.1. functions/global.php (from 1.4.0) |
e07525be |
223 | * reads 'squirrelmail_language' cookie |
224 | * loads $languages (since 1.5.1 $languages array is built from |
225 | locale/*/setup.php files) |
226 | * loads own gettext functions, if php gettext is unavailable |
e398ba12 |
227 | 6. functions/auth.php |
228 | 7. include/load_prefs.php |
229 | 7.1. include/validate.php |
230 | 7.2. functions/prefs.php |
e07525be |
231 | 7.2.1. functions/global.php (sqgetGlobalVar() function) |
6b7579a0 |
232 | 7.2.2. functions/plugin.php (do_hook_function() function,, |
e07525be |
233 | since 1.4.4 and 1.5.1, see 7.3) |
234 | 7.2.3. $prefs_backend (only in 1.4.3 and 1.5.0) |
235 | do_hook_function('prefs_backend') (since 1.4.4 and 1.5.1) |
236 | functions/db_prefs.php |
237 | functions/file_prefs.php |
238 | 7.2.3.1. functions/display_messages.php |
239 | (loaded only by file_prefs.php) |
240 | 7.2.3.2. files loaded by plugin that uses 'prefs_backend' hook |
e398ba12 |
241 | 7.3. functions/plugin.php |
242 | 7.3.1. functions/global.php (from 1.4.0 and 1.5.0) |
243 | 7.3.2. functions/prefs.php (from 1.5.1) |
6b7579a0 |
244 | 7.3.3. plugins/*/setup.php files for enabled plugins. |
e07525be |
245 | * starts all squirrelmail_plugin_init_pluginname functions |
e398ba12 |
246 | 7.4. functions/constants.php |
247 | 7.5. do_hook('loading_prefs') |
e07525be |
248 | 7.5.1. files loaded by plugins that use 'loading_prefs' hook |
e398ba12 |
249 | 8. functions/page_header.php |
250 | 8.1. functions/strings.php |
251 | 8.2. functions/html.php |
252 | 8.3. functions/imap_mailbox.php |
253 | 8.3.1. functions/imap_utf7_local.php |
254 | 8.4. functions/global.php |
e07525be |
255 | 9. functions/prefs.php (already loaded. see 7.2) |
256 | |
6b7579a0 |
257 | Since SquirrelMail 1.5.1 functions/global.php file must be loaded before |
258 | setting any own global variables. If variables are set before loading |
259 | functions/global.php library, they can be corrupted in PHP register_globals=On |
46cbf588 |
260 | setups. |
261 | |
6b638171 |
262 | |
9cd2ae7d |
263 | Hook Types: Parameters and Return Values |
264 | ----------------------------------------- |
265 | |
f4fd89e0 |
266 | Hooks, when executed, are called with differing parameters and may or may |
267 | not take return values, all depending on the type of hook being called and |
268 | the context in which it is being used. On the source side (where the hook |
269 | call originates), all hooks have at least one parameter, which is the |
270 | name of the hook. After that, things get complicated. |
271 | |
272 | do_hook |
273 | ------- |
274 | Most hook calls don't pass any data and don't ask for anything back. |
275 | These always use the do_hook call. A limited number of do_hook calls do |
276 | pass some extra parameters, in which case your plugin may modify the |
277 | given data if you do so by reference. It is not necessary to return |
278 | anything from your function in such a case; modifying the parameter |
279 | data by reference is what does the job (although the hook call itself |
280 | (in the source) must grab the return value for this to work). Note |
281 | that in this case, the parameter to your hook function will be an array, |
282 | the first element simply being the hook name, followed by any other |
283 | parameters that may have been included in the actual hook call in the |
284 | source. Modify parameters with care! |
285 | |
286 | do_hook_function |
287 | ---------------- |
288 | This hook type was intended to be the main hook type used when the |
289 | source needs to get something back from your plugin. It is somewhat |
290 | limited in that it will only use the value returned from the LAST |
291 | plugin registered against the hook. The source for this hook might |
292 | use the return value for internal purposes, or might expect you to |
293 | provide text or HTML to be sent to the client browser (you'll have to |
294 | look at its use in context to understand how you should return values |
295 | here). The parameters that your hook function gets will be anything |
296 | you see AFTER the hook name in the actual hook call in the source. |
297 | These cannot be changed in the same way that the do_hook parameters |
298 | can be. |
299 | |
300 | concat_hook_function |
301 | -------------------- |
302 | This is a newer hook type meant to address the shortcomings of |
303 | do_hook_function; specifically in that it uses the return values of |
304 | all plugins registered against the hook. In order to do so, the |
305 | return value is assumed to be a string, which is just piled on top |
306 | of whatever it got from the other plugins working on the same hook. |
307 | Again, you'll have to inspect the source code to see how such data |
308 | is put to use, but most of the time, it is used to create a string |
309 | of HTML to be inserted into the output page. The parameters that |
310 | your hook function will get are the same as for the do_hook_function; |
311 | they are anything AFTER the hook name in the actual hook call in the |
312 | source. |
313 | |
efea59ed |
314 | boolean_hook_function |
315 | --------------------- |
f4fd89e0 |
316 | The newest of the SquirrelMail hooks, this type is used to let all |
317 | plugins registered against the hook to "vote" for some action. What |
318 | that action is is entirely dependent on how the hook is used in the |
319 | source (look for yourself). Plugins make their "vote" by returning |
320 | TRUE or FALSE. This hook may be configured to "tally votes" in one |
321 | of three ways. This configuration is done with the third parameter |
322 | in the hook call in the source: |
323 | > 0 -- Any one or more TRUEs will override any FALSEs |
324 | < 0 -- Any one or more FALSEs will override any TRUEs |
325 | = 0 -- Majority wins. Ties are broken in this case with |
326 | the last parameter in the hook call in the source. |
327 | Your hook function will get the second paramter in the hook call in |
328 | the source as its parameter (this might be an array if multiple values |
329 | need to be passed). |
a3a95e4a |
330 | |
f4fd89e0 |
331 | See below for further discussion of special hook types and the values |
a3a95e4a |
332 | |
333 | |
9cd2ae7d |
334 | List of Hooks |
6b638171 |
335 | ------------- |
ef3c69f0 |
336 | |
9cd2ae7d |
337 | This is a list of all hooks currently available in SquirrelMail, ordered |
338 | by file. Note that this list is accurate as of June 17, 2003 (should be |
339 | close to what is contained in release 1.4.1, plus or minus a hook or two), |
340 | but may be out of date soon thereafter. You never know. ;-) |
6b638171 |
341 | |
9cd2ae7d |
342 | Hook Name Found In Called With(#) |
343 | --------- -------- -------------- |
df788686 |
344 | abook_init functions/addressbook.php do_hook |
345 | abook_add_class functions/addressbook.php do_hook |
9cd2ae7d |
346 | loading_constants functions/constants.php do_hook |
54067ccd |
347 | logout_error functions/display_messages.php do_hook |
348 | error_box functions/display_messages.php concat_hook |
9cd2ae7d |
349 | get_pref_override functions/file_prefs.php hook_func |
350 | get_pref functions/file_prefs.php hook_func |
3df61ef3 |
351 | & options_identities_process functions/identity.php do_hook |
352 | &% options_identities_renumber functions/identity.php do_hook |
9cd2ae7d |
353 | special_mailbox functions/imap_mailbox.php hook_func |
f030c853 |
354 | % rename_or_delete_folder functions/imap_mailbox.php hook_func |
f9937b7c |
355 | folder_status (since 1.5.1) functions/imap_mailbox.php hook_func |
356 | functions/imap_general.php hook_func |
9cd2ae7d |
357 | mailbox_index_before functions/mailbox_display.php do_hook |
358 | mailbox_form_before functions/mailbox_display.php do_hook |
359 | mailbox_index_after functions/mailbox_display.php do_hook |
360 | check_handleAsSent_result functions/mailbox_display.php do_hook |
361 | subject_link functions/mailbox_display.php concat_hook |
c5aaf57f |
362 | mailbox_display_buttons functions/mailbox_display.php do_hook |
7c788b1c |
363 | mailbox_display_button_action functions/mailbox_display.php hook_func |
9cd2ae7d |
364 | message_body functions/mime.php do_hook |
f030c853 |
365 | ^ attachment $type0/$type1 functions/mime.php do_hook |
9ad17edb |
366 | attachments_bottom functions/mime.php hook_func |
c4115032 |
367 | decode_body functions/mime.php hook_func |
9cd2ae7d |
368 | generic_header functions/page_header.php do_hook |
369 | menuline functions/page_header.php do_hook |
9d0239af |
370 | prefs_backend functions/prefs.php hook_func |
9cd2ae7d |
371 | loading_prefs include/load_prefs.php do_hook |
372 | addrbook_html_search_below src/addrbook_search_html.php do_hook |
373 | addressbook_bottom src/addressbook.php do_hook |
a61f899d |
374 | ! compose_form src/compose.php do_hook |
9cd2ae7d |
375 | compose_bottom src/compose.php do_hook |
376 | compose_button_row src/compose.php do_hook |
377 | compose_send src/compose.php do_hook |
9b8f1003 |
378 | compose_send_after src/compose.php do_hook |
a4409e0d |
379 | configtest (since 1.5.2) src/configtest.php boolean_hook |
9cd2ae7d |
380 | folders_bottom src/folders.php do_hook |
381 | help_top src/help.php do_hook |
382 | help_chapter src/help.php do_hook |
383 | help_bottom src/help.php do_hook |
7022cc97 |
384 | left_main_after_each_folder src/left_main.php concat_hook |
9cd2ae7d |
385 | left_main_before src/left_main.php do_hook |
386 | left_main_after src/left_main.php do_hook |
387 | login_cookie src/login.php do_hook |
388 | login_top src/login.php do_hook |
16436d92 |
389 | login_form src/login.php concat_hook |
390 | (was do_hook before 1.5.1) |
9cd2ae7d |
391 | login_bottom src/login.php do_hook |
f030c853 |
392 | * optpage_set_loadinfo src/options.php do_hook |
393 | * optpage_loadhook_personal src/options.php do_hook |
394 | * optpage_loadhook_display src/options.php do_hook |
395 | * optpage_loadhook_highlight src/options.php do_hook |
396 | * optpage_loadhook_folder src/options.php do_hook |
397 | * optpage_loadhook_order src/options.php do_hook |
398 | * options_personal_save src/options.php do_hook |
399 | * options_display_save src/options.php do_hook |
400 | * options_folder_save src/options.php do_hook |
401 | * options_save src/options.php do_hook |
402 | * optpage_register_block src/options.php do_hook |
403 | * options_link_and_description src/options.php do_hook |
404 | * options_personal_inside src/options.php do_hook |
405 | * options_display_inside src/options.php do_hook |
406 | * options_highlight_inside src/options.php do_hook |
407 | * options_folder_inside src/options.php do_hook |
408 | * options_order_inside src/options.php do_hook |
409 | * options_personal_bottom src/options.php do_hook |
410 | * options_display_bottom src/options.php do_hook |
411 | * options_highlight_bottom src/options.php do_hook |
412 | * options_folder_bottom src/options.php do_hook |
413 | * options_order_bottom src/options.php do_hook |
414 | * options_highlight_bottom src/options_highlight.php do_hook |
f030c853 |
415 | & options_identities_top src/options_identities.php do_hook |
f030c853 |
416 | & options_identities_table src/options_identities.php concat_hook |
417 | & options_identities_buttons src/options_identities.php concat_hook |
9cd2ae7d |
418 | message_body src/printer_friendly_bottom.php do_hook |
419 | read_body_header src/read_body.php do_hook |
d44e63d5 |
420 | read_body_menu_top src/read_body.php hook_func |
9cd2ae7d |
421 | read_body_menu_bottom src/read_body.php do_hook |
422 | read_body_header_right src/read_body.php do_hook |
9cd2ae7d |
423 | read_body_top src/read_body.php do_hook |
424 | read_body_bottom src/read_body.php do_hook |
9cd2ae7d |
425 | login_before src/redirect.php do_hook |
426 | login_verified src/redirect.php do_hook |
9cd2ae7d |
427 | right_main_after_header src/right_main.php do_hook |
428 | right_main_bottom src/right_main.php do_hook |
429 | search_before_form src/search.php do_hook |
430 | search_after_form src/search.php do_hook |
431 | search_bottom src/search.php do_hook |
432 | logout src/signout.php do_hook |
f63fd5f0 |
433 | message_body (since 1.5.2) src/view_html.php do_hook |
434 | message_body (since 1.5.2) src/view_text.php do_hook |
9cd2ae7d |
435 | webmail_top src/webmail.php do_hook |
d44e63d5 |
436 | webmail_bottom src/webmail.php concat_hook |
9cd2ae7d |
437 | logout_above_text src/signout.php concat_hook |
f030c853 |
438 | O info_bottom plugins/info/options.php do_hook |
b6522eb5 |
439 | |
9cd2ae7d |
440 | % = This hook is used in multiple places in the given file |
441 | # = Called with hook type (see below) |
442 | & = Special identity hooks (see below) |
443 | ^ = Special attachments hook (see below) |
444 | * = Special options hooks (see below) |
f030c853 |
445 | O = Optional hook provided by a particular plugin |
a61f899d |
446 | ! = See below for notes about working with the compose page's <form> tag |
6b638171 |
447 | |
6b638171 |
448 | |
9cd2ae7d |
449 | (#) Called With |
450 | --------------- |
451 | Each hook is called using the hook type specified in the list above: |
452 | do_hook do_hook() |
453 | hook_func do_hook_function() |
454 | concat_hook concat_hook_function() |
a3a95e4a |
455 | |
456 | |
a61f899d |
457 | (!) Compose Form |
458 | ---------------- |
6b7579a0 |
459 | The compose_form hook allows plugins to insert their own code into |
a61f899d |
460 | the form tag for the main message composition HTML form. Usually |
461 | plugins will want to insert some kind of code in an onsubmit event |
462 | handler. In order to allow more than one plugin to do so, all plugins |
463 | using this hook to add some onsubmit code need to add that code (without |
6b7579a0 |
464 | the enclosing attribute name and quotes) as a new array entry to the |
a61f899d |
465 | global $compose_onsubmit array. The code should use "return false" |
466 | if the plugin has found a reason to stop form submission, otherwise, |
467 | it should DO NOTHING (that is, please do not use "return true", as that |
468 | will prevent other plugins from using the onsubmit handler). SquirrelMail |
469 | itself will insert a final "return true". All onsubmit code will be |
6b7579a0 |
470 | enclosed in double quotes by SquirrelMail, so plugins need to quote |
a61f899d |
471 | accordingly if needed. For example: |
472 | |
473 | global $compose_onsubmit; |
474 | $compose_onsubmit[] = ' if (somevar == \'no\') return false; '; |
475 | |
476 | Note the escaped single quotes. If you use double quotes, they would have |
477 | to be escaped as such: |
478 | |
479 | global $compose_onsubmit; |
480 | $compose_onsubmit[] = ' if (somevar == \'no\') { alert(\\"Sorry\\"); return false; }'; |
481 | |
6b7579a0 |
482 | Any other form tag additions by a plugin (beside onsubmit event code) can |
a61f899d |
483 | currently be echoed directly to the browser. |
484 | |
485 | |
0f101579 |
486 | (&) Identity Hooks |
487 | ------------------ |
9cd2ae7d |
488 | This set of hooks is passed special information in the array of arguments: |
0f101579 |
489 | |
490 | options_identities_process |
9cd2ae7d |
491 | |
b6522eb5 |
492 | This hook is called at the top of the Identities page, which is |
9cd2ae7d |
493 | most useful when the user has changed any identity settings - this |
494 | is where you'll want to save any custom information you are keeping |
495 | for each identity or catch any custom submit buttons that you may |
496 | have added to the identities page. The arguments to this hook are: |
497 | |
3df61ef3 |
498 | (SquirrelMail 1.4.4 or older and 1.5.0) |
9cd2ae7d |
499 | [0] = hook name (always "options_identities_process") |
500 | [1] = should I run the SaveUpdateFunction() (alterable) |
501 | |
502 | Obviously, set the second array element to 1/true if you want to |
503 | trigger SaveUpdateFunction() after the hook is finished - by default, |
504 | it will not be called. |
0f101579 |
505 | |
3df61ef3 |
506 | (SquirrelMail 1.4.6+ or 1.5.1+) |
507 | [0] = hook name (always "options_identities_process") |
6b7579a0 |
508 | [1] = action (hook is used only in 'update' action and any custom |
509 | action added to form with option_identities_table and |
3df61ef3 |
510 | option_identities_buttons hooks) |
511 | [2] = processed identity number |
512 | |
513 | Hook is not available in SquirrelMail 1.4.5. |
514 | |
0f101579 |
515 | options_identities_renumber |
9cd2ae7d |
516 | |
517 | This hook is called when one of the identities is being renumbered, |
b6522eb5 |
518 | such as if the user had three identities and deletes the second - |
9cd2ae7d |
519 | this hook would be called with an array that looks like this: |
520 | ('options_identities_renumber', 2, 1). The arguments to this hook |
521 | are: |
522 | |
523 | [0] = hook name (always "options_identities_renumber") |
524 | [1] = being renumbered from ('default' or 1 through (# idents) - 1) |
525 | [2] = being renumbered to ('default' or 1 through (# idents) - 1) |
b6522eb5 |
526 | |
3df61ef3 |
527 | Hook is not available in SquirrelMail 1.4.5. Renumbering order differs |
528 | in 1.4.5+ and 1.5.1+. |
529 | |
0f101579 |
530 | options_identities_table |
9cd2ae7d |
531 | |
532 | This hook allows you to insert additional rows into the table that |
533 | holds each identity. The arguments to this hook are: |
534 | |
23e3aacf |
535 | [0] = additional html attributes applied to table row. |
536 | use it like this in your plugin: |
537 | <tr "<?php echo $args[0]; ?>"> |
9cd2ae7d |
538 | [1] = is this an empty section (the one at the end of the list)? |
539 | [2] = what is the 'post' value? (ident # or empty string if default) |
540 | |
541 | You need to return any HTML you would like to add to the table. |
542 | You could add a table row with code similar to this: |
543 | |
b6522eb5 |
544 | function demo_identities_table(&$args) |
9cd2ae7d |
545 | { |
546 | return '<tr bgcolor="' . $args[0] . '"><td> </td><td>' |
547 | . 'YOUR CODE HERE' . '</td></tr>' . "\n"; |
548 | } |
b6522eb5 |
549 | |
6b7579a0 |
550 | First hook argument was modified in 1.4.5/1.5.1. In SquirrelMail 1.4.1-1.4.4 |
551 | and 1.5.0 argument contains only background color. You should use |
23e3aacf |
552 | <tr bgcolor="<?php echo $args[0]; ?>"> in these SquirrelMail versions. |
553 | |
0f101579 |
554 | options_identities_buttons |
9cd2ae7d |
555 | |
556 | This hook allows you to add a button (or other HTML) to the row of |
557 | buttons under each identity. The arguments to this hook are: |
558 | |
559 | [0] = is this an empty section (the one at the end of the list)? |
560 | [1] = what is the 'post' value? (ident # or empty string if default) |
561 | |
b6522eb5 |
562 | You need to return any HTML you would like to add here. You could add |
9cd2ae7d |
563 | a button with code similar to this: |
564 | |
565 | function demo_identities_button(&$args) |
566 | { |
567 | return '<input type="submit" name="demo_button_' . $args[1] |
5f75494f |
568 | . '" value="Press Me" />'; |
9cd2ae7d |
569 | } |
0f101579 |
570 | |
6b7579a0 |
571 | Input element should use 'smaction[action_name][identity_no]' value in |
ad427dd3 |
572 | 'name' attribute, if you want to process your button actions in |
3df61ef3 |
573 | SquirrelMail 1.4.6+ and 1.5.1+ options_identity_process hook. |
574 | |
575 | |
576 | See sample implementation of identity hooks in SquirrelMail demo plugin. |
577 | |
578 | cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/squirrelmail \ |
579 | co plugins/demo |
580 | |
0f101579 |
581 | |
a3a95e4a |
582 | (^) Attachment Hooks |
583 | -------------------- |
584 | When a message has attachments, this hook is called with the MIME types. For |
585 | instance, a .zip file hook is "attachment application/x-zip". The hook should |
586 | probably show a link to do a specific action, such as "Verify" or "View" for a |
9cd2ae7d |
587 | .zip file. Thus, to register your plugin for .zip attachments, you'd do this |
588 | in setup.php (assuming your plugin is called "demo"): |
589 | |
590 | $squirrelmail_plugin_hooks['attachment application/x-zip']['demo'] |
591 | = 'demo_handle_zip_attachment'; |
a3a95e4a |
592 | |
593 | This is a breakdown of the data passed in the array to the hook that is called: |
594 | |
595 | [0] = Hook's name ('attachment text/plain') |
9cd2ae7d |
596 | [1] = Array of links of actions (see below) (alterable) |
a3a95e4a |
597 | [2] = Used for returning to mail message (startMessage) |
598 | [3] = Used for finding message to display (id) |
599 | [4] = Mailbox name, urlencode()'d (urlMailbox) |
600 | [5] = Entity ID inside mail message (ent) |
9cd2ae7d |
601 | [6] = Default URL to go to when filename is clicked on (alterable) |
ef30bf50 |
602 | [7] = Filename that is displayed for the attachment |
603 | [8] = Sent if message was found from a search (where) |
604 | [9] = Sent if message was found from a search (what) |
b6522eb5 |
605 | |
a3a95e4a |
606 | To set up links for actions, you assign them like this: |
b6522eb5 |
607 | |
9cd2ae7d |
608 | $Args[1]['<plugin_name>']['href'] = 'URL to link to'; |
21dab2dc |
609 | $Args[1]['<plugin_name>']['text'] = _("What to display"); |
d0201d63 |
610 | $Args[1]['<plugin_name>']['extra'] = 'extra stuff, such as an <img ...> tag'; |
21dab2dc |
611 | |
612 | Note: _("What to display") is explained in the section about |
613 | internationalization. |
b6522eb5 |
614 | |
d0201d63 |
615 | You can leave the 'text' empty and put an image tag in 'extra' to show an |
616 | image-only link for the attachment, or do the opposite (leave 'extra' empty) |
617 | to display a text-only link. |
618 | |
ae2f65a9 |
619 | It's also possible to specify a hook as "attachment type0/*", |
620 | for example "attachment text/*". This hook will be executed whenever there's |
621 | no more specific rule available for that type. |
622 | |
9cd2ae7d |
623 | Putting all this together, the demo_handle_zip_attachment() function should |
624 | look like this (note the argument being passed): |
57945c53 |
625 | |
9cd2ae7d |
626 | function demo_handle_zip_attachment(&$Args) |
627 | { |
628 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
629 | demo_handle_zip_attachment_do($Args); |
630 | } |
57945c53 |
631 | |
9cd2ae7d |
632 | And the demo_handle_zip_attachment_do() function in the |
633 | plugins/demo/functions.php file would typically (but not necessarily) |
634 | display a custom link: |
635 | |
636 | function demo_handle_zip_attachment_do(&$Args) |
637 | { |
638 | $Args[1]['demo']['href'] = SM_PATH . 'plugins/demo/zip_handler.php?' |
b6522eb5 |
639 | . 'passed_id=' . $Args[3] . '&mailbox=' . $Args[4] |
9cd2ae7d |
640 | . '&passed_ent_id=' . $Args[5]; |
21dab2dc |
641 | $Args[1]['demo']['text'] = _("Show zip contents"); |
9cd2ae7d |
642 | } |
643 | |
644 | The file plugins/demo/zip_handler.php can now do whatever it needs with the |
645 | attachment (note that this will hand information about how to retrieve the |
646 | source message from the IMAP server as GET varibles). |
647 | |
648 | |
649 | (*) Options |
650 | ----------- |
651 | Before you start adding user preferences to your plugin, please take a moment |
b6522eb5 |
652 | to think about it: in some cases, more options may not be a good thing. |
653 | Having too many options can be confusing. Thinking from the user's |
9cd2ae7d |
654 | perspective, will the proposed options actually be used? Will users |
655 | understand what these options are for? |
656 | |
657 | There are two ways to add options for your plugin. When you only have a few |
658 | options that don't merit an entirely new preferences page, you can incorporate |
b6522eb5 |
659 | them into an existing section of SquirrelMail preferences (Personal |
660 | Information, Display Preferences, Message Highlighting, Folder Preferences or |
661 | Index Order). Or, if you have an extensive number of settings or for some |
9cd2ae7d |
662 | reason need a separate page for the user to interact with, you can create your |
663 | own preferences page. |
664 | |
665 | |
666 | Integrating Your Options Into Existing SquirrelMail Preferences Pages |
667 | --------------------------------------------------------------------- |
668 | |
669 | There are two ways to accomplish the integration of your plugin's settings |
b6522eb5 |
670 | into another preferences page. The first method is to add the HTML code |
9cd2ae7d |
671 | for your options directly to the preferences page of your choice. Although |
672 | currently very popular, this method will soon be deprecated, so avoid it |
b6522eb5 |
673 | if you can. That said, here is how it works. :) Look for any of the hooks |
674 | named as "options_<pref page>_inside", where <pref page> is "display", |
675 | "personal", etc. For this example, we'll use "options_display_inside" and, |
9cd2ae7d |
676 | as above, "demo" as our plugin name: |
677 | |
678 | 1. In setup.php in the squirrelmail_plugin_init_demo() function: |
679 | |
b6522eb5 |
680 | $squirrelmail_plugin_hooks['options_display_inside']['demo'] |
9cd2ae7d |
681 | = 'demo_show_options'; |
682 | |
683 | Note that there are also hooks such as "options_display_bottom", |
684 | however, they place your options at the bottom of the preferences |
685 | page, which is usually not desirable (mostly because they also |
686 | come AFTER the HTML FORM tag is already closed). It is possible |
687 | to use these hooks if you want to create your own FORM with custom |
688 | submission logic. |
689 | |
690 | 2. Assuming the function demo_show_options() calls another function |
691 | elsewhere called demo_show_options_do(), that function should have |
692 | output similar to this (note that you will be inserting code into |
693 | a table that is already defined with two columns, so please be sure |
694 | to keep this framework in your plugin): |
695 | |
696 | ------cut here------- |
697 | <tr> |
698 | <td> |
699 | OPTION_NAME |
700 | </td> |
701 | <td> |
702 | OPTION_INPUT |
703 | </td> |
b6522eb5 |
704 | </tr> |
9cd2ae7d |
705 | ------cut here------- |
706 | |
707 | Of course, you can place any text where OPTION_NAME is and any input |
b6522eb5 |
708 | tags where OPTION_INPUT is. |
9cd2ae7d |
709 | |
710 | 3. You will want to use the "options_<pref page>_save" hook (in this case, |
711 | "options_display_save") to save the user's settings after they have |
b6522eb5 |
712 | pressed the "Submit" button. Again, back in setup.php in the |
9cd2ae7d |
713 | squirrelmail_plugin_init_demo() function: |
57945c53 |
714 | |
b6522eb5 |
715 | $squirrelmail_plugin_hooks['options_display_save']['demo'] |
9cd2ae7d |
716 | = 'demo_save_options'; |
57945c53 |
717 | |
9cd2ae7d |
718 | 4. Assuming the function demo_save_options() calls another function |
719 | elsewhere called demo_save_options_do(), that function should put |
720 | the user's settings into permanent storage (see the preferences |
721 | section below for more information). This example assumes that |
722 | in the preferences page, the INPUT tag's NAME attribute was set |
723 | to "demo_option": |
724 | |
725 | global $data_dir, $username; |
726 | sqgetGlobalVar('demo_option', $demo_option); |
727 | setPref($data_dir, $username, 'demo_option', $demo_option); |
728 | |
729 | |
730 | The second way to add options to one of the SquirrelMail preferences page is |
731 | to use one of the "optpage_loadhook_<pref page>" hooks. The sent_subfolders |
60eeb409 |
732 | plugin has an excellent example of this method. Briefly, this way of adding |
9cd2ae7d |
733 | options consists of adding some plugin-specific information to a predefined |
734 | data structure which SquirrelMail then uses to build the HTML input forms |
735 | for you. This is the preferred method of building options lists going forward. |
736 | |
737 | 1. We'll use the "optpage_loadhook_display" hook to add a new group of |
b6522eb5 |
738 | options to the display preferences page. In setup.php in the |
9cd2ae7d |
739 | squirrelmail_plugin_init_demo() function: |
740 | |
b6522eb5 |
741 | $squirrelmail_plugin_hooks['optpage_loadhook_display']['demo'] |
9cd2ae7d |
742 | = 'demo_options'; |
743 | |
744 | 2. Assuming the function demo_options() calls another function elsewhere |
745 | called demo_options_do(), that function needs to add a new key to two |
746 | arrays, $optpage_data['grps'] and $optpage_data['vals']. The value |
747 | associated with that key should simply be a section heading for your |
748 | plugin on the preferences page for the $optpage_data['grps'] array, |
b6522eb5 |
749 | and yet another array with all of your plugin's options for the |
750 | $optpage_data['vals'] array. The options are built as arrays (yes, |
9cd2ae7d |
751 | that's four levels of nested arrays) that specify attributes that are |
752 | used by SquirrelMail to build your HTML input tags automatically. |
753 | This example includes just one input element, a SELECT (drop-down) |
754 | list: |
755 | |
756 | global $optpage_data; |
757 | $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options'; |
758 | $optionValues = array(); |
759 | $optionValues[] = array( |
760 | 'name' => 'plugin_demo_favorite_color', |
761 | 'caption' => 'Please Choose Your Favorite Color', |
762 | 'type' => SMOPT_TYPE_STRLIST, |
763 | 'refresh' => SMOPT_REFRESH_ALL, |
764 | 'posvals' => array(0 => 'red', |
765 | 1 => 'blue', |
766 | 2 => 'green', |
767 | 3 => 'orange'), |
768 | 'save' => 'save_plugin_demo_favorite_color' |
769 | ); |
770 | $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues; |
771 | |
772 | The array that you use to specify each plugin option has the following |
773 | possible attributes: |
774 | |
6976aad7 |
775 | name The name of this setting, which is used not only for |
776 | the INPUT tag name, but also for the name of this |
777 | setting in the user's preferences |
778 | caption The text that prefaces this setting on the preferences |
779 | page |
361d6e1b |
780 | trailing_text Text that follows a text input or select list input on |
781 | the preferences page (useful for indicating units, |
782 | meanings of special values, etc.) |
6976aad7 |
783 | type The type of INPUT element, which should be one of: |
784 | SMOPT_TYPE_STRING String/text input |
785 | SMOPT_TYPE_STRLIST Select list input |
786 | SMOPT_TYPE_TEXTAREA Text area input |
787 | SMOPT_TYPE_INTEGER Integer input |
788 | SMOPT_TYPE_FLOAT Floating point number input |
789 | SMOPT_TYPE_BOOLEAN Boolean (yes/no radio buttons) |
60eeb409 |
790 | input |
6976aad7 |
791 | SMOPT_TYPE_HIDDEN Hidden input (not actually |
792 | shown on preferences page) |
793 | SMOPT_TYPE_COMMENT Text is shown (specified by the |
794 | 'comment' attribute), but no |
795 | user input is needed |
796 | SMOPT_TYPE_FLDRLIST Select list of IMAP folders |
797 | refresh Indicates if a link should be shown to refresh part or |
798 | all of the window (optional). Possible values are: |
799 | SMOPT_REFRESH_NONE No refresh link is shown |
800 | SMOPT_REFRESH_FOLDERLIST Link is shown to refresh |
801 | only the folder list |
802 | SMOPT_REFRESH_ALL Link is shown to refresh |
803 | the entire window |
b6522eb5 |
804 | initial_value The value that should initially be placed in this |
6976aad7 |
805 | INPUT element |
806 | posvals For select lists, this should be an associative array, |
807 | where each key is an actual input value and the |
808 | corresponding value is what is displayed to the user |
809 | for that list item in the drop-down list |
810 | value Specify the default/preselected value for this option |
811 | input |
812 | save You may indicate that special functionality needs to be |
813 | used instead of just saving this setting by giving the |
b6522eb5 |
814 | name of a function to call when this value would |
6976aad7 |
815 | otherwise just be saved in the user's preferences |
816 | size Specifies the size of certain input items (typically |
817 | textual inputs). Possible values are: |
818 | SMOPT_SIZE_TINY |
819 | SMOPT_SIZE_SMALL |
820 | SMOPT_SIZE_MEDIUM |
821 | SMOPT_SIZE_LARGE |
822 | SMOPT_SIZE_HUGE |
823 | SMOPT_SIZE_NORMAL |
824 | comment For SMOPT_TYPE_COMMENT type options, this is the text |
825 | displayed to the user |
b6522eb5 |
826 | script This is where you may add any additional javascript |
6976aad7 |
827 | or other code to the user input |
828 | post_script You may specify some script (usually Javascript) that |
829 | will be placed after (outside of) the INPUT tag. |
ddb5b25c |
830 | htmlencoded disables html sanitizing. WARNING - don't use it, if user |
831 | input is possible in option or use own sanitizing functions. |
832 | Currently works only with SMOPT_TYPE_STRLIST. |
99ecf044 |
833 | folder_filter Controls folder list limits in SMOPT_TYPE_FLDRLIST widget. |
834 | See $flag argument in sqimap_mailbox_option_list() |
835 | function. Available since 1.5.1. |
9cd2ae7d |
836 | |
60eeb409 |
837 | Note that you do not have to create a whole new section on the options |
838 | page if you merely want to add a simple input item or two to an options |
839 | section that already exists. For example, the Display Options page has |
840 | these groups: |
841 | |
842 | 0 - General Display Options |
843 | 1 - Mailbox Display Options |
844 | 2 - Message Display and Composition |
845 | |
846 | To add our previous input drop-down to the Mailbox Display Options, |
847 | we would not have to create our own group; just add it to group |
848 | number one: |
849 | |
850 | global $optpage_data; |
851 | $optpage_data['vals'][1][] = array( |
852 | 'name' => 'plugin_demo_favorite_color', |
853 | 'caption' => 'Please Choose Your Favorite Color', |
854 | 'type' => SMOPT_TYPE_STRLIST, |
855 | 'refresh' => SMOPT_REFRESH_ALL, |
856 | 'posvals' => array(0 => 'red', |
857 | 1 => 'blue', |
858 | 2 => 'green', |
859 | 3 => 'orange'), |
860 | 'save' => 'save_plugin_demo_favorite_color' |
861 | ); |
862 | |
9cd2ae7d |
863 | 3. If you indicated a 'save' attribute for any of your options, you must |
864 | create that function (you'll only need to do this if you need to do |
865 | some special processing for one of your settings). The function gets |
b6522eb5 |
866 | one parameter, which is an object with mostly the same attributes you |
9cd2ae7d |
867 | defined when you made the option above... the 'new_value' (and possibly |
868 | 'value', which is the current value for this setting) is the most useful |
869 | attribute in this context: |
870 | |
871 | function save_plugin_demo_favorite_color($option) |
872 | { |
873 | // if user chose orange, make note that they are really dumb |
874 | if ($option->new_value == 3) |
875 | { |
876 | // more code here as needed |
877 | } |
878 | |
879 | // don't even save this setting if user chose green (old |
880 | // setting will remain) |
881 | if ($option->new_value == 2) |
882 | return; |
883 | |
884 | // for all other colors, save as normal |
885 | save_option($option); |
886 | } |
887 | |
888 | |
889 | Creating Your Own Preferences Page |
890 | ---------------------------------- |
891 | |
892 | It is also possible to create your own preferences page for a plugin. This |
b6522eb5 |
893 | is particularly useful when your plugin has numerous options or needs to |
9cd2ae7d |
894 | offer special interaction with the user (for things such as changing password, |
895 | etc.). Here is an outline of how to do so (again, using the "demo" plugin |
896 | name): |
897 | |
b6522eb5 |
898 | 1. Add a new listing to the main Options page. Older versions of |
9cd2ae7d |
899 | SquirrelMail offered a hook called "options_link_and_description" |
900 | although its use is deprecated (and it is harder to use in that |
901 | it requires you to write your own HTML to add the option). Instead, |
902 | you should always use the "optpage_register_block" hook where you |
903 | create a simple array that lets SquirrelMail build the HTML |
904 | to add the plugin options entry automatically. In setup.php in the |
905 | squirrelmail_plugin_init_demo() function: |
b6522eb5 |
906 | |
9cd2ae7d |
907 | $squirrelmail_plugin_hooks['optpage_register_block']['demo'] |
908 | = 'demo_options_block'; |
909 | |
910 | 2. Assuming the function demo_options_block() calls another function |
911 | elsewhere called demo_options_block_do(), that function only needs |
912 | to create a simple array and add it to the $optpage_blocks array: |
913 | |
914 | global $optpage_blocks; |
915 | $optpage_blocks[] = array( |
916 | 'name' => 'Favorite Color Settings', |
917 | 'url' => SM_PATH . 'plugins/demo/options.php', |
918 | 'desc' => 'Change your favorite color & find new exciting colors', |
919 | 'js' => FALSE |
920 | ); |
921 | |
922 | The array should have four elements: |
923 | name The title of the plugin's options as it will be displayed on |
924 | the Options page |
925 | url The URI that points to your plugin's custom preferences page |
926 | desc A description of what the preferences page offers the user, |
927 | displayed on the Options page below the title |
928 | js Indicates if this option page requires the client browser |
929 | to be Javascript-capable. Should be TRUE or FALSE. |
930 | |
b6522eb5 |
931 | 3. There are two different ways to create the actual preferences page |
932 | itself. One is to simply write all of your own HTML and other |
933 | interactive functionality, while the other is to define some data |
9cd2ae7d |
934 | structures that allow SquirrelMail to build your user inputs and save |
b6522eb5 |
935 | your data automatically. |
9cd2ae7d |
936 | |
b6522eb5 |
937 | Building your own page is wide open, and for ideas, you should look at |
9cd2ae7d |
938 | any of the plugins that currently have their own preferences pages. If |
b6522eb5 |
939 | you do this, make sure to read step number 4 below for information on |
940 | saving settings. In order to maintain security, consistant look and |
9cd2ae7d |
941 | feel, internationalization support and overall integrity, there are just |
942 | a few things you should always do in this case: define the SM_PATH |
943 | constant, include the file include/validate.php (see the section about |
944 | including other files above) and make a call to place the standard page |
945 | heading at the top of your preferences page. The top of your PHP file |
946 | might look something like this: |
947 | |
948 | define('SM_PATH', '../../'); |
949 | include_once(SM_PATH . 'include/validate.php'); |
950 | global $color; |
951 | displayPageHeader($color, 'None'); |
952 | |
953 | From here you are on your own, although you are encouraged to do things |
954 | such as use the $color array to keep your HTML correctly themed, etc. |
955 | |
b6522eb5 |
956 | If you want SquirrelMail to build your preferences page for you, |
957 | creating input forms and automatically saving users' settings, then |
9cd2ae7d |
958 | you should change the 'url' attribute in the options block you created |
959 | in step number 2 above to read as follows: |
960 | |
961 | 'url' => SM_PATH . 'src/options.php?optpage=plugin_demo', |
962 | |
b6522eb5 |
963 | Now, you will need to use the "optpage_set_loadinfo" hook to tell |
964 | SquirrelMail about your new preferences page. In setup.php in the |
9cd2ae7d |
965 | squirrelmail_plugin_init_demo() function: |
b6522eb5 |
966 | |
9cd2ae7d |
967 | $squirrelmail_plugin_hooks['optpage_set_loadinfo']['demo'] |
968 | = 'demo_optpage_loadinfo'; |
969 | |
970 | Assuming the function demo_optpage_loadinfo() calls another function |
b6522eb5 |
971 | elsewhere called demo_optpage_loadinfo_do(), that function needs to |
972 | define values for four variables (make sure you test to see that it |
9cd2ae7d |
973 | is your plugin that is being called by checking the GET variable you |
974 | added to the url just above): |
b6522eb5 |
975 | |
976 | global $optpage, $optpage_name, $optpage_file, |
9cd2ae7d |
977 | $optpage_loader, $optpage_loadhook; |
978 | if ($optpage == 'plugin_demo') |
979 | { |
980 | $optpage_name = "Favorite Color Preferences"; |
981 | $optpage_file = SM_PATH . 'plugins/demo/options.php'; |
982 | $optpage_loader = 'load_optpage_data_demo'; |
983 | $optpage_loadhook = 'optpage_loadhook_demo'; |
984 | } |
985 | |
986 | Now you are ready to build all of your options. In the file you |
987 | indicated for the variable $optpage_file above, you'll need to create |
988 | a function named the same as the value you used for $optpage_loader |
989 | above. In this example, the file plugins/demo/options.php should |
990 | have at least this function in it: |
991 | |
992 | function load_optpage_data_demo() |
993 | { |
994 | $optpage_data = array(); |
995 | $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options'; |
996 | $optionValues = array(); |
997 | $optionValues[] = array( |
998 | 'name' => 'plugin_demo_favorite_color', |
999 | 'caption' => 'Please Choose Your Favorite Color', |
1000 | 'type' => SMOPT_TYPE_STRLIST, |
1001 | 'refresh' => SMOPT_REFRESH_ALL, |
1002 | 'posvals' => array(0 => 'red', |
1003 | 1 => 'blue', |
1004 | 2 => 'green', |
1005 | 3 => 'orange'), |
1006 | 'save' => 'save_plugin_demo_favorite_color' |
1007 | ); |
1008 | $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues; |
1009 | return $optpage_data; |
1010 | } |
1011 | |
1012 | For a detailed description of how you build these options, please read |
1013 | step number 2 for the second method of adding options to an existing |
1014 | preferences page above. Notice that the only difference here is in the |
1015 | very first and last lines of this function where you are actually |
1016 | creating and returning the options array instead of just adding onto it. |
1017 | |
1018 | That's all there is to it - SquirrelMail will create a preferences page |
1019 | titled as you indicated for $optpage_name above, and other plugins |
1020 | can even add extra options to this new preferences page. To do so, |
1021 | they should use the hook name you specified for $optpage_loadhook above |
1022 | and use the second method for adding option settings to existing |
1023 | preferences pages described above. |
1024 | |
1025 | 4. Saving your options settings: if you used the second method in step |
1026 | number 3 above, your settings will be saved automatically (or you can |
b6522eb5 |
1027 | define special functions to save special settings such as the |
9cd2ae7d |
1028 | save_plugin_demo_favorite_color() function in the example described |
1029 | above) and there is probably no need to follow this step. If you |
1030 | created your own preferences page from scratch, you'll need to follow |
1031 | this step. First, you need to register your plugin against the |
1032 | "options_save" hook. In setup.php in the squirrelmail_plugin_init_demo() |
1033 | function: |
b6522eb5 |
1034 | |
9cd2ae7d |
1035 | $squirrelmail_plugin_hooks['options_save']['demo'] |
1036 | = 'demo_save_options'; |
1037 | |
1038 | Assuming the function demo_save_options() calls another function |
1039 | elsewhere called demo_save_options_do(), that function needs to grab |
1040 | all of your POST and/or GET settings values and save them in the user's |
1041 | preferences (for more about preferences, see that section below). Since |
b6522eb5 |
1042 | this is a generic hook called for all custom preferences pages, you |
9cd2ae7d |
1043 | should always set "optpage" as a POST or GET variable with a string that |
1044 | uniquely identifies your plugin: |
1045 | |
6fd95361 |
1046 | <input type="hidden" name="optpage" value="plugin_demo" /> |
9cd2ae7d |
1047 | |
1048 | Now in your demo_save_options_do() function, do something like this: |
1049 | |
1050 | global $username, $data_dir, $optpage, $favorite_color; |
1051 | if ($optpage == 'plugin_demo') |
1052 | { |
1053 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
1054 | setPref($data_dir, $username, 'favorite_color', $favorite_color); |
1055 | } |
b6522eb5 |
1056 | |
1057 | Note that $favorite_color may not need to be globalized, although |
9cd2ae7d |
1058 | experience has shown that some versions of PHP don't behave as expected |
1059 | unless you do so. Even when you use SquirrelMail's built-in preferences |
b6522eb5 |
1060 | page generation functionality, you may still use this hook, although |
1061 | there should be no need to do so. If you need to do some complex |
9cd2ae7d |
1062 | validation routines, note that it might be better to do so in the file |
1063 | you specified as the "$optpage_file" (in our example, that was the |
b6522eb5 |
1064 | plugins/demo/options.php file), since at this point, you can still |
9cd2ae7d |
1065 | redisplay your preferences page. You could put code similar to this |
1066 | in the plugins/demp/options.php file (note that there is no function; |
1067 | this code needs to be executed at include time): |
1068 | |
1069 | global $optmode; |
b6522eb5 |
1070 | if ($optmode == 'submit') |
9cd2ae7d |
1071 | { |
1072 | // do something here such as validation, etc |
1073 | if (you want to redisplay your preferences page) |
1074 | $optmode = ''; |
1075 | } |
1076 | |
1077 | |
1078 | Preferences |
1079 | ----------- |
1080 | |
1081 | Saving and retrieving user preferences is very easy in SquirrelMail. |
b6522eb5 |
1082 | SquirrelMail supports preference storage in files or in a database |
9cd2ae7d |
1083 | backend, however, the code you need to write to manipulate preferences |
1084 | is the same in both cases. |
1085 | |
b6522eb5 |
1086 | Setting preferences: |
9cd2ae7d |
1087 | |
1088 | Setting preferences is done for you if you use the built-in facilities |
1089 | for automatic options construction and presentation (see above). If |
1090 | you need to manually set preferences, however, all you need to do is: |
1091 | |
1092 | global $data_dir, $username; |
1093 | setPref($data_dir, $username, 'pref_name', $pref_value); |
1094 | |
1095 | Where "pref_name" is the key under which the value will be stored |
b6522eb5 |
1096 | and "pref_value" is a variable that should contain the actual |
9cd2ae7d |
1097 | preference value to be stored. |
1098 | |
1099 | Loading preferences: |
1100 | |
1101 | There are two approaches to retrieving plugin (or any other) preferences. |
1102 | You can grab individual preferences one at a time or you can add your |
b6522eb5 |
1103 | plugin's preferences to the routine that loads up user preferences at |
9cd2ae7d |
1104 | the beginning of each page request. If you do the latter, making sure |
1105 | to place your preference variables into the global scope, they will be |
1106 | immediately available in all other plugin code. To retrieve a single |
1107 | preference value at any time, do this: |
1108 | |
1109 | global $data_dir, $username; |
1110 | $pref_value = getPref($data_dir, $username, 'pref_name', 'default value'); |
1111 | |
1112 | Where "pref_name" is the preference you are retrieving, "default_value" |
1113 | is what will be returned if the preference is not found for this user, |
1114 | and, of course, "pref_value" is the variable that will get the actual |
1115 | preference value. |
1116 | |
1117 | To have all your preferences loaded at once when each page request is |
1118 | made, you'll need to register a function against the "loading_prefs" hook. |
1119 | For our "demo" plugin, in setup.php in the squirrelmail_plugin_init_demo() |
1120 | function: |
b6522eb5 |
1121 | |
9cd2ae7d |
1122 | $squirrelmail_plugin_hooks['loading_prefs']['demo'] |
1123 | = 'demo_load_prefs'; |
1124 | |
1125 | Assuming the function demo_load_prefs() calls another function |
1126 | elsewhere called demo_load_prefs_do(), that function just needs to |
1127 | pull out any all all preferences you'll be needing elsewhere: |
1128 | |
1129 | global $data_dir, $username, $pref_value; |
1130 | $pref_value = getPref($data_dir, $username, 'pref_name', 'default value'); |
1131 | |
1132 | Remember to globalize each preference, or this code is useless. |
1133 | |
1134 | |
1135 | Internationalization |
1136 | -------------------- |
1137 | |
1138 | Although this document may only be available in English, we sure hope that you |
1139 | are thinking about making your plugin useful to the thousands of non-English |
1140 | speaking SquirrelMail users out there! It is almost rude not to do so, and |
1141 | it isn't much trouble, either. This document will only describe how you can |
1142 | accomplish the internationalization of a plugin. For more general information |
1143 | about PHP and SquirrelMail translation facilities, see: |
1144 | |
e07525be |
1145 | http://www.squirrelmail.org/wiki/LanguageTranslation |
9cd2ae7d |
1146 | |
1147 | The unofficial way to internationalize a plugin is to put all plugin output |
1148 | into the proper format but to rely on the SquirrelMail translation facilities |
1149 | for all the rest. If the plugin were really to get translated, you'd need |
1150 | to make sure that all output strings for your plugin are either added to or |
1151 | already exist in the main SquirrelMail locale files. |
1152 | |
1153 | The better way to make sure your plugin is translated is to create your own |
1154 | locale files and what is called a "gettext domain" (see the link above for |
1155 | more information). |
1156 | |
1157 | There are three basic steps to getting your plugins internationalized: put |
b6522eb5 |
1158 | all output into the proper format, switch gettext domains and create locale |
9cd2ae7d |
1159 | files. |
1160 | |
1161 | 1. Putting plugin output into the correct format is quite easy. The hard |
1162 | part is making sure you catch every last echo statement. You need to |
1163 | echo text like this: |
1164 | |
1165 | echo _("Hello"); |
1166 | |
1167 | So, even in the HTML segments of your plugin files, you need to do this: |
1168 | |
6fd95361 |
1169 | <input type="submit" value="<?php echo _("Submit"); ?>" /> |
9cd2ae7d |
1170 | |
1171 | You can put any text you want inside of the quotes (you MUST use double |
b6522eb5 |
1172 | quotes!), including HTML tags, etc. What you should think carefully |
1173 | about is that some languages may use different word ordering, so this |
9cd2ae7d |
1174 | might be problematic: |
1175 | |
1176 | echo _("I want to eat a ") . $fruitName . _(" before noon"); |
1177 | |
1178 | Because some languages (Japanese, for instance) would need to translate |
b6522eb5 |
1179 | such a sentence to "Before noon " . $fruitName . " I want to eat", but |
1180 | with the format above, they are stuck having to translate each piece |
9cd2ae7d |
1181 | separately. You might want to reword your original sentence: |
1182 | |
1183 | echo _("This is what I want to eat before noon: ") . $fruitName; |
1184 | |
45f574a7 |
1185 | Note: |
1186 | Support for single quotes in gettext was added somewhere along gettext |
1187 | 0.11.x (release dates 2002-01-31--08-06). This means that strings could |
1188 | be written as: |
1189 | |
1190 | echo _('Hello'); |
1191 | |
1192 | However, gettext 0.10.40 is currently the oldest version available at the |
1193 | GNU site. It's still used in some Linux and BSD distributions/versions. |
1194 | Since it's still in common use and it doesn't support single quoted |
1195 | strings, double quoted strings are the preferred way when writing a |
1196 | plugin. |
1197 | |
9cd2ae7d |
1198 | 2. By default, the SquirrelMail gettext domain is always in use. That |
1199 | means that any text in the format described above will be translated |
1200 | using the locale files found in the main SquirrelMail locale directory. |
1201 | Unless your plugin produces no output or only output that is in fact |
1202 | translated under the default SquirrelMail domain, you need to create |
1203 | your own gettext domain. The PHP for doing so is very simple. At |
1204 | the top of any file that produces any output, place the following code |
1205 | (again, using "demo" as the plugin name): |
1206 | |
b6f0f89d |
1207 | bindtextdomain('demo', SM_PATH . 'locale'); |
9cd2ae7d |
1208 | textdomain('demo'); |
1209 | |
1210 | Now all output will be translated using your own custom locale files. |
1211 | Please be sure to switch back to the SquirrelMail domain at the end |
1212 | of the file, or many of the other SquirrelMail files may misbehave: |
1213 | |
1214 | bindtextdomain('squirrelmail', SM_PATH . 'locale'); |
1215 | textdomain('squirrelmail'); |
1216 | |
1217 | Note that if, in the middle of your plugin file, you use any |
1218 | SquirrelMail functions that send output to the browser, you'll need |
1219 | to temporarily switch back to the SquirrelMail domain: |
1220 | |
1221 | bindtextdomain('squirrelmail', SM_PATH . 'locale'); |
1222 | textdomain('squirrelmail'); |
1223 | displayPageHeader($color, 'None'); |
b6f0f89d |
1224 | bindtextdomain('demo', SM_PATH . 'locale'); |
9cd2ae7d |
1225 | textdomain('demo'); |
1226 | |
1227 | Note that technically speaking, you only need to have one bindtextdomain |
1228 | call per file, you should always use it before every textdomain call, |
1229 | since PHP installations without gettext compiled into them will not |
1230 | function properly if you do not. |
1231 | |
b6f0f89d |
1232 | 3. Finally, you just need to create your own locale. There is a directory |
1233 | structure like this in the locale directory: |
9cd2ae7d |
1234 | |
b6f0f89d |
1235 | locale |
1236 | | |
1237 | ------de_DE |
1238 | | | |
1239 | | ------LC_MESSAGES |
1240 | | |
1241 | ------ja_JP |
9cd2ae7d |
1242 | | |
b6f0f89d |
1243 | ------LC_MESSAGES |
1244 | |
79cc90dd |
1245 | There is a directory such as de_DE for each language (de_DE is German, |
b6f0f89d |
1246 | ja_JP is Japanese, etc.). Inside of each LC_MESSAGES directory you should |
1247 | place two files; one with your translations in it, called <plugin name>.po |
1248 | (in this case, "demo.po"), and one that is a compiled version of the ".po" |
1249 | file, called <plugin name>.mo (in this case, "demo.mo"). On most linux |
1250 | systems, there is a tool you can use to pull out most of the strings that |
1251 | you need to have translated from your PHP files into a sample .po file: |
9cd2ae7d |
1252 | |
b6522eb5 |
1253 | xgettext --keyword=_ -d <plugin name> -s -C *.php |
9cd2ae7d |
1254 | |
1255 | --keyword option tells xgettext what your strings are enclosed in |
1256 | -d is the domain of your plugin which should be the plugin's name |
1257 | -s tells xgettext to sort the results and remove duplicate strings |
1258 | -C means you are translating a file with C/C++ type syntax (ie. PHP) |
1259 | *.php is all the files you want translations for |
1260 | |
b6522eb5 |
1261 | Note, however, that this will not always pick up all strings, so you |
9cd2ae7d |
1262 | should double-check manually. Of course, it's easiest if you just keep |
1263 | track of all your strings as you are coding your plugin. Your .po file |
1264 | will now look something like: |
1265 | |
1266 | # SOME DESCRIPTIVE TITLE. |
1267 | # Copyright (C) YEAR Free Software Foundation, Inc. |
1268 | # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. |
1269 | # |
1270 | #, fuzzy |
1271 | msgid "" |
1272 | msgstr "" |
1273 | "Project-Id-Version: PACKAGE VERSION\n" |
1274 | "POT-Creation-Date: 2003-06-18 11:22-0600\n" |
1275 | "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" |
1276 | "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" |
1277 | "Language-Team: LANGUAGE <LL@li.org>\n" |
1278 | "MIME-Version: 1.0\n" |
1279 | "Content-Type: text/plain; charset=CHARSET\n" |
1280 | "Content-Transfer-Encoding: ENCODING\n" |
b6522eb5 |
1281 | |
9cd2ae7d |
1282 | #: functions.php:45 |
1283 | msgid "Hello" |
1284 | msgstr "" |
b6522eb5 |
1285 | |
9cd2ae7d |
1286 | #: functions.php:87 |
1287 | msgid "Favorite Color" |
1288 | msgstr "" |
b6522eb5 |
1289 | |
9cd2ae7d |
1290 | You should change the header to look something more like: |
1291 | |
b6f0f89d |
1292 | # Copyright (c) 1999-2006 The SquirrelMail Project Team |
9cd2ae7d |
1293 | # Roland Bauerschmidt <rb@debian.org>, 1999. |
df788686 |
1294 | # $Id$ |
9cd2ae7d |
1295 | msgid "" |
1296 | msgstr "" |
df788686 |
1297 | "Project-Id-Version: plugin-name version\n" |
9cd2ae7d |
1298 | "POT-Creation-Date: 2003-01-21 19:21+0100\n" |
1299 | "PO-Revision-Date: 2003-01-21 21:01+0100\n" |
1300 | "Last-Translator: Juergen Edner <juergen.edner@epost.de>\n" |
598294a7 |
1301 | "Language-Team: German <squirrelmail-i18n@lists.sourceforge.net>\n" |
9cd2ae7d |
1302 | "MIME-Version: 1.0\n" |
1303 | "Content-Type: text/plain; charset=ISO-8859-1\n" |
1304 | "Content-Transfer-Encoding: 8bit\n" |
1305 | |
1306 | The most important thing to change here is the charset on the next to |
1307 | last line. You'll want to keep a master copy of the .po file and make |
b6522eb5 |
1308 | a copy for each language you have a translation for. You'll need to |
9cd2ae7d |
1309 | translate each string in the .po file: |
1310 | |
1311 | msgid "Hello" |
1312 | msgstr "Guten Tag" |
1313 | |
b6522eb5 |
1314 | After you're done translating, you can create the .mo file very simply |
9cd2ae7d |
1315 | by running the following command (available on most linux systems): |
1316 | |
d2b351d7 |
1317 | msgfmt -o <plugin name>.mo <plugin name>.po |
9cd2ae7d |
1318 | |
1319 | In the case of the "demo" plugin: |
1320 | |
d2b351d7 |
1321 | msgfmt -o demo.mo demo.po |
9cd2ae7d |
1322 | |
1323 | Please be sure that the .po and .mo files both are named exactly the |
1324 | same as the domain you bound in step 2 above and everything else works |
1325 | automatically. In SquirrelMail, go to Options -> Display Preferences |
1326 | and change your Language setting to see the translations in action! |
1327 | |
1328 | |
a7532db9 |
1329 | |
1330 | Documenting the Code (Optional) |
1331 | ------------------------------- |
1332 | |
1333 | If you wish, you can use phpdoc (Javadoc-style) comments, when documenting your |
1334 | code. |
1335 | |
598294a7 |
1336 | If you follow the standards that are followed between SquirrelMail core & |
a7532db9 |
1337 | plugin developers, the resulted documentation can be included with the rest of |
598294a7 |
1338 | the SquirrelMail code & API documentation. Specifically, in the page-level |
a7532db9 |
1339 | docblock, declare the package to be 'plugins', and the subpackage to be the |
1340 | name of your plugin. For instance: |
b6522eb5 |
1341 | |
a7532db9 |
1342 | /** |
1343 | * demo.php |
1344 | * |
ba6338ee |
1345 | * Copyright (c) 2005 My Name <my-email-address> |
a7532db9 |
1346 | * Licensed under the GNU GPL. For full terms see the file COPYING. |
1347 | * |
1348 | * @package plugins |
1349 | * @subpackage demo |
1350 | */ |
1351 | |
1352 | The rest is up to you. Try to follow some common sense and document what is |
1353 | really needed. Documenting the code properly can be a big help not only to |
1354 | yourself, but to those who will take a look at your code, fix the bugs and even |
598294a7 |
1355 | improve it, in the true open-source spirit that SquirrelMail was built upon. |
a7532db9 |
1356 | |
1357 | For more information about phpdocumentor and how to write proper-tagged |
1358 | comments, you are directed at: |
1359 | |
1360 | http://phpdocu.sourceforge.net/ |
1361 | |
1362 | |
1363 | |
9cd2ae7d |
1364 | PLUGIN STANDARDS AND REQUIREMENTS |
1365 | ================================= |
1366 | |
1367 | The SquirrelMail project has some important goals, such as avoiding the |
1368 | use of JavaScript, avoiding non-standard HTML tags, keeping file sizes |
1369 | small and providing the fastest webmail client on the Internet. As such, |
1370 | we'd like it if plugin authors coded with the same goals in mind that the |
1371 | core developers do. Common sense is always a good tool to have in your |
b6522eb5 |
1372 | programming repertoire, but below is an outline of some standards that we |
1373 | ask you as a plugin developer to meet. Depending upon how far you bend |
1374 | these rules, we may not want to post your plugin on the SquirrelMail |
9cd2ae7d |
1375 | website... and of course, no one really wants your efforts to go to waste |
1376 | and for the SquirrelMail community to miss out on a potentially useful |
1377 | plugin, so please try to follow these guidelines as closely as possible. |
1378 | |
1379 | |
1380 | Small setup.php |
1381 | --------------- |
1382 | |
1383 | In order for SquirrelMail to remain fast and lean, we are now asking |
1384 | that all plugin authors remove all unnecessary functionality from setup.php |
d2b351d7 |
1385 | and refactor it into another file. There are a few ways to accomplish |
9cd2ae7d |
1386 | this, none of which are difficult. At a minimum, you'll want to have the |
1387 | squirrelmail_plugin_init_<plugin name>() function in setup.php, and naturally, |
1388 | you'll need functions that are merely stubs for each hook that you are using. |
1389 | One (but not the only) way to do it is: |
1390 | |
b6522eb5 |
1391 | function squirrelmail_plugin_init_demo() |
9cd2ae7d |
1392 | { |
1393 | global $squirrelmail_plugin_hooks; |
1394 | $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; |
1395 | } |
1396 | function plugin_demo_header() |
1397 | { |
1398 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
1399 | plugin_demo_header_do(); |
1400 | } |
1401 | |
1402 | |
1403 | Internationalization |
1404 | -------------------- |
1405 | |
b6522eb5 |
1406 | Q: What is more disappointing to users in France who would make good |
9cd2ae7d |
1407 | use of your plugin than learning that it is written entirely in English? |
1408 | A: Learning that they cannot send you a French translation file for your |
1409 | plugin. |
1410 | |
1411 | There are thousands of users out there whose native tongue is not English, |
1412 | and when you develop your plugin without going through the three simple steps |
b6522eb5 |
1413 | needed to internationalize it, you are effectively writing them all off. |
9cd2ae7d |
1414 | PLEASE consider internationalizing your plugin! |
1415 | |
1416 | |
1417 | Developing with E_ALL |
1418 | --------------------- |
1419 | |
1420 | When you are developing your plugin, you should always have error reporting |
1421 | turned all the way up. You can do this by changing two settings in your |
1422 | php.ini and restarting your web server: |
1423 | |
799c2046 |
1424 | display_errors = On |
9cd2ae7d |
1425 | error_reporting = E_ALL |
1426 | |
1427 | This way, you'll be sure to see all Notices, Warnings and Errors that your |
1428 | code generates (it's OK, really, it happens to the best of us... except me!). |
1429 | Please make sure to fix them all before you release the plugin. |
1430 | |
1431 | |
1b6b1526 |
1432 | Compatibility with register_globals=Off |
1433 | --------------------------------------- |
1434 | |
1435 | Most sensible systems administrators now run their PHP systems with the |
1436 | setting "register_globals" as OFF. This is a prudent security setting, |
1437 | and as the SquirrelMail core code has long since been upgraded to work |
1438 | in such an environment, we are now requiring that all plugins do the same. |
1439 | Compatibility with this setting amounts to little more than explicitly |
1440 | gathering any and all variables you sent from a <form> tag as GET or POST |
1441 | values instead of just assuming that they will be placed in the global |
1442 | scope automatically. There is nothing more to do than this: |
1443 | |
1444 | global $favorite_color; |
1445 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
1446 | |
6b7579a0 |
1447 | SquirrelMail 1.5.1+ cleans globals in functions/global.php library. If |
1448 | plugin depends on PHP register_globals=On and loads this library, it will |
46cbf588 |
1449 | be broken. |
1450 | |
1b6b1526 |
1451 | |
68549369 |
1452 | Security considerations |
1453 | ----------------------- |
1454 | |
ecc368a8 |
1455 | All plugin authors should consider the security implications of their |
1456 | plugin. Of course, if you call external programs you have to use great |
1457 | care, but the following issues are important to nearly every plugin. |
68549369 |
1458 | |
1459 | - Escape any untrusted data before you output it. This is to prevent |
ecc368a8 |
1460 | cross site scripting attacks. It means that you have to htmlspecialchars() |
68549369 |
1461 | every variable that comes in through the URL, a mail message or other |
1462 | external factors, before outputting it. |
1463 | |
1464 | - Make sure that your plugin doesn't perform its function when it's not |
1465 | enabled. If you just call hooks, your hooks won't be called when the |
1466 | plugin is disabled, but if you also supply extra .php files, you should |
1467 | check if they perform any function if accessed directly. If they do, you |
ecc368a8 |
1468 | should check at the start of that file whether the plugin is enabled in the |
68549369 |
1469 | config, and if not, exit the script. Example: |
1470 | global $plugins; |
1471 | if ( !in_array('mypluginname', $plugins) ) { |
1472 | die("Plugin not enabled in SquirrelMail configuration."); |
1473 | } |
1474 | |
1475 | If you have any questions about this or are unsure, please contact the |
1476 | mailinglist or IRC channel, because security is very important for a |
1477 | widely used application like SquirrelMail! |
1478 | |
1479 | |
9cd2ae7d |
1480 | Extra Blank Lines |
1481 | ----------------- |
1482 | |
1483 | It may seem innocuous, but if you have any blank lines either before the |
1484 | first <?php tag or after the last ?> tag in any of your plugin files, you |
1485 | you will break SquirrelMail in ways that may seem entirely unrelated. For |
1486 | instance, this will often cause a line feed character to be included with |
1487 | email attachments when they are viewed or downloaded, rendering them useless! |
1488 | |
1489 | |
1490 | include_once |
1491 | ------------ |
1492 | |
1493 | When including files, please make sure to use the include_once() function |
b6522eb5 |
1494 | and NOT include(), require(), or require_once(), since these all are much |
1495 | less efficient than include_once() and can have a cumulative effect on |
9cd2ae7d |
1496 | SquirrelMail performance. |
1497 | |
1498 | |
1499 | Version Reporting |
1500 | ----------------- |
1501 | |
1502 | In order for systems administrators to keep better track of your plugin and |
1503 | get upgrades more efficiently, you are requested to make version information |
b6522eb5 |
1504 | available to SquirrelMail in a format that it understands. There are two |
1505 | ways to do this. Presently, we are asking that you do both, since we are |
1506 | still in a transition period between the two. This is painless, so please |
9cd2ae7d |
1507 | be sure to include it: |
1508 | |
1509 | 1. Create a file called "version" in the plugin directory. That file |
1510 | should have only two lines: the first line should have the name of |
1511 | the plugin as named on the SquirrelMail web site (this is often a |
b6522eb5 |
1512 | prettified version of the plugin directory name), the second line |
9cd2ae7d |
1513 | must have the version and nothing more. So for our "demo" plugin, |
b6522eb5 |
1514 | whose name on the web site might be something like "Demo Favorite |
9cd2ae7d |
1515 | Colors", the file plugins/demo/version should have these two lines: |
1516 | |
1517 | Demo Favorite Colors |
1518 | 1.0 |
1519 | |
1520 | 2. In setup.php, you should have a function called <plugin name>_version(). |
1521 | That function should return the version of your plugin. For the "demo" |
1522 | plugin, that should look like this: |
1523 | |
1524 | function demo_version() |
1525 | { |
1526 | return '1.0'; |
1527 | } |
1528 | |
1529 | |
1530 | Configuration Files |
1531 | ------------------- |
1532 | |
1533 | It is common to need a configuration file that holds some variables that |
1534 | are set up at install time. For ease of installation and maintenance, you |
1535 | should place all behavioral settings in a config file, isolated from the |
1536 | rest of your plugin code. A typical file name to use is "config.php". If |
1537 | you are using such a file, you should NOT include a file called "config.php" |
b6522eb5 |
1538 | in your plugin distribution, but instead a copy of that file called |
9cd2ae7d |
1539 | "config.php.sample". This helps systems administrators avoid overwriting |
1540 | the "config.php" files and losing all of their setup information when they |
1541 | upgrade your plugin. |
1542 | |
1543 | |
1544 | Session Variables |
1545 | ----------------- |
1546 | |
1547 | In the past, there have been some rather serious issues with PHP sessions |
1548 | and SquirrelMail, and certain people have worked long and hard to ensure |
1549 | that these problems no longer occur in an extremely wide variety of OS/PHP/ |
b6522eb5 |
1550 | web server environments. Thus, if you need to place any values into the |
1551 | user's session, there are some built-in SquirrelMail functions that you are |
9cd2ae7d |
1552 | strongly encouraged to make use of. Using them also makes your job easier. |
1553 | |
1554 | 1. To place a variable into the session: |
1555 | |
b6522eb5 |
1556 | global $favorite_color; |
9cd2ae7d |
1557 | $favoriteColor = 'green'; |
1558 | sqsession_register($favorite_color, 'favorite_color'); |
1559 | |
1560 | Strictly speaking, globalizing the variable shouldn't be necessary, |
1561 | but certain versions of PHP seem to behave more predictably if you do. |
1562 | |
1563 | 2. To retrieve a variable from the session: |
1564 | |
1565 | global $favorite_color; |
1566 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_SESSION); |
1567 | |
1568 | 3. You can also check for the presence of a variable in the session: |
1569 | |
1570 | if (sqsession_is_registered('favorite_color')) |
1571 | // do something important |
1572 | |
1573 | 4. To remove a variable from the session: |
1574 | |
ea26c996 |
1575 | global $favorite_color; |
9cd2ae7d |
1576 | sqsession_unregister('favorite_color'); |
1577 | |
ea26c996 |
1578 | Strictly speaking, globalizing the variable shouldn't be necessary, |
1579 | but certain versions of PHP seem to behave more predictably if you do. |
1580 | |
9cd2ae7d |
1581 | |
1582 | Form Variables |
1583 | -------------- |
1584 | |
b6522eb5 |
1585 | You are also encouraged to use SquirrelMail's built-in facilities to |
9cd2ae7d |
1586 | retrieve variables from POST and GET submissions. This is also much |
1587 | easier on you and makes sure that all PHP installations are accounted |
b6522eb5 |
1588 | for (such as those that don't make the $_POST array automatically |
9cd2ae7d |
1589 | global, etc.): |
1590 | |
1591 | global $favorite_color; |
1592 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
1593 | |
1594 | |
1595 | Files In Plugin Directory |
1596 | ------------------------- |
1597 | |
1598 | There are a few files that you should make sure to include when you build |
1599 | your final plugin distribution: |
1600 | |
b6522eb5 |
1601 | 1. A copy of the file index.php from the main plugins directory. When |
9cd2ae7d |
1602 | working in your plugin directory, just copy it in like this: |
1603 | |
1604 | $ cp ../index.php . |
1605 | |
1606 | This will redirect anyone who tries to browse to your plugin directory |
1607 | to somewhere more appropriate. If you create other directories under |
1608 | your plugin directory, you may copy the file there as well to be extra |
1609 | safe. If you are storing sensitive configuration files or other data |
1610 | in such a directory, you could even include a .htaccess file with the |
b6522eb5 |
1611 | contents "Deny From All" that will disallow access to that directory |
9cd2ae7d |
1612 | entirely (when the target system is running the Apache web server). |
1613 | Keep in mind that not all web servers will honor an .htaccess file, so |
1614 | don't depend on it for security. Make sure not to put such a file in |
1615 | your main plugin directory! |
1616 | |
b6522eb5 |
1617 | 2. A file that describes your plugin and offers detailed instructions for |
1618 | configuration or help with troubleshooting, etc. This file is usually |
9cd2ae7d |
1619 | entitled "README". Some useful sections to include might be: |
1620 | |
1621 | Plugin Name and Author |
1622 | Current Version |
1623 | Plugin Features |
1624 | Detailed Plugin Description |
1625 | How-to for Plugin Configuration |
1626 | Change Log |
1627 | Future Ideas/Enhancements/To Do List |
1628 | |
1629 | 3. A file that explains how to install your plugin. This file is typically |
b6522eb5 |
1630 | called "INSTALL". If you do not require any special installation |
9cd2ae7d |
1631 | actions, you can probably copy one from another plugin or use this as |
1632 | a template: |
1633 | |
1634 | Installing the Demo Plugin |
1635 | ========================== |
1636 | |
1637 | 1) Start with untaring the file into the plugins directory. |
1638 | Here is a example for the 1.0 version of the Demo plugin. |
1639 | |
1640 | $ cd plugins |
1641 | $ tar -zxvf demo-1.0-1.4.0.tar.gz |
1642 | |
1643 | 2) Change into the demo directory, copy config.php.sample |
1644 | to config.php and edit config.php, making adjustments as |
1645 | you deem necessary. For more detailed explanations about |
1646 | each of these parameters, consult the README file. |
b6522eb5 |
1647 | |
9cd2ae7d |
1648 | $ cd demo |
1649 | $ cp config.php.sample config.php |
1650 | $ vi config.php |
b6522eb5 |
1651 | |
1652 | |
9cd2ae7d |
1653 | 3) Then go to your config directory and run conf.pl. Choose |
1654 | option 8 and move the plugin from the "Available Plugins" |
1655 | category to the "Installed Plugins" category. Save and exit. |
b6522eb5 |
1656 | |
9cd2ae7d |
1657 | $ cd ../../config/ |
1658 | $ ./conf.pl |
b6522eb5 |
1659 | |
9cd2ae7d |
1660 | |
1661 | Upgrading the Demo Plugin |
1662 | ========================= |
1663 | |
1664 | 1) Start with untaring the file into the plugins directory. |
1665 | Here is a example for the 3.1 version of the demo plugin. |
1666 | |
1667 | $ cd plugins |
1668 | $ tar -zxvf demo-3.1-1.4.0.tar.gz |
1669 | |
1670 | |
1671 | 2) Change into the demo directory, check your config.php |
1672 | file against the new version, to see if there are any new |
1673 | settings that you must add to your config.php file. |
1674 | |
1675 | $ diff -Nau config.php config.php.sample |
b6522eb5 |
1676 | |
9cd2ae7d |
1677 | Or simply replace your config.php file with the provided sample |
1678 | and reconfigure the plugin from scratch (see step 2 under the |
1679 | installation procedure above). |
1680 | |
1681 | |
1682 | COMPATIBILITY WITH OLDER VERSIONS OF SQUIRRELMAIL |
1683 | ================================================= |
1684 | |
1685 | Whenever new versions of SquirrelMail are released, there is always a |
1686 | considerable lag time before it is widely adopted. During that transitional |
1687 | time, especially when the new SquirrelMail version contains any architectural |
1688 | and/or functional changes, plugin developers are put in a unique and very |
1689 | difficult position. That is, there will be people running both the old and |
b6522eb5 |
1690 | new versions of SquirrelMail who want to use your plugin, and you will |
9cd2ae7d |
1691 | probably want to accomodate them both. |
1692 | |
1693 | The easiest way to keep both sides happy is to keep two different versions |
1694 | of your pluign up to date, one that runs under the older SquirrelMail, and |
1695 | one that requires the newest SquirrelMail. This is inconvenient, however, |
1696 | especially if you are continuing to develop the plugin. Depending on the |
1697 | changes the SquirrelMail has implemented in the new version, you may be able |
1698 | to include code that can auto-sense SquirrelMail version and make adjustments |
b6522eb5 |
1699 | on the fly. There is a function available to you for determining the |
9cd2ae7d |
1700 | SquirrelMail version called check_sm_version() and it can be used as such: |
1701 | |
1702 | check_sm_version(1, 4, 0) |
1703 | |
1704 | This will return TRUE if the SquirrelMail being used is at least 1.4.0, and |
1705 | FALSE otherwise. |
1706 | |
1707 | As this document is written, we are in a transition period between versions |
1708 | 1.2.11 and 1.4.0. There is a plugin called "Compatibilty" that is intended |
1709 | for use by plugin authors so they can develop one version of their plugin |
1710 | and seamlessly support both 1.2.x and 1.4.x SquirrelMail installations. For |
1711 | more information about how to use the "Compatibility" plugin, download it and |
1712 | read its README file or see: |
1713 | |
e07525be |
1714 | http://www.squirrelmail.org/wiki/PluginUpgrading |
9cd2ae7d |
1715 | |
1716 | |
1717 | REQUESTING NEW HOOKS |
1718 | ==================== |
1719 | |
1720 | It's impossible to foresee all of the places where hooks might be useful |
1721 | (it's also impossible to put in hooks everywhere!), so you might need to |
1722 | negotiate the insertion of a new hook to make your plugin work. In order |
1723 | to do so, you should post such a request to the squirrelmail-devel mailing |
1724 | list. |
1725 | |
1726 | |
1727 | HOW TO RELEASE YOUR PLUGIN |
1728 | ========================== |
1729 | |
1730 | As long as you've consulted the list of plugin standards and done your |
1731 | best to follow them, there's little standing in the way of great fame as an |
1732 | official SquirrelMail plugin developer. |
1733 | |
1734 | 1. Make a distribution file. There is a convenient Perl script in |
1735 | the plugins directory that will help you do this: |
1736 | |
1737 | make_archive.pl -v demo 1.0 1.4.0 |
1738 | |
1739 | -v is optional and indicates that the script should run in verbose mode |
1740 | demo is the name of your plugin |
1741 | 1.0 is the version of your plugin |
1742 | 1.4.0 is the version of SquirrelMail that is required to run your plugin |
1743 | |
b6522eb5 |
1744 | You can also create the distribution file manually in most *nix |
1745 | environments by running this command from the plugins directory (NOT |
9cd2ae7d |
1746 | your plugin directory): |
1747 | |
1748 | $ tar czvf demo-1.0-1.4.0.tar.gz demo |
1749 | |
1750 | Where "demo" is the name of your plugin, "1.0" is the version of |
1751 | your plugin, and "1.4.0" is the version of SquirrelMail required |
1752 | to use your plugin. |
1753 | |
1754 | 2. Consult the SquirrelMail web site for contact information for the |
b6522eb5 |
1755 | Plugins Team Leaders, to whom you should make your request. If they |
1756 | do not respond, you should feel free to ask for help contacting them |
9cd2ae7d |
1757 | on the squirrelmail-plugins mailing list. |
1758 | |
e07525be |
1759 | http://www.squirrelmail.org/wiki/SquirrelMailLeadership |
9cd2ae7d |
1760 | |