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