doc/Development/plugin.txt

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