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