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