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