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