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