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