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