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