3 In addition to this document, please check out the SquirrelMail
4 development FAQ for more information. Also, help writing plugins
5 is easily obtained by posting to the squirrelmail-plugins mailing
6 list. (See details about mailing lists on the website)
8 FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
10 http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
13 A FEW NOTES ON THE PLUGIN ARCHITECTURE
14 ======================================
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
19 be possible to add as plugins.
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".
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.
34 Some way for the plugins to interact with the help subsystem and
35 translations will be provided.
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,
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
49 hook name provided by the SquirrelMail developers.
51 A plugin must reside in a subdirectory in the plugins/ directory. The
52 name of the subdirectory is considered to be the name of the plugin.
53 (The plugin will not function correctly if this is not the case.)
55 To start using a plugin, its name must be added to the $plugins array
56 in config.php like this:
58 $plugins[0] = 'plugin_name';
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
62 called with no parameters. That function is where the plugin may
63 register itself against any hooks it wishes to take advantage of.
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
74 more than call another function in a different file.
76 Any other files used by the plugin should also be placed in the
77 plugin directory (or subdirectory thereof) and should contain the
78 bulk of the plugin logic.
80 The function squirrelmail_plugin_init_plugin_name() is called to
81 initalize a plugin. This function could look something like this (if
82 the plugin was named "demo" and resided in the directory plugins/demo/):
84 function squirrelmail_plugin_init_demo ()
86 global $squirrelmail_plugin_hooks;
88 $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header';
89 $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline';
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-
94 time. Thus, the inclusion of any dynamic code (anything except hook
95 registration) here is strongly discouraged.
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:
101 function plugin_demo_header()
103 include_once(SM_PATH . 'plugins/demo/functions.php');
104 plugin_demo_header_do();
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.
112 Including Other Files
113 ---------------------
115 A plugin may need to reference functionality provided in other
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
119 browser (custom options page, etc.). In this case, you'll need
120 to make sure you include the files you need (see below).
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
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,
128 you will need to define this constant before you do anything else:
130 define('SM_PATH', '../../');
132 Files are included like this:
134 include_once(SM_PATH . 'include/validate.php');
136 When including files, please make sure to use the include_once() function
137 and NOT include(), require(), or require_once(), since these all are much
138 less efficient than include_once() and can have a cumulative effect on
139 SquirrelMail performance.
141 The files that you may need to include in a plugin will vary greatly
142 depending upon what the plugin is designed to do. For files that are
143 requested directly by the client browser, we strongly recommend that
144 you include the file include/validate.php, since it will set up the
145 SquirrelMail environment automatically. It will ensure the the user
146 has been authenticated and is currently logged in, load all user
147 preferences, include internationalization support, call stripslashes()
148 on all incoming data (if magic_quotes_gpc is on), and initialize and
149 include all other basic SquirrelMail resources and functions. You may
150 see other plugins that directly include other SquirrelMail files, but
151 that is no longer necessary and is a hold-over from older SquirrelMail
154 List of files, that are included by include/validate.php (If SquirrelMail
155 version 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
166 3. functions/strings.php
168 4.1. config/config_local.php (from 1.4.0rc1)
169 5. functions/i18n.php
170 5.1. functions/global.php (from 1.4.0)
171 6. functions/auth.php
172 7. include/load_prefs.php
173 7.1. include/validate.php
174 7.2. functions/prefs.php
175 7.3. functions/plugin.php
176 7.3.1. functions/global.php (from 1.4.0 and 1.5.0)
177 7.3.2. functions/prefs.php (from 1.5.1)
178 7.4. functions/constants.php
179 7.5. do_hook('loading_prefs')
180 7.5.1. files loaded by plugins that use 'loading_prefs'
181 8. functions/page_header.php
182 8.1. functions/strings.php
183 8.2. functions/html.php
184 8.3. functions/imap_mailbox.php
185 8.3.1. functions/imap_utf7_local.php
186 8.4. functions/global.php
187 9. functions/prefs.php
188 9.1. functions/global.php
189 9.2. $prefs_backend (only in 1.4.3 and 1.5.0)
190 do_hook_function('prefs_backend') (since 1.4.4 and 1.5.1)
191 functions/db_prefs.php
192 functions/file_prefs.php
193 9.2.1. functions/display_messages.php
194 (loaded only by file_prefs.php)
195 9.2.2. files loaded by plugin that uses 'prefs_backend'
197 Hook Types: Parameters and Return Values
198 -----------------------------------------
200 Hooks, when executed, are called with differing parameters and may or may
201 not take return values, all depending on the type of hook being called and
202 the context in which it is being used. On the source side (where the hook
203 call originates), all hooks have at least one parameter, which is the
204 name of the hook. After that, things get complicated.
208 Most hook calls don't pass any data and don't ask for anything back.
209 These always use the do_hook call. A limited number of do_hook calls do
210 pass some extra parameters, in which case your plugin may modify the
211 given data if you do so by reference. It is not necessary to return
212 anything from your function in such a case; modifying the parameter
213 data by reference is what does the job (although the hook call itself
214 (in the source) must grab the return value for this to work). Note
215 that in this case, the parameter to your hook function will be an array,
216 the first element simply being the hook name, followed by any other
217 parameters that may have been included in the actual hook call in the
218 source. Modify parameters with care!
222 This hook type was intended to be the main hook type used when the
223 source needs to get something back from your plugin. It is somewhat
224 limited in that it will only use the value returned from the LAST
225 plugin registered against the hook. The source for this hook might
226 use the return value for internal purposes, or might expect you to
227 provide text or HTML to be sent to the client browser (you'll have to
228 look at its use in context to understand how you should return values
229 here). The parameters that your hook function gets will be anything
230 you see AFTER the hook name in the actual hook call in the source.
231 These cannot be changed in the same way that the do_hook parameters
236 This is a newer hook type meant to address the shortcomings of
237 do_hook_function; specifically in that it uses the return values of
238 all plugins registered against the hook. In order to do so, the
239 return value is assumed to be a string, which is just piled on top
240 of whatever it got from the other plugins working on the same hook.
241 Again, you'll have to inspect the source code to see how such data
242 is put to use, but most of the time, it is used to create a string
243 of HTML to be inserted into the output page. The parameters that
244 your hook function will get are the same as for the do_hook_function;
245 they are anything AFTER the hook name in the actual hook call in the
248 boolean_hook_function
249 ---------------------
250 The newest of the SquirrelMail hooks, this type is used to let all
251 plugins registered against the hook to "vote" for some action. What
252 that action is is entirely dependent on how the hook is used in the
253 source (look for yourself). Plugins make their "vote" by returning
254 TRUE or FALSE. This hook may be configured to "tally votes" in one
255 of three ways. This configuration is done with the third parameter
256 in the hook call in the source:
257 > 0 -- Any one or more TRUEs will override any FALSEs
258 < 0 -- Any one or more FALSEs will override any TRUEs
259 = 0 -- Majority wins. Ties are broken in this case with
260 the last parameter in the hook call in the source.
261 Your hook function will get the second paramter in the hook call in
262 the source as its parameter (this might be an array if multiple values
265 See below for further discussion of special hook types and the values
271 This is a list of all hooks currently available in SquirrelMail, ordered
272 by file. Note that this list is accurate as of June 17, 2003 (should be
273 close to what is contained in release 1.4.1, plus or minus a hook or two),
274 but may be out of date soon thereafter. You never know. ;-)
276 Hook Name Found In Called With(#)
277 --------- -------- --------------
278 abook_init functions/addressbook.php do_hook
279 abook_add_class functions/addressbook.php do_hook
280 loading_constants functions/constants.php do_hook
281 logout_error functions/display_messages.php do_hook
282 error_box functions/display_messages.php concat_hook
283 get_pref_override functions/file_prefs.php hook_func
284 get_pref functions/file_prefs.php hook_func
285 & options_identities_process functions/identity.php do_hook
286 &% options_identities_renumber functions/identity.php do_hook
287 special_mailbox functions/imap_mailbox.php hook_func
288 % rename_or_delete_folder functions/imap_mailbox.php hook_func
289 mailbox_index_before functions/mailbox_display.php do_hook
290 mailbox_form_before functions/mailbox_display.php do_hook
291 mailbox_index_after functions/mailbox_display.php do_hook
292 check_handleAsSent_result functions/mailbox_display.php do_hook
293 subject_link functions/mailbox_display.php concat_hook
294 mailbox_display_buttons functions/mailbox_display.php do_hook
295 mailbox_display_button_action functions/mailbox_display.php hook_func
296 message_body functions/mime.php do_hook
297 ^ attachment $type0/$type1 functions/mime.php do_hook
298 attachments_bottom functions/mime.php hook_func
299 decode_body functions/mime.php hook_func
300 generic_header functions/page_header.php do_hook
301 menuline functions/page_header.php do_hook
302 prefs_backend functions/prefs.php hook_func
303 loading_prefs include/load_prefs.php do_hook
304 addrbook_html_search_below src/addrbook_search_html.php do_hook
305 addressbook_bottom src/addressbook.php do_hook
306 compose_form src/compose.php do_hook
307 compose_bottom src/compose.php do_hook
308 compose_button_row src/compose.php do_hook
309 compose_send src/compose.php do_hook
310 folders_bottom src/folders.php do_hook
311 help_top src/help.php do_hook
312 help_chapter src/help.php do_hook
313 help_bottom src/help.php do_hook
314 left_main_after_each_folder src/left_main.php concat_hook
315 left_main_before src/left_main.php do_hook
316 left_main_after src/left_main.php do_hook
317 login_cookie src/login.php do_hook
318 login_top src/login.php do_hook
319 login_form src/login.php concat_hook
320 (was do_hook before 1.5.1)
321 login_bottom src/login.php do_hook
322 * optpage_set_loadinfo src/options.php do_hook
323 * optpage_loadhook_personal src/options.php do_hook
324 * optpage_loadhook_display src/options.php do_hook
325 * optpage_loadhook_highlight src/options.php do_hook
326 * optpage_loadhook_folder src/options.php do_hook
327 * optpage_loadhook_order src/options.php do_hook
328 * options_personal_save src/options.php do_hook
329 * options_display_save src/options.php do_hook
330 * options_folder_save src/options.php do_hook
331 * options_save src/options.php do_hook
332 * optpage_register_block src/options.php do_hook
333 * options_link_and_description src/options.php do_hook
334 * options_personal_inside src/options.php do_hook
335 * options_display_inside src/options.php do_hook
336 * options_highlight_inside src/options.php do_hook
337 * options_folder_inside src/options.php do_hook
338 * options_order_inside src/options.php do_hook
339 * options_personal_bottom src/options.php do_hook
340 * options_display_bottom src/options.php do_hook
341 * options_highlight_bottom src/options.php do_hook
342 * options_folder_bottom src/options.php do_hook
343 * options_order_bottom src/options.php do_hook
344 * options_highlight_bottom src/options_highlight.php do_hook
345 & options_identities_top src/options_identities.php do_hook
346 & options_identities_table src/options_identities.php concat_hook
347 & options_identities_buttons src/options_identities.php concat_hook
348 message_body src/printer_friendly_bottom.php do_hook
349 read_body_header src/read_body.php do_hook
350 read_body_menu_top src/read_body.php hook_func
351 read_body_menu_bottom src/read_body.php do_hook
352 read_body_header_right src/read_body.php do_hook
353 read_body_top src/read_body.php do_hook
354 read_body_bottom src/read_body.php do_hook
355 login_before src/redirect.php do_hook
356 login_verified src/redirect.php do_hook
357 right_main_after_header src/right_main.php do_hook
358 right_main_bottom src/right_main.php do_hook
359 search_before_form src/search.php do_hook
360 search_after_form src/search.php do_hook
361 search_bottom src/search.php do_hook
362 logout src/signout.php do_hook
363 webmail_top src/webmail.php do_hook
364 webmail_bottom src/webmail.php concat_hook
365 logout_above_text src/signout.php concat_hook
366 O info_bottom plugins/info/options.php do_hook
368 % = This hook is used in multiple places in the given file
369 # = Called with hook type (see below)
370 & = Special identity hooks (see below)
371 ^ = Special attachments hook (see below)
372 * = Special options hooks (see below)
373 O = Optional hook provided by a particular plugin
378 Each hook is called using the hook type specified in the list above:
380 hook_func do_hook_function()
381 concat_hook concat_hook_function()
386 This set of hooks is passed special information in the array of arguments:
388 options_identities_process
390 This hook is called at the top of the Identities page, which is
391 most useful when the user has changed any identity settings - this
392 is where you'll want to save any custom information you are keeping
393 for each identity or catch any custom submit buttons that you may
394 have added to the identities page. The arguments to this hook are:
396 (SquirrelMail 1.4.4 or older and 1.5.0)
397 [0] = hook name (always "options_identities_process")
398 [1] = should I run the SaveUpdateFunction() (alterable)
400 Obviously, set the second array element to 1/true if you want to
401 trigger SaveUpdateFunction() after the hook is finished - by default,
402 it will not be called.
404 (SquirrelMail 1.4.6+ or 1.5.1+)
405 [0] = hook name (always "options_identities_process")
406 [1] = action (hook is used only in 'update' action and any custom
407 action added to form with option_identities_table and
408 option_identities_buttons hooks)
409 [2] = processed identity number
411 Hook is not available in SquirrelMail 1.4.5.
413 options_identities_renumber
415 This hook is called when one of the identities is being renumbered,
416 such as if the user had three identities and deletes the second -
417 this hook would be called with an array that looks like this:
418 ('options_identities_renumber', 2, 1). The arguments to this hook
421 [0] = hook name (always "options_identities_renumber")
422 [1] = being renumbered from ('default' or 1 through (# idents) - 1)
423 [2] = being renumbered to ('default' or 1 through (# idents) - 1)
425 Hook is not available in SquirrelMail 1.4.5. Renumbering order differs
426 in 1.4.5+ and 1.5.1+.
428 options_identities_table
430 This hook allows you to insert additional rows into the table that
431 holds each identity. The arguments to this hook are:
433 [0] = additional html attributes applied to table row.
434 use it like this in your plugin:
435 <tr "<?php echo $args[0]; ?>">
436 [1] = is this an empty section (the one at the end of the list)?
437 [2] = what is the 'post' value? (ident # or empty string if default)
439 You need to return any HTML you would like to add to the table.
440 You could add a table row with code similar to this:
442 function demo_identities_table(&$args)
444 return '<tr bgcolor="' . $args[0] . '"><td> </td><td>'
445 . 'YOUR CODE HERE' . '</td></tr>' . "\n";
448 First hook argument was modified in 1.4.5/1.5.1. In SquirrelMail 1.4.1-1.4.4
449 and 1.5.0 argument contains only background color. You should use
450 <tr bgcolor="<?php echo $args[0]; ?>"> in these SquirrelMail versions.
452 options_identities_buttons
454 This hook allows you to add a button (or other HTML) to the row of
455 buttons under each identity. The arguments to this hook are:
457 [0] = is this an empty section (the one at the end of the list)?
458 [1] = what is the 'post' value? (ident # or empty string if default)
460 You need to return any HTML you would like to add here. You could add
461 a button with code similar to this:
463 function demo_identities_button(&$args)
465 return '<input type="submit" name="demo_button_' . $args[1]
466 . '" value="Press Me" />';
469 Input element should use 'smaction[action_name][identity_no]' value in
470 'name' attribute, if you want to process your button actions in
471 SquirrelMail 1.4.6+ and 1.5.1+ options_identity_process hook.
474 See sample implementation of identity hooks in SquirrelMail demo plugin.
476 cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/squirrelmail \
482 When a message has attachments, this hook is called with the MIME types. For
483 instance, a .zip file hook is "attachment application/x-zip". The hook should
484 probably show a link to do a specific action, such as "Verify" or "View" for a
485 .zip file. Thus, to register your plugin for .zip attachments, you'd do this
486 in setup.php (assuming your plugin is called "demo"):
488 $squirrelmail_plugin_hooks['attachment application/x-zip']['demo']
489 = 'demo_handle_zip_attachment';
491 This is a breakdown of the data passed in the array to the hook that is called:
493 [0] = Hook's name ('attachment text/plain')
494 [1] = Array of links of actions (see below) (alterable)
495 [2] = Used for returning to mail message (startMessage)
496 [3] = Used for finding message to display (id)
497 [4] = Mailbox name, urlencode()'d (urlMailbox)
498 [5] = Entity ID inside mail message (ent)
499 [6] = Default URL to go to when filename is clicked on (alterable)
500 [7] = Filename that is displayed for the attachment
501 [8] = Sent if message was found from a search (where)
502 [9] = Sent if message was found from a search (what)
504 To set up links for actions, you assign them like this:
506 $Args[1]['<plugin_name>']['href'] = 'URL to link to';
507 $Args[1]['<plugin_name>']['text'] = _("What to display");
508 $Args[1]['<plugin_name>']['extra'] = 'extra stuff, such as an <img ...> tag';
510 Note: _("What to display") is explained in the section about
511 internationalization.
513 You can leave the 'text' empty and put an image tag in 'extra' to show an
514 image-only link for the attachment, or do the opposite (leave 'extra' empty)
515 to display a text-only link.
517 It's also possible to specify a hook as "attachment type0/*",
518 for example "attachment text/*". This hook will be executed whenever there's
519 no more specific rule available for that type.
521 Putting all this together, the demo_handle_zip_attachment() function should
522 look like this (note the argument being passed):
524 function demo_handle_zip_attachment(&$Args)
526 include_once(SM_PATH . 'plugins/demo/functions.php');
527 demo_handle_zip_attachment_do($Args);
530 And the demo_handle_zip_attachment_do() function in the
531 plugins/demo/functions.php file would typically (but not necessarily)
532 display a custom link:
534 function demo_handle_zip_attachment_do(&$Args)
536 $Args[1]['demo']['href'] = SM_PATH . 'plugins/demo/zip_handler.php?'
537 . 'passed_id=' . $Args[3] . '&mailbox=' . $Args[4]
538 . '&passed_ent_id=' . $Args[5];
539 $Args[1]['demo']['text'] = _("Show zip contents");
542 The file plugins/demo/zip_handler.php can now do whatever it needs with the
543 attachment (note that this will hand information about how to retrieve the
544 source message from the IMAP server as GET varibles).
549 Before you start adding user preferences to your plugin, please take a moment
550 to think about it: in some cases, more options may not be a good thing.
551 Having too many options can be confusing. Thinking from the user's
552 perspective, will the proposed options actually be used? Will users
553 understand what these options are for?
555 There are two ways to add options for your plugin. When you only have a few
556 options that don't merit an entirely new preferences page, you can incorporate
557 them into an existing section of SquirrelMail preferences (Personal
558 Information, Display Preferences, Message Highlighting, Folder Preferences or
559 Index Order). Or, if you have an extensive number of settings or for some
560 reason need a separate page for the user to interact with, you can create your
561 own preferences page.
564 Integrating Your Options Into Existing SquirrelMail Preferences Pages
565 ---------------------------------------------------------------------
567 There are two ways to accomplish the integration of your plugin's settings
568 into another preferences page. The first method is to add the HTML code
569 for your options directly to the preferences page of your choice. Although
570 currently very popular, this method will soon be deprecated, so avoid it
571 if you can. That said, here is how it works. :) Look for any of the hooks
572 named as "options_<pref page>_inside", where <pref page> is "display",
573 "personal", etc. For this example, we'll use "options_display_inside" and,
574 as above, "demo" as our plugin name:
576 1. In setup.php in the squirrelmail_plugin_init_demo() function:
578 $squirrelmail_plugin_hooks['options_display_inside']['demo']
579 = 'demo_show_options';
581 Note that there are also hooks such as "options_display_bottom",
582 however, they place your options at the bottom of the preferences
583 page, which is usually not desirable (mostly because they also
584 come AFTER the HTML FORM tag is already closed). It is possible
585 to use these hooks if you want to create your own FORM with custom
588 2. Assuming the function demo_show_options() calls another function
589 elsewhere called demo_show_options_do(), that function should have
590 output similar to this (note that you will be inserting code into
591 a table that is already defined with two columns, so please be sure
592 to keep this framework in your plugin):
594 ------cut here-------
603 ------cut here-------
605 Of course, you can place any text where OPTION_NAME is and any input
606 tags where OPTION_INPUT is.
608 3. You will want to use the "options_<pref page>_save" hook (in this case,
609 "options_display_save") to save the user's settings after they have
610 pressed the "Submit" button. Again, back in setup.php in the
611 squirrelmail_plugin_init_demo() function:
613 $squirrelmail_plugin_hooks['options_display_save']['demo']
614 = 'demo_save_options';
616 4. Assuming the function demo_save_options() calls another function
617 elsewhere called demo_save_options_do(), that function should put
618 the user's settings into permanent storage (see the preferences
619 section below for more information). This example assumes that
620 in the preferences page, the INPUT tag's NAME attribute was set
623 global $data_dir, $username;
624 sqgetGlobalVar('demo_option', $demo_option);
625 setPref($data_dir, $username, 'demo_option', $demo_option);
628 The second way to add options to one of the SquirrelMail preferences page is
629 to use one of the "optpage_loadhook_<pref page>" hooks. The sent_subfolders
630 plugin has an excellent example of this method. Briefly, this way of adding
631 options consists of adding some plugin-specific information to a predefined
632 data structure which SquirrelMail then uses to build the HTML input forms
633 for you. This is the preferred method of building options lists going forward.
635 1. We'll use the "optpage_loadhook_display" hook to add a new group of
636 options to the display preferences page. In setup.php in the
637 squirrelmail_plugin_init_demo() function:
639 $squirrelmail_plugin_hooks['optpage_loadhook_display']['demo']
642 2. Assuming the function demo_options() calls another function elsewhere
643 called demo_options_do(), that function needs to add a new key to two
644 arrays, $optpage_data['grps'] and $optpage_data['vals']. The value
645 associated with that key should simply be a section heading for your
646 plugin on the preferences page for the $optpage_data['grps'] array,
647 and yet another array with all of your plugin's options for the
648 $optpage_data['vals'] array. The options are built as arrays (yes,
649 that's four levels of nested arrays) that specify attributes that are
650 used by SquirrelMail to build your HTML input tags automatically.
651 This example includes just one input element, a SELECT (drop-down)
654 global $optpage_data;
655 $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options';
656 $optionValues = array();
657 $optionValues[] = array(
658 'name' => 'plugin_demo_favorite_color',
659 'caption' => 'Please Choose Your Favorite Color',
660 'type' => SMOPT_TYPE_STRLIST,
661 'refresh' => SMOPT_REFRESH_ALL,
662 'posvals' => array(0 => 'red',
666 'save' => 'save_plugin_demo_favorite_color'
668 $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues;
670 The array that you use to specify each plugin option has the following
673 name The name of this setting, which is used not only for
674 the INPUT tag name, but also for the name of this
675 setting in the user's preferences
676 caption The text that prefaces this setting on the preferences
678 trailing_text Text that follows a text input or select list input on
679 the preferences page (useful for indicating units,
680 meanings of special values, etc.)
681 type The type of INPUT element, which should be one of:
682 SMOPT_TYPE_STRING String/text input
683 SMOPT_TYPE_STRLIST Select list input
684 SMOPT_TYPE_TEXTAREA Text area input
685 SMOPT_TYPE_INTEGER Integer input
686 SMOPT_TYPE_FLOAT Floating point number input
687 SMOPT_TYPE_BOOLEAN Boolean (yes/no radio buttons)
689 SMOPT_TYPE_HIDDEN Hidden input (not actually
690 shown on preferences page)
691 SMOPT_TYPE_COMMENT Text is shown (specified by the
692 'comment' attribute), but no
694 SMOPT_TYPE_FLDRLIST Select list of IMAP folders
695 refresh Indicates if a link should be shown to refresh part or
696 all of the window (optional). Possible values are:
697 SMOPT_REFRESH_NONE No refresh link is shown
698 SMOPT_REFRESH_FOLDERLIST Link is shown to refresh
700 SMOPT_REFRESH_ALL Link is shown to refresh
702 initial_value The value that should initially be placed in this
704 posvals For select lists, this should be an associative array,
705 where each key is an actual input value and the
706 corresponding value is what is displayed to the user
707 for that list item in the drop-down list
708 value Specify the default/preselected value for this option
710 save You may indicate that special functionality needs to be
711 used instead of just saving this setting by giving the
712 name of a function to call when this value would
713 otherwise just be saved in the user's preferences
714 size Specifies the size of certain input items (typically
715 textual inputs). Possible values are:
722 comment For SMOPT_TYPE_COMMENT type options, this is the text
723 displayed to the user
724 script This is where you may add any additional javascript
725 or other code to the user input
726 post_script You may specify some script (usually Javascript) that
727 will be placed after (outside of) the INPUT tag.
728 htmlencoded disables html sanitizing. WARNING - don't use it, if user
729 input is possible in option or use own sanitizing functions.
730 Currently works only with SMOPT_TYPE_STRLIST.
732 Note that you do not have to create a whole new section on the options
733 page if you merely want to add a simple input item or two to an options
734 section that already exists. For example, the Display Options page has
737 0 - General Display Options
738 1 - Mailbox Display Options
739 2 - Message Display and Composition
741 To add our previous input drop-down to the Mailbox Display Options,
742 we would not have to create our own group; just add it to group
745 global $optpage_data;
746 $optpage_data['vals'][1][] = array(
747 'name' => 'plugin_demo_favorite_color',
748 'caption' => 'Please Choose Your Favorite Color',
749 'type' => SMOPT_TYPE_STRLIST,
750 'refresh' => SMOPT_REFRESH_ALL,
751 'posvals' => array(0 => 'red',
755 'save' => 'save_plugin_demo_favorite_color'
758 3. If you indicated a 'save' attribute for any of your options, you must
759 create that function (you'll only need to do this if you need to do
760 some special processing for one of your settings). The function gets
761 one parameter, which is an object with mostly the same attributes you
762 defined when you made the option above... the 'new_value' (and possibly
763 'value', which is the current value for this setting) is the most useful
764 attribute in this context:
766 function save_plugin_demo_favorite_color($option)
768 // if user chose orange, make note that they are really dumb
769 if ($option->new_value == 3)
771 // more code here as needed
774 // don't even save this setting if user chose green (old
775 // setting will remain)
776 if ($option->new_value == 2)
779 // for all other colors, save as normal
780 save_option($option);
784 Creating Your Own Preferences Page
785 ----------------------------------
787 It is also possible to create your own preferences page for a plugin. This
788 is particularly useful when your plugin has numerous options or needs to
789 offer special interaction with the user (for things such as changing password,
790 etc.). Here is an outline of how to do so (again, using the "demo" plugin
793 1. Add a new listing to the main Options page. Older versions of
794 SquirrelMail offered a hook called "options_link_and_description"
795 although its use is deprecated (and it is harder to use in that
796 it requires you to write your own HTML to add the option). Instead,
797 you should always use the "optpage_register_block" hook where you
798 create a simple array that lets SquirrelMail build the HTML
799 to add the plugin options entry automatically. In setup.php in the
800 squirrelmail_plugin_init_demo() function:
802 $squirrelmail_plugin_hooks['optpage_register_block']['demo']
803 = 'demo_options_block';
805 2. Assuming the function demo_options_block() calls another function
806 elsewhere called demo_options_block_do(), that function only needs
807 to create a simple array and add it to the $optpage_blocks array:
809 global $optpage_blocks;
810 $optpage_blocks[] = array(
811 'name' => 'Favorite Color Settings',
812 'url' => SM_PATH . 'plugins/demo/options.php',
813 'desc' => 'Change your favorite color & find new exciting colors',
817 The array should have four elements:
818 name The title of the plugin's options as it will be displayed on
820 url The URI that points to your plugin's custom preferences page
821 desc A description of what the preferences page offers the user,
822 displayed on the Options page below the title
823 js Indicates if this option page requires the client browser
824 to be Javascript-capable. Should be TRUE or FALSE.
826 3. There are two different ways to create the actual preferences page
827 itself. One is to simply write all of your own HTML and other
828 interactive functionality, while the other is to define some data
829 structures that allow SquirrelMail to build your user inputs and save
830 your data automatically.
832 Building your own page is wide open, and for ideas, you should look at
833 any of the plugins that currently have their own preferences pages. If
834 you do this, make sure to read step number 4 below for information on
835 saving settings. In order to maintain security, consistant look and
836 feel, internationalization support and overall integrity, there are just
837 a few things you should always do in this case: define the SM_PATH
838 constant, include the file include/validate.php (see the section about
839 including other files above) and make a call to place the standard page
840 heading at the top of your preferences page. The top of your PHP file
841 might look something like this:
843 define('SM_PATH', '../../');
844 include_once(SM_PATH . 'include/validate.php');
846 displayPageHeader($color, 'None');
848 From here you are on your own, although you are encouraged to do things
849 such as use the $color array to keep your HTML correctly themed, etc.
851 If you want SquirrelMail to build your preferences page for you,
852 creating input forms and automatically saving users' settings, then
853 you should change the 'url' attribute in the options block you created
854 in step number 2 above to read as follows:
856 'url' => SM_PATH . 'src/options.php?optpage=plugin_demo',
858 Now, you will need to use the "optpage_set_loadinfo" hook to tell
859 SquirrelMail about your new preferences page. In setup.php in the
860 squirrelmail_plugin_init_demo() function:
862 $squirrelmail_plugin_hooks['optpage_set_loadinfo']['demo']
863 = 'demo_optpage_loadinfo';
865 Assuming the function demo_optpage_loadinfo() calls another function
866 elsewhere called demo_optpage_loadinfo_do(), that function needs to
867 define values for four variables (make sure you test to see that it
868 is your plugin that is being called by checking the GET variable you
869 added to the url just above):
871 global $optpage, $optpage_name, $optpage_file,
872 $optpage_loader, $optpage_loadhook;
873 if ($optpage == 'plugin_demo')
875 $optpage_name = "Favorite Color Preferences";
876 $optpage_file = SM_PATH . 'plugins/demo/options.php';
877 $optpage_loader = 'load_optpage_data_demo';
878 $optpage_loadhook = 'optpage_loadhook_demo';
881 Now you are ready to build all of your options. In the file you
882 indicated for the variable $optpage_file above, you'll need to create
883 a function named the same as the value you used for $optpage_loader
884 above. In this example, the file plugins/demo/options.php should
885 have at least this function in it:
887 function load_optpage_data_demo()
889 $optpage_data = array();
890 $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options';
891 $optionValues = array();
892 $optionValues[] = array(
893 'name' => 'plugin_demo_favorite_color',
894 'caption' => 'Please Choose Your Favorite Color',
895 'type' => SMOPT_TYPE_STRLIST,
896 'refresh' => SMOPT_REFRESH_ALL,
897 'posvals' => array(0 => 'red',
901 'save' => 'save_plugin_demo_favorite_color'
903 $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues;
904 return $optpage_data;
907 For a detailed description of how you build these options, please read
908 step number 2 for the second method of adding options to an existing
909 preferences page above. Notice that the only difference here is in the
910 very first and last lines of this function where you are actually
911 creating and returning the options array instead of just adding onto it.
913 That's all there is to it - SquirrelMail will create a preferences page
914 titled as you indicated for $optpage_name above, and other plugins
915 can even add extra options to this new preferences page. To do so,
916 they should use the hook name you specified for $optpage_loadhook above
917 and use the second method for adding option settings to existing
918 preferences pages described above.
920 4. Saving your options settings: if you used the second method in step
921 number 3 above, your settings will be saved automatically (or you can
922 define special functions to save special settings such as the
923 save_plugin_demo_favorite_color() function in the example described
924 above) and there is probably no need to follow this step. If you
925 created your own preferences page from scratch, you'll need to follow
926 this step. First, you need to register your plugin against the
927 "options_save" hook. In setup.php in the squirrelmail_plugin_init_demo()
930 $squirrelmail_plugin_hooks['options_save']['demo']
931 = 'demo_save_options';
933 Assuming the function demo_save_options() calls another function
934 elsewhere called demo_save_options_do(), that function needs to grab
935 all of your POST and/or GET settings values and save them in the user's
936 preferences (for more about preferences, see that section below). Since
937 this is a generic hook called for all custom preferences pages, you
938 should always set "optpage" as a POST or GET variable with a string that
939 uniquely identifies your plugin:
941 <input type="hidden" name="optpage" value="plugin_demo" />
943 Now in your demo_save_options_do() function, do something like this:
945 global $username, $data_dir, $optpage, $favorite_color;
946 if ($optpage == 'plugin_demo')
948 sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
949 setPref($data_dir, $username, 'favorite_color', $favorite_color);
952 Note that $favorite_color may not need to be globalized, although
953 experience has shown that some versions of PHP don't behave as expected
954 unless you do so. Even when you use SquirrelMail's built-in preferences
955 page generation functionality, you may still use this hook, although
956 there should be no need to do so. If you need to do some complex
957 validation routines, note that it might be better to do so in the file
958 you specified as the "$optpage_file" (in our example, that was the
959 plugins/demo/options.php file), since at this point, you can still
960 redisplay your preferences page. You could put code similar to this
961 in the plugins/demp/options.php file (note that there is no function;
962 this code needs to be executed at include time):
965 if ($optmode == 'submit')
967 // do something here such as validation, etc
968 if (you want to redisplay your preferences page)
976 Saving and retrieving user preferences is very easy in SquirrelMail.
977 SquirrelMail supports preference storage in files or in a database
978 backend, however, the code you need to write to manipulate preferences
979 is the same in both cases.
983 Setting preferences is done for you if you use the built-in facilities
984 for automatic options construction and presentation (see above). If
985 you need to manually set preferences, however, all you need to do is:
987 global $data_dir, $username;
988 setPref($data_dir, $username, 'pref_name', $pref_value);
990 Where "pref_name" is the key under which the value will be stored
991 and "pref_value" is a variable that should contain the actual
992 preference value to be stored.
996 There are two approaches to retrieving plugin (or any other) preferences.
997 You can grab individual preferences one at a time or you can add your
998 plugin's preferences to the routine that loads up user preferences at
999 the beginning of each page request. If you do the latter, making sure
1000 to place your preference variables into the global scope, they will be
1001 immediately available in all other plugin code. To retrieve a single
1002 preference value at any time, do this:
1004 global $data_dir, $username;
1005 $pref_value = getPref($data_dir, $username, 'pref_name', 'default value');
1007 Where "pref_name" is the preference you are retrieving, "default_value"
1008 is what will be returned if the preference is not found for this user,
1009 and, of course, "pref_value" is the variable that will get the actual
1012 To have all your preferences loaded at once when each page request is
1013 made, you'll need to register a function against the "loading_prefs" hook.
1014 For our "demo" plugin, in setup.php in the squirrelmail_plugin_init_demo()
1017 $squirrelmail_plugin_hooks['loading_prefs']['demo']
1018 = 'demo_load_prefs';
1020 Assuming the function demo_load_prefs() calls another function
1021 elsewhere called demo_load_prefs_do(), that function just needs to
1022 pull out any all all preferences you'll be needing elsewhere:
1024 global $data_dir, $username, $pref_value;
1025 $pref_value = getPref($data_dir, $username, 'pref_name', 'default value');
1027 Remember to globalize each preference, or this code is useless.
1030 Internationalization
1031 --------------------
1033 Although this document may only be available in English, we sure hope that you
1034 are thinking about making your plugin useful to the thousands of non-English
1035 speaking SquirrelMail users out there! It is almost rude not to do so, and
1036 it isn't much trouble, either. This document will only describe how you can
1037 accomplish the internationalization of a plugin. For more general information
1038 about PHP and SquirrelMail translation facilities, see:
1040 http://www.squirrelmail.org/wiki/wiki.php?LanguageTranslation
1042 The unofficial way to internationalize a plugin is to put all plugin output
1043 into the proper format but to rely on the SquirrelMail translation facilities
1044 for all the rest. If the plugin were really to get translated, you'd need
1045 to make sure that all output strings for your plugin are either added to or
1046 already exist in the main SquirrelMail locale files.
1048 The better way to make sure your plugin is translated is to create your own
1049 locale files and what is called a "gettext domain" (see the link above for
1052 There are three basic steps to getting your plugins internationalized: put
1053 all output into the proper format, switch gettext domains and create locale
1056 1. Putting plugin output into the correct format is quite easy. The hard
1057 part is making sure you catch every last echo statement. You need to
1058 echo text like this:
1062 So, even in the HTML segments of your plugin files, you need to do this:
1064 <input type="submit" value="<?php echo _("Submit"); ?>" />
1066 You can put any text you want inside of the quotes (you MUST use double
1067 quotes!), including HTML tags, etc. What you should think carefully
1068 about is that some languages may use different word ordering, so this
1069 might be problematic:
1071 echo _("I want to eat a ") . $fruitName . _(" before noon");
1073 Because some languages (Japanese, for instance) would need to translate
1074 such a sentence to "Before noon " . $fruitName . " I want to eat", but
1075 with the format above, they are stuck having to translate each piece
1076 separately. You might want to reword your original sentence:
1078 echo _("This is what I want to eat before noon: ") . $fruitName;
1081 Support for single quotes in gettext was added somewhere along gettext
1082 0.11.x (release dates 2002-01-31--08-06). This means that strings could
1087 However, gettext 0.10.40 is currently the oldest version available at the
1088 GNU site. It's still used in some Linux and BSD distributions/versions.
1089 Since it's still in common use and it doesn't support single quoted
1090 strings, double quoted strings are the preferred way when writing a
1093 2. By default, the SquirrelMail gettext domain is always in use. That
1094 means that any text in the format described above will be translated
1095 using the locale files found in the main SquirrelMail locale directory.
1096 Unless your plugin produces no output or only output that is in fact
1097 translated under the default SquirrelMail domain, you need to create
1098 your own gettext domain. The PHP for doing so is very simple. At
1099 the top of any file that produces any output, place the following code
1100 (again, using "demo" as the plugin name):
1102 bindtextdomain('demo', SM_PATH . 'plugins/demo/locale');
1105 Now all output will be translated using your own custom locale files.
1106 Please be sure to switch back to the SquirrelMail domain at the end
1107 of the file, or many of the other SquirrelMail files may misbehave:
1109 bindtextdomain('squirrelmail', SM_PATH . 'locale');
1110 textdomain('squirrelmail');
1112 Note that if, in the middle of your plugin file, you use any
1113 SquirrelMail functions that send output to the browser, you'll need
1114 to temporarily switch back to the SquirrelMail domain:
1116 bindtextdomain('squirrelmail', SM_PATH . 'locale');
1117 textdomain('squirrelmail');
1118 displayPageHeader($color, 'None');
1119 bindtextdomain('demo', SM_PATH . 'plugins/demo/locale');
1122 Note that technically speaking, you only need to have one bindtextdomain
1123 call per file, you should always use it before every textdomain call,
1124 since PHP installations without gettext compiled into them will not
1125 function properly if you do not.
1127 3. Finally, you just need to create your own locale. You should create
1128 a directory structure like this in the plugin directory:
1142 Create a directories such as de_DE for each language (de_DE is German,
1143 ja_JP is Japanese, etc. - check the SquirrelMail locale directory for
1144 a fairly comprehensive listing). Inside of each LC_MESSAGES directory
1145 you should place two files, one with your translations in it, called
1146 <plugin name>.po (in this case, "demo.po"), and one that is a compiled
1147 version of the ".po" file, called <plugin name>.mo (in this case,
1148 "demo.mo"). On most linux systems, there is a tool you can use to pull
1149 out most of the strings that you need to have translated from your PHP
1150 files into a sample .po file:
1152 xgettext --keyword=_ -d <plugin name> -s -C *.php
1154 --keyword option tells xgettext what your strings are enclosed in
1155 -d is the domain of your plugin which should be the plugin's name
1156 -s tells xgettext to sort the results and remove duplicate strings
1157 -C means you are translating a file with C/C++ type syntax (ie. PHP)
1158 *.php is all the files you want translations for
1160 Note, however, that this will not always pick up all strings, so you
1161 should double-check manually. Of course, it's easiest if you just keep
1162 track of all your strings as you are coding your plugin. Your .po file
1163 will now look something like:
1165 # SOME DESCRIPTIVE TITLE.
1166 # Copyright (C) YEAR Free Software Foundation, Inc.
1167 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
1172 "Project-Id-Version: PACKAGE VERSION\n"
1173 "POT-Creation-Date: 2003-06-18 11:22-0600\n"
1174 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
1175 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
1176 "Language-Team: LANGUAGE <LL@li.org>\n"
1177 "MIME-Version: 1.0\n"
1178 "Content-Type: text/plain; charset=CHARSET\n"
1179 "Content-Transfer-Encoding: ENCODING\n"
1186 msgid "Favorite Color"
1189 You should change the header to look something more like:
1191 # Copyright (c) 1999-2005 The SquirrelMail Project Team
1192 # Roland Bauerschmidt <rb@debian.org>, 1999.
1196 "Project-Id-Version: plugin-name version\n"
1197 "POT-Creation-Date: 2003-01-21 19:21+0100\n"
1198 "PO-Revision-Date: 2003-01-21 21:01+0100\n"
1199 "Last-Translator: Juergen Edner <juergen.edner@epost.de>\n"
1200 "Language-Team: German <squirrelmail-i18n@lists.sourceforge.net>\n"
1201 "MIME-Version: 1.0\n"
1202 "Content-Type: text/plain; charset=ISO-8859-1\n"
1203 "Content-Transfer-Encoding: 8bit\n"
1205 The most important thing to change here is the charset on the next to
1206 last line. You'll want to keep a master copy of the .po file and make
1207 a copy for each language you have a translation for. You'll need to
1208 translate each string in the .po file:
1213 After you're done translating, you can create the .mo file very simply
1214 by running the following command (available on most linux systems):
1216 msgfmt -o <plugin name>.mo <plugin name>.po
1218 In the case of the "demo" plugin:
1220 msgfmt -o demo.mo demo.po
1222 Please be sure that the .po and .mo files both are named exactly the
1223 same as the domain you bound in step 2 above and everything else works
1224 automatically. In SquirrelMail, go to Options -> Display Preferences
1225 and change your Language setting to see the translations in action!
1229 Documenting the Code (Optional)
1230 -------------------------------
1232 If you wish, you can use phpdoc (Javadoc-style) comments, when documenting your
1235 If you follow the standards that are followed between SquirrelMail core &
1236 plugin developers, the resulted documentation can be included with the rest of
1237 the SquirrelMail code & API documentation. Specifically, in the page-level
1238 docblock, declare the package to be 'plugins', and the subpackage to be the
1239 name of your plugin. For instance:
1244 * Copyright (c) 2005 My Name <my-email-address>
1245 * Licensed under the GNU GPL. For full terms see the file COPYING.
1251 The rest is up to you. Try to follow some common sense and document what is
1252 really needed. Documenting the code properly can be a big help not only to
1253 yourself, but to those who will take a look at your code, fix the bugs and even
1254 improve it, in the true open-source spirit that SquirrelMail was built upon.
1256 For more information about phpdocumentor and how to write proper-tagged
1257 comments, you are directed at:
1259 http://phpdocu.sourceforge.net/
1263 PLUGIN STANDARDS AND REQUIREMENTS
1264 =================================
1266 The SquirrelMail project has some important goals, such as avoiding the
1267 use of JavaScript, avoiding non-standard HTML tags, keeping file sizes
1268 small and providing the fastest webmail client on the Internet. As such,
1269 we'd like it if plugin authors coded with the same goals in mind that the
1270 core developers do. Common sense is always a good tool to have in your
1271 programming repertoire, but below is an outline of some standards that we
1272 ask you as a plugin developer to meet. Depending upon how far you bend
1273 these rules, we may not want to post your plugin on the SquirrelMail
1274 website... and of course, no one really wants your efforts to go to waste
1275 and for the SquirrelMail community to miss out on a potentially useful
1276 plugin, so please try to follow these guidelines as closely as possible.
1282 In order for SquirrelMail to remain fast and lean, we are now asking
1283 that all plugin authors remove all unnecessary functionality from setup.php
1284 and refactor it into another file. There are a few ways to accomplish
1285 this, none of which are difficult. At a minimum, you'll want to have the
1286 squirrelmail_plugin_init_<plugin name>() function in setup.php, and naturally,
1287 you'll need functions that are merely stubs for each hook that you are using.
1288 One (but not the only) way to do it is:
1290 function squirrelmail_plugin_init_demo()
1292 global $squirrelmail_plugin_hooks;
1293 $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header';
1295 function plugin_demo_header()
1297 include_once(SM_PATH . 'plugins/demo/functions.php');
1298 plugin_demo_header_do();
1302 Internationalization
1303 --------------------
1305 Q: What is more disappointing to users in France who would make good
1306 use of your plugin than learning that it is written entirely in English?
1307 A: Learning that they cannot send you a French translation file for your
1310 There are thousands of users out there whose native tongue is not English,
1311 and when you develop your plugin without going through the three simple steps
1312 needed to internationalize it, you are effectively writing them all off.
1313 PLEASE consider internationalizing your plugin!
1316 Developing with E_ALL
1317 ---------------------
1319 When you are developing your plugin, you should always have error reporting
1320 turned all the way up. You can do this by changing two settings in your
1321 php.ini and restarting your web server:
1324 error_reporting = E_ALL
1326 This way, you'll be sure to see all Notices, Warnings and Errors that your
1327 code generates (it's OK, really, it happens to the best of us... except me!).
1328 Please make sure to fix them all before you release the plugin.
1331 Compatibility with register_globals=Off
1332 ---------------------------------------
1334 Most sensible systems administrators now run their PHP systems with the
1335 setting "register_globals" as OFF. This is a prudent security setting,
1336 and as the SquirrelMail core code has long since been upgraded to work
1337 in such an environment, we are now requiring that all plugins do the same.
1338 Compatibility with this setting amounts to little more than explicitly
1339 gathering any and all variables you sent from a <form> tag as GET or POST
1340 values instead of just assuming that they will be placed in the global
1341 scope automatically. There is nothing more to do than this:
1343 global $favorite_color;
1344 sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
1347 Security considerations
1348 -----------------------
1350 All plugin authors should consider the security implications of their
1351 plugin. Of course, if you call external programs you have to use great
1352 care, but the following issues are important to nearly every plugin.
1354 - Escape any untrusted data before you output it. This is to prevent
1355 cross site scripting attacks. It means that you have to htmlspecialchars()
1356 every variable that comes in through the URL, a mail message or other
1357 external factors, before outputting it.
1359 - Make sure that your plugin doesn't perform its function when it's not
1360 enabled. If you just call hooks, your hooks won't be called when the
1361 plugin is disabled, but if you also supply extra .php files, you should
1362 check if they perform any function if accessed directly. If they do, you
1363 should check at the start of that file whether the plugin is enabled in the
1364 config, and if not, exit the script. Example:
1366 if ( !in_array('mypluginname', $plugins) ) {
1367 die("Plugin not enabled in SquirrelMail configuration.");
1370 If you have any questions about this or are unsure, please contact the
1371 mailinglist or IRC channel, because security is very important for a
1372 widely used application like SquirrelMail!
1378 It may seem innocuous, but if you have any blank lines either before the
1379 first <?php tag or after the last ?> tag in any of your plugin files, you
1380 you will break SquirrelMail in ways that may seem entirely unrelated. For
1381 instance, this will often cause a line feed character to be included with
1382 email attachments when they are viewed or downloaded, rendering them useless!
1388 When including files, please make sure to use the include_once() function
1389 and NOT include(), require(), or require_once(), since these all are much
1390 less efficient than include_once() and can have a cumulative effect on
1391 SquirrelMail performance.
1397 In order for systems administrators to keep better track of your plugin and
1398 get upgrades more efficiently, you are requested to make version information
1399 available to SquirrelMail in a format that it understands. There are two
1400 ways to do this. Presently, we are asking that you do both, since we are
1401 still in a transition period between the two. This is painless, so please
1402 be sure to include it:
1404 1. Create a file called "version" in the plugin directory. That file
1405 should have only two lines: the first line should have the name of
1406 the plugin as named on the SquirrelMail web site (this is often a
1407 prettified version of the plugin directory name), the second line
1408 must have the version and nothing more. So for our "demo" plugin,
1409 whose name on the web site might be something like "Demo Favorite
1410 Colors", the file plugins/demo/version should have these two lines:
1412 Demo Favorite Colors
1415 2. In setup.php, you should have a function called <plugin name>_version().
1416 That function should return the version of your plugin. For the "demo"
1417 plugin, that should look like this:
1419 function demo_version()
1428 It is common to need a configuration file that holds some variables that
1429 are set up at install time. For ease of installation and maintenance, you
1430 should place all behavioral settings in a config file, isolated from the
1431 rest of your plugin code. A typical file name to use is "config.php". If
1432 you are using such a file, you should NOT include a file called "config.php"
1433 in your plugin distribution, but instead a copy of that file called
1434 "config.php.sample". This helps systems administrators avoid overwriting
1435 the "config.php" files and losing all of their setup information when they
1436 upgrade your plugin.
1442 In the past, there have been some rather serious issues with PHP sessions
1443 and SquirrelMail, and certain people have worked long and hard to ensure
1444 that these problems no longer occur in an extremely wide variety of OS/PHP/
1445 web server environments. Thus, if you need to place any values into the
1446 user's session, there are some built-in SquirrelMail functions that you are
1447 strongly encouraged to make use of. Using them also makes your job easier.
1449 1. To place a variable into the session:
1451 global $favorite_color;
1452 $favoriteColor = 'green';
1453 sqsession_register($favorite_color, 'favorite_color');
1455 Strictly speaking, globalizing the variable shouldn't be necessary,
1456 but certain versions of PHP seem to behave more predictably if you do.
1458 2. To retrieve a variable from the session:
1460 global $favorite_color;
1461 sqgetGlobalVar('favorite_color', $favorite_color, SQ_SESSION);
1463 3. You can also check for the presence of a variable in the session:
1465 if (sqsession_is_registered('favorite_color'))
1466 // do something important
1468 4. To remove a variable from the session:
1470 global $favorite_color;
1471 sqsession_unregister('favorite_color');
1473 Strictly speaking, globalizing the variable shouldn't be necessary,
1474 but certain versions of PHP seem to behave more predictably if you do.
1480 You are also encouraged to use SquirrelMail's built-in facilities to
1481 retrieve variables from POST and GET submissions. This is also much
1482 easier on you and makes sure that all PHP installations are accounted
1483 for (such as those that don't make the $_POST array automatically
1486 global $favorite_color;
1487 sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
1490 Files In Plugin Directory
1491 -------------------------
1493 There are a few files that you should make sure to include when you build
1494 your final plugin distribution:
1496 1. A copy of the file index.php from the main plugins directory. When
1497 working in your plugin directory, just copy it in like this:
1501 This will redirect anyone who tries to browse to your plugin directory
1502 to somewhere more appropriate. If you create other directories under
1503 your plugin directory, you may copy the file there as well to be extra
1504 safe. If you are storing sensitive configuration files or other data
1505 in such a directory, you could even include a .htaccess file with the
1506 contents "Deny From All" that will disallow access to that directory
1507 entirely (when the target system is running the Apache web server).
1508 Keep in mind that not all web servers will honor an .htaccess file, so
1509 don't depend on it for security. Make sure not to put such a file in
1510 your main plugin directory!
1512 2. A file that describes your plugin and offers detailed instructions for
1513 configuration or help with troubleshooting, etc. This file is usually
1514 entitled "README". Some useful sections to include might be:
1516 Plugin Name and Author
1519 Detailed Plugin Description
1520 How-to for Plugin Configuration
1522 Future Ideas/Enhancements/To Do List
1524 3. A file that explains how to install your plugin. This file is typically
1525 called "INSTALL". If you do not require any special installation
1526 actions, you can probably copy one from another plugin or use this as
1529 Installing the Demo Plugin
1530 ==========================
1532 1) Start with untaring the file into the plugins directory.
1533 Here is a example for the 1.0 version of the Demo plugin.
1536 $ tar -zxvf demo-1.0-1.4.0.tar.gz
1538 2) Change into the demo directory, copy config.php.sample
1539 to config.php and edit config.php, making adjustments as
1540 you deem necessary. For more detailed explanations about
1541 each of these parameters, consult the README file.
1544 $ cp config.php.sample config.php
1548 3) Then go to your config directory and run conf.pl. Choose
1549 option 8 and move the plugin from the "Available Plugins"
1550 category to the "Installed Plugins" category. Save and exit.
1556 Upgrading the Demo Plugin
1557 =========================
1559 1) Start with untaring the file into the plugins directory.
1560 Here is a example for the 3.1 version of the demo plugin.
1563 $ tar -zxvf demo-3.1-1.4.0.tar.gz
1566 2) Change into the demo directory, check your config.php
1567 file against the new version, to see if there are any new
1568 settings that you must add to your config.php file.
1570 $ diff -Nau config.php config.php.sample
1572 Or simply replace your config.php file with the provided sample
1573 and reconfigure the plugin from scratch (see step 2 under the
1574 installation procedure above).
1577 COMPATIBILITY WITH OLDER VERSIONS OF SQUIRRELMAIL
1578 =================================================
1580 Whenever new versions of SquirrelMail are released, there is always a
1581 considerable lag time before it is widely adopted. During that transitional
1582 time, especially when the new SquirrelMail version contains any architectural
1583 and/or functional changes, plugin developers are put in a unique and very
1584 difficult position. That is, there will be people running both the old and
1585 new versions of SquirrelMail who want to use your plugin, and you will
1586 probably want to accomodate them both.
1588 The easiest way to keep both sides happy is to keep two different versions
1589 of your pluign up to date, one that runs under the older SquirrelMail, and
1590 one that requires the newest SquirrelMail. This is inconvenient, however,
1591 especially if you are continuing to develop the plugin. Depending on the
1592 changes the SquirrelMail has implemented in the new version, you may be able
1593 to include code that can auto-sense SquirrelMail version and make adjustments
1594 on the fly. There is a function available to you for determining the
1595 SquirrelMail version called check_sm_version() and it can be used as such:
1597 check_sm_version(1, 4, 0)
1599 This will return TRUE if the SquirrelMail being used is at least 1.4.0, and
1602 As this document is written, we are in a transition period between versions
1603 1.2.11 and 1.4.0. There is a plugin called "Compatibilty" that is intended
1604 for use by plugin authors so they can develop one version of their plugin
1605 and seamlessly support both 1.2.x and 1.4.x SquirrelMail installations. For
1606 more information about how to use the "Compatibility" plugin, download it and
1607 read its README file or see:
1609 http://www.squirrelmail.org/wiki/wiki.php?PluginUpgrading
1612 REQUESTING NEW HOOKS
1613 ====================
1615 It's impossible to foresee all of the places where hooks might be useful
1616 (it's also impossible to put in hooks everywhere!), so you might need to
1617 negotiate the insertion of a new hook to make your plugin work. In order
1618 to do so, you should post such a request to the squirrelmail-devel mailing
1622 HOW TO RELEASE YOUR PLUGIN
1623 ==========================
1625 As long as you've consulted the list of plugin standards and done your
1626 best to follow them, there's little standing in the way of great fame as an
1627 official SquirrelMail plugin developer.
1629 1. Make a distribution file. There is a convenient Perl script in
1630 the plugins directory that will help you do this:
1632 make_archive.pl -v demo 1.0 1.4.0
1634 -v is optional and indicates that the script should run in verbose mode
1635 demo is the name of your plugin
1636 1.0 is the version of your plugin
1637 1.4.0 is the version of SquirrelMail that is required to run your plugin
1639 You can also create the distribution file manually in most *nix
1640 environments by running this command from the plugins directory (NOT
1641 your plugin directory):
1643 $ tar czvf demo-1.0-1.4.0.tar.gz demo
1645 Where "demo" is the name of your plugin, "1.0" is the version of
1646 your plugin, and "1.4.0" is the version of SquirrelMail required
1649 2. Consult the SquirrelMail web site for contact information for the
1650 Plugins Team Leaders, to whom you should make your request. If they
1651 do not respond, you should feel free to ask for help contacting them
1652 on the squirrelmail-plugins mailing list.
1654 http://www.squirrelmail.org/wiki/wiki.php?SquirrelMailLeadership