Added 'trailing text' for options that SM builds, which is placed after a text input...
[squirrelmail.git] / doc / plugin.txt
CommitLineData
99098885 1$Id$
2
9cd2ae7d 3In addition to this document, please check out the SquirrelMail
4development FAQ for more information. Also, help writing plugins
5is easily obtained by posting to the squirrelmail-plugins mailing
b2978b37 6list. (See details about mailing lists on the website)
99098885 7
8FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
9cd2ae7d 9Plugin Development ->
10 http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
99098885 11
12
1aaef171 13A FEW NOTES ON THE PLUGIN ARCHITECTURE
14======================================
15
9cd2ae7d 16The plugin architecture of SquirrelMail is designed to make it possible
17to add new features without having to patch SquirrelMail itself.
18Functionality like password changing, displaying ads and calendars should
19be possible to add as plugins.
1aaef171 20
21
9cd2ae7d 22The Idea
1aaef171 23--------
24
25The idea is to be able to run random code at given places in the
26SquirrelMail code. This random code should then be able to do whatever
27needed to enhance the functionality of SquirrelMail. The places where
28code can be executed are called "hooks".
29
30There are some limitations in what these hooks can do. It is difficult
31to use them to change the layout and to change functionality that
32already is in SquirrelMail.
33
34Some way for the plugins to interact with the help subsystem and
35translations will be provided.
36
37
9cd2ae7d 38The Implementation
1aaef171 39------------------
40
9cd2ae7d 41The plugin jumping off point in the main SquirrelMail code is in the
42file functions/plugin.php. In places where hooks are made available,
43they are executed by calling the function do_hook('hookname'). The
44do_hook function then traverses the array
45$squirrelmail_plugin_hooks['hookname'] and executes all the functions
46that are named in that array. Those functions are placed there when
47plugins register themselves with SquirrelMail as discussed below. A
48plugin may add its own internal functions to this array under any
49hook name provided by the SquirrelMail developers.
1aaef171 50
51A plugin must reside in a subdirectory in the plugins/ directory. The
9cd2ae7d 52name 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.)
1aaef171 54
55To start using a plugin, its name must be added to the $plugins array
56in config.php like this:
57
9cd2ae7d 58 $plugins[0] = 'plugin_name';
1aaef171 59
9cd2ae7d 60When a plugin is registered, the file plugins/plugin_name/setup.php is
61included and the function squirrelmail_plugin_init_plugin_name() is
62called with no parameters. That function is where the plugin may
63register itself against any hooks it wishes to take advantage of.
1aaef171 64
65
9cd2ae7d 66WRITING PLUGINS
67===============
68
69All plugins must contain a file called setup.php and must include a
70function called squirrelmail_plugin_init_plugin_name() therein. Since
71including numerous plugins can slow SquirrelMail performance
72considerably, the setup.php file should contain little else. Any
73functions that are registered against plugin hooks should do little
74more than call another function in a different file.
75
76Any other files used by the plugin should also be placed in the
77plugin directory (or subdirectory thereof) and should contain the
78bulk of the plugin logic.
1aaef171 79
9cd2ae7d 80The function squirrelmail_plugin_init_plugin_name() is called to
81initalize a plugin. This function could look something like this (if
82the plugin was named "demo" and resided in the directory plugins/demo/):
1aaef171 83
9cd2ae7d 84function squirrelmail_plugin_init_demo ()
85{
86 global $squirrelmail_plugin_hooks;
1aaef171 87
9cd2ae7d 88 $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header';
89 $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline';
90}
91
92Please note that as of SquirrelMail 1.5.0, this function will no longer
93be called at run time and will instead be called only once at configure-
94time. Thus, the inclusion of any dynamic code (anything except hook
95registration) here is strongly discouraged.
1aaef171 96
9cd2ae7d 97In this example, the "demo" plugin should also have two other functions
98in its setup.php file called plugin_demo_header() and plugin_demo_menuline().
99The first of these might look something like this:
100
101function plugin_demo_header()
102{
103 include_once(SM_PATH . 'plugins/demo/functions.php');
104 plugin_demo_header_do();
1aaef171 105}
106
9cd2ae7d 107The function called plugin_demo_header_do() would be in the file called
108functions.php in the demo plugin directory and would contain the plugin's
109core logic for the "generic_header" hook.
110
111
112Including Other Files
113---------------------
114
115A plugin may need to reference functionality provided in other
116files, and therefore need to include those files. Most of the
117core SquirrelMail functions are already available to your plugin
118unless it has any files that are requested directly by the client
119browser (custom options page, etc.). In this case, you'll need
120to make sure you include the files you need (see below).
121
122Note that as of SquirrelMail 1.4.0, all files are accessed using a
123constant called SM_PATH that always contains the relative path to
124the main SquirrelMail directory. This constant is always available
125for you to use when including other files from the SquirrelMail core,
126your own plugin, or other plugins, should the need arise. If any of
127your plugin files are requested directly from the client browser,
128you will need to define this constant before you do anything else:
129
130 define('SM_PATH', '../../');
131
132Files are included like this:
133
134 include_once(SM_PATH . 'include/validate.php');
135
136When including files, please make sure to use the include_once() function
137and NOT include(), require(), or require_once(), since these all are much
138less efficient than include_once() and can have a cumulative effect on
139SquirrelMail performance.
140
141The files that you may need to include in a plugin will vary greatly
142depending upon what the plugin is designed to do. For files that are
143requested directly by the client browser, we strongly recommend that
144you include the file include/validate.php, since it will set up the
145SquirrelMail environment automatically. It will ensure the the user
146has been authenticated and is currently logged in, load all user
147preferences, include internationalization support, call stripslashes()
148on all incoming data (if magic_quotes_gpc is on), and initialize and
149include all other basic SquirrelMail resources and functions. You may
150see other plugins that directly include other SquirrelMail files, but
151that is no longer necessary and is a hold-over from older SquirrelMail
152versions.
6b638171 153
154
9cd2ae7d 155Hook Types: Parameters and Return Values
156-----------------------------------------
157
f4fd89e0 158Hooks, when executed, are called with differing parameters and may or may
159not take return values, all depending on the type of hook being called and
160the context in which it is being used. On the source side (where the hook
161call originates), all hooks have at least one parameter, which is the
162name 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
efea59ed 206 boolean_hook_function
207 ---------------------
f4fd89e0 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).
a3a95e4a 222
f4fd89e0 223See below for further discussion of special hook types and the values
a3a95e4a 224
225
9cd2ae7d 226List of Hooks
6b638171 227-------------
ef3c69f0 228
9cd2ae7d 229This is a list of all hooks currently available in SquirrelMail, ordered
230by file. Note that this list is accurate as of June 17, 2003 (should be
231close to what is contained in release 1.4.1, plus or minus a hook or two),
232but may be out of date soon thereafter. You never know. ;-)
6b638171 233
9cd2ae7d 234 Hook Name Found In Called With(#)
235 --------- -------- --------------
df788686 236 abook_init functions/addressbook.php do_hook
237 abook_add_class functions/addressbook.php do_hook
9cd2ae7d 238 loading_constants functions/constants.php do_hook
54067ccd 239 logout_error functions/display_messages.php do_hook
240 error_box functions/display_messages.php concat_hook
9cd2ae7d 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
9cd2ae7d 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
c5aaf57f 250 mailbox_display_buttons functions/mailbox_display.php do_hook
9cd2ae7d 251 message_body functions/mime.php do_hook
252 ^ attachment $type0/$type1 functions/mime.php do_hook
9ad17edb 253 attachments_bottom functions/mime.php hook_func
c4115032 254 decode_body functions/mime.php hook_func
9cd2ae7d 255 generic_header functions/page_header.php do_hook
256 menuline functions/page_header.php do_hook
c5aaf57f 257 internal_link functions/page_header.php hook_func
9cd2ae7d 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
7022cc97 269 left_main_after_each_folder src/left_main.php concat_hook
9cd2ae7d 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
c5aaf57f 277 move_messages_button_action src/move_messages.php concat_hook
9cd2ae7d 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
d44e63d5 308 read_body_menu_top src/read_body.php hook_func
9cd2ae7d 309 read_body_menu_bottom src/read_body.php do_hook
310 read_body_header_right src/read_body.php do_hook
9cd2ae7d 311 read_body_top src/read_body.php do_hook
312 read_body_bottom src/read_body.php do_hook
9cd2ae7d 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
d44e63d5 323 webmail_bottom src/webmail.php concat_hook
9cd2ae7d 324 logout_above_text src/signout.php concat_hook
8ed1cfc6 325 O info_bottom plugins/info/options.php do_hook
9cd2ae7d 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)
8ed1cfc6 332O = optional hook used by plugin
6b638171 333
6b638171 334
9cd2ae7d 335(#) Called With
336---------------
337Each 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()
a3a95e4a 341
342
0f101579 343(&) Identity Hooks
344------------------
9cd2ae7d 345This set of hooks is passed special information in the array of arguments:
0f101579 346
347options_identities_process
9cd2ae7d 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.
0f101579 361
362options_identities_renumber
9cd2ae7d 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)
0f101579 373
374options_identities_table
9cd2ae7d 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:
cb3425db 380 <tr bgcolor="<?php echo $info[1]; ?>">
9cd2ae7d 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 }
0f101579 392
393options_identities_buttons
9cd2ae7d 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 }
0f101579 409
410
a3a95e4a 411(^) Attachment Hooks
412--------------------
413When a message has attachments, this hook is called with the MIME types. For
414instance, a .zip file hook is "attachment application/x-zip". The hook should
415probably show a link to do a specific action, such as "Verify" or "View" for a
9cd2ae7d 416.zip file. Thus, to register your plugin for .zip attachments, you'd do this
417in setup.php (assuming your plugin is called "demo"):
418
419 $squirrelmail_plugin_hooks['attachment application/x-zip']['demo']
420 = 'demo_handle_zip_attachment';
a3a95e4a 421
422This 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')
9cd2ae7d 425 [1] = Array of links of actions (see below) (alterable)
a3a95e4a 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)
9cd2ae7d 430 [6] = Default URL to go to when filename is clicked on (alterable)
ef30bf50 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)
a3a95e4a 434
435To set up links for actions, you assign them like this:
436
9cd2ae7d 437 $Args[1]['<plugin_name>']['href'] = 'URL to link to';
438 $Args[1]['<plugin_name>']['text'] = 'What to display';
441f2d33 439
ae2f65a9 440It's also possible to specify a hook as "attachment type0/*",
441for example "attachment text/*". This hook will be executed whenever there's
442no more specific rule available for that type.
443
9cd2ae7d 444Putting all this together, the demo_handle_zip_attachment() function should
445look like this (note the argument being passed):
57945c53 446
9cd2ae7d 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 }
57945c53 452
9cd2ae7d 453And the demo_handle_zip_attachment_do() function in the
454plugins/demo/functions.php file would typically (but not necessarily)
455display 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
465The file plugins/demo/zip_handler.php can now do whatever it needs with the
466attachment (note that this will hand information about how to retrieve the
467source message from the IMAP server as GET varibles).
468
469
470(*) Options
471-----------
472Before you start adding user preferences to your plugin, please take a moment
473to think about it: in some cases, more options may not be a good thing.
474Having too many options can be confusing. Thinking from the user's
475perspective, will the proposed options actually be used? Will users
476understand what these options are for?
477
478There are two ways to add options for your plugin. When you only have a few
479options that don't merit an entirely new preferences page, you can incorporate
480them into an existing section of SquirrelMail preferences (Personal
481Information, Display Preferences, Message Highlighting, Folder Preferences or
482Index Order). Or, if you have an extensive number of settings or for some
483reason need a separate page for the user to interact with, you can create your
484own preferences page.
485
486
487Integrating Your Options Into Existing SquirrelMail Preferences Pages
488---------------------------------------------------------------------
489
490There are two ways to accomplish the integration of your plugin's settings
491into another preferences page. The first method is to add the HTML code
492for your options directly to the preferences page of your choice. Although
493currently very popular, this method will soon be deprecated, so avoid it
494if you can. That said, here is how it works. :) Look for any of the hooks
495named as "options_<pref page>_inside", where <pref page> is "display",
496"personal", etc. For this example, we'll use "options_display_inside" and,
497as 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:
57945c53 535
9cd2ae7d 536 $squirrelmail_plugin_hooks['options_display_save']['demo']
537 = 'demo_save_options';
57945c53 538
9cd2ae7d 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
551The second way to add options to one of the SquirrelMail preferences page is
552to use one of the "optpage_loadhook_<pref page>" hooks. The sent_subfolders
60eeb409 553plugin has an excellent example of this method. Briefly, this way of adding
9cd2ae7d 554options consists of adding some plugin-specific information to a predefined
555data structure which SquirrelMail then uses to build the HTML input forms
556for 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
6976aad7 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
361d6e1b 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.)
6976aad7 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)
60eeb409 611 input
6976aad7 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.
9cd2ae7d 651
60eeb409 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
9cd2ae7d 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
704Creating Your Own Preferences Page
705----------------------------------
706
707It is also possible to create your own preferences page for a plugin. This
708is particularly useful when your plugin has numerous options or needs to
709offer special interaction with the user (for things such as changing password,
710etc.). Here is an outline of how to do so (again, using the "demo" plugin
711name):
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:
57945c53 781
9cd2ae7d 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
893Preferences
894-----------
895
896Saving and retrieving user preferences is very easy in SquirrelMail.
897SquirrelMail supports preference storage in files or in a database
898backend, however, the code you need to write to manipulate preferences
899is the same in both cases.
900
901Setting 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
914Loading 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
950Internationalization
951--------------------
952
953Although this document may only be available in English, we sure hope that you
954are thinking about making your plugin useful to the thousands of non-English
955speaking SquirrelMail users out there! It is almost rude not to do so, and
956it isn't much trouble, either. This document will only describe how you can
957accomplish the internationalization of a plugin. For more general information
958about PHP and SquirrelMail translation facilities, see:
959
960http://www.squirrelmail.org/wiki/wiki.php?LanguageTranslation
961
962The unofficial way to internationalize a plugin is to put all plugin output
963into the proper format but to rely on the SquirrelMail translation facilities
964for all the rest. If the plugin were really to get translated, you'd need
965to make sure that all output strings for your plugin are either added to or
966already exist in the main SquirrelMail locale files.
967
968The better way to make sure your plugin is translated is to create your own
969locale files and what is called a "gettext domain" (see the link above for
970more information).
971
972There are three basic steps to getting your plugins internationalized: put
973all output into the proper format, switch gettext domains and create locale
974files.
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.
df788686 1100 # $Id$
9cd2ae7d 1101 msgid ""
1102 msgstr ""
df788686 1103 "Project-Id-Version: plugin-name version\n"
9cd2ae7d 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
d2b351d7 1123 msgfmt -o <plugin name>.mo <plugin name>.po
9cd2ae7d 1124
1125 In the case of the "demo" plugin:
1126
d2b351d7 1127 msgfmt -o demo.mo demo.po
9cd2ae7d 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
a7532db9 1135
1136Documenting the Code (Optional)
1137-------------------------------
1138
1139If you wish, you can use phpdoc (Javadoc-style) comments, when documenting your
1140code.
1141
1142If you follow the standards that are followed between Squirrelmail core &
1143plugin developers, the resulted documentation can be included with the rest of
1144the Squirrelmail code & API documentation. Specifically, in the page-level
1145docblock, declare the package to be 'plugins', and the subpackage to be the
1146name 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
1158The rest is up to you. Try to follow some common sense and document what is
1159really needed. Documenting the code properly can be a big help not only to
1160yourself, but to those who will take a look at your code, fix the bugs and even
1161improve it, in the true open-source spirit that Squirrelmail was built upon.
1162
1163For more information about phpdocumentor and how to write proper-tagged
1164comments, you are directed at:
1165
1166http://phpdocu.sourceforge.net/
1167
1168
1169
9cd2ae7d 1170PLUGIN STANDARDS AND REQUIREMENTS
1171=================================
1172
1173The SquirrelMail project has some important goals, such as avoiding the
1174use of JavaScript, avoiding non-standard HTML tags, keeping file sizes
1175small and providing the fastest webmail client on the Internet. As such,
1176we'd like it if plugin authors coded with the same goals in mind that the
1177core developers do. Common sense is always a good tool to have in your
1178programming repertoire, but below is an outline of some standards that we
1179ask you as a plugin developer to meet. Depending upon how far you bend
1180these rules, we may not want to post your plugin on the SquirrelMail
1181website... and of course, no one really wants your efforts to go to waste
1182and for the SquirrelMail community to miss out on a potentially useful
1183plugin, so please try to follow these guidelines as closely as possible.
1184
1185
1186Small setup.php
1187---------------
1188
1189In order for SquirrelMail to remain fast and lean, we are now asking
1190that all plugin authors remove all unnecessary functionality from setup.php
d2b351d7 1191and refactor it into another file. There are a few ways to accomplish
9cd2ae7d 1192this, none of which are difficult. At a minimum, you'll want to have the
1193squirrelmail_plugin_init_<plugin name>() function in setup.php, and naturally,
1194you'll need functions that are merely stubs for each hook that you are using.
1195One (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
1209Internationalization
1210--------------------
1211
1212Q: 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?
1214A: Learning that they cannot send you a French translation file for your
1215 plugin.
1216
1217There are thousands of users out there whose native tongue is not English,
1218and when you develop your plugin without going through the three simple steps
1219needed to internationalize it, you are effectively writing them all off.
1220PLEASE consider internationalizing your plugin!
1221
1222
1223Developing with E_ALL
1224---------------------
1225
1226When you are developing your plugin, you should always have error reporting
1227turned all the way up. You can do this by changing two settings in your
1228php.ini and restarting your web server:
1229
799c2046 1230 display_errors = On
9cd2ae7d 1231 error_reporting = E_ALL
1232
1233This way, you'll be sure to see all Notices, Warnings and Errors that your
1234code generates (it's OK, really, it happens to the best of us... except me!).
1235Please make sure to fix them all before you release the plugin.
1236
1237
1b6b1526 1238Compatibility with register_globals=Off
1239---------------------------------------
1240
1241Most sensible systems administrators now run their PHP systems with the
1242setting "register_globals" as OFF. This is a prudent security setting,
1243and as the SquirrelMail core code has long since been upgraded to work
1244in such an environment, we are now requiring that all plugins do the same.
1245Compatibility with this setting amounts to little more than explicitly
1246gathering any and all variables you sent from a <form> tag as GET or POST
1247values instead of just assuming that they will be placed in the global
1248scope automatically. There is nothing more to do than this:
1249
1250 global $favorite_color;
1251 sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
1252
1253
9cd2ae7d 1254Extra Blank Lines
1255-----------------
1256
1257It may seem innocuous, but if you have any blank lines either before the
1258first <?php tag or after the last ?> tag in any of your plugin files, you
1259you will break SquirrelMail in ways that may seem entirely unrelated. For
1260instance, this will often cause a line feed character to be included with
1261email attachments when they are viewed or downloaded, rendering them useless!
1262
1263
1264include_once
1265------------
1266
1267When including files, please make sure to use the include_once() function
1268and NOT include(), require(), or require_once(), since these all are much
1269less efficient than include_once() and can have a cumulative effect on
1270SquirrelMail performance.
1271
1272
1273Version Reporting
1274-----------------
1275
1276In order for systems administrators to keep better track of your plugin and
1277get upgrades more efficiently, you are requested to make version information
1278available to SquirrelMail in a format that it understands. There are two
1279ways to do this. Presently, we are asking that you do both, since we are
1280still in a transition period between the two. This is painless, so please
1281be 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
1304Configuration Files
1305-------------------
1306
1307It is common to need a configuration file that holds some variables that
1308are set up at install time. For ease of installation and maintenance, you
1309should place all behavioral settings in a config file, isolated from the
1310rest of your plugin code. A typical file name to use is "config.php". If
1311you are using such a file, you should NOT include a file called "config.php"
1312in your plugin distribution, but instead a copy of that file called
1313"config.php.sample". This helps systems administrators avoid overwriting
1314the "config.php" files and losing all of their setup information when they
1315upgrade your plugin.
1316
1317
1318Session Variables
1319-----------------
1320
1321In the past, there have been some rather serious issues with PHP sessions
1322and SquirrelMail, and certain people have worked long and hard to ensure
1323that these problems no longer occur in an extremely wide variety of OS/PHP/
1324web server environments. Thus, if you need to place any values into the
1325user's session, there are some built-in SquirrelMail functions that you are
1326strongly 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
ea26c996 1349 global $favorite_color;
9cd2ae7d 1350 sqsession_unregister('favorite_color');
1351
ea26c996 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
9cd2ae7d 1355
1356Form Variables
1357--------------
1358
1359You are also encouraged to use SquirrelMail's built-in facilities to
1360retrieve variables from POST and GET submissions. This is also much
1361easier on you and makes sure that all PHP installations are accounted
1362for (such as those that don't make the $_POST array automatically
1363global, etc.):
1364
1365 global $favorite_color;
1366 sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
1367
1368
1369Files In Plugin Directory
1370-------------------------
1371
1372There are a few files that you should make sure to include when you build
1373your 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
1456COMPATIBILITY WITH OLDER VERSIONS OF SQUIRRELMAIL
1457=================================================
1458
1459Whenever new versions of SquirrelMail are released, there is always a
1460considerable lag time before it is widely adopted. During that transitional
1461time, especially when the new SquirrelMail version contains any architectural
1462and/or functional changes, plugin developers are put in a unique and very
1463difficult position. That is, there will be people running both the old and
1464new versions of SquirrelMail who want to use your plugin, and you will
1465probably want to accomodate them both.
1466
1467The easiest way to keep both sides happy is to keep two different versions
1468of your pluign up to date, one that runs under the older SquirrelMail, and
1469one that requires the newest SquirrelMail. This is inconvenient, however,
1470especially if you are continuing to develop the plugin. Depending on the
1471changes the SquirrelMail has implemented in the new version, you may be able
1472to include code that can auto-sense SquirrelMail version and make adjustments
1473on the fly. There is a function available to you for determining the
1474SquirrelMail version called check_sm_version() and it can be used as such:
1475
1476 check_sm_version(1, 4, 0)
1477
1478This will return TRUE if the SquirrelMail being used is at least 1.4.0, and
1479FALSE otherwise.
1480
1481As this document is written, we are in a transition period between versions
14821.2.11 and 1.4.0. There is a plugin called "Compatibilty" that is intended
1483for use by plugin authors so they can develop one version of their plugin
1484and seamlessly support both 1.2.x and 1.4.x SquirrelMail installations. For
1485more information about how to use the "Compatibility" plugin, download it and
1486read its README file or see:
1487
1488 http://www.squirrelmail.org/wiki/wiki.php?PluginUpgrading
1489
1490
1491REQUESTING NEW HOOKS
1492====================
1493
1494It'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
1496negotiate the insertion of a new hook to make your plugin work. In order
1497to do so, you should post such a request to the squirrelmail-devel mailing
1498list.
1499
1500
1501HOW TO RELEASE YOUR PLUGIN
1502==========================
1503
1504As long as you've consulted the list of plugin standards and done your
1505best to follow them, there's little standing in the way of great fame as an
1506official 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