is easily obtained by posting to the squirrelmail-plugins mailing
list. (See details about mailing lists on the website)
-FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
+FAQ -> http://www.squirrelmail.org/wiki/DeveloperFAQ
Plugin Development ->
- http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
+ http://www.squirrelmail.org/wiki/DevelopingPlugins
A FEW NOTES ON THE PLUGIN ARCHITECTURE
1.7. class/mime/Language.class.php
1.8. class/mime/ContentType.class.php
2. functions/global.php
+ * fixes differences between php 4.0.x and 4.1+ globals (only in 1.4.x).
+ * undoes magic_quotes_gpc=on sanitizing
+ * sets $PHP_SELF (since 1.5.1)
+ * starts session
3. functions/strings.php
+ 3.1. functions/global.php
+ 3.2. plugins/compatibility/functions.php (compatibility v.2.0.4+, requires
+ code patching)
+ * sets squirrelmail version variable and constant.
+ * sets $PHP_SELF (before 1.5.1)
4. config/config.php
4.1. config/config_local.php (from 1.4.0rc1)
5. functions/i18n.php
5.1. functions/global.php (from 1.4.0)
+ * reads 'squirrelmail_language' cookie
+ * loads $languages (since 1.5.1 $languages array is built from
+ locale/*/setup.php files)
+ * loads own gettext functions, if php gettext is unavailable
6. functions/auth.php
7. include/load_prefs.php
7.1. include/validate.php
7.2. functions/prefs.php
+ 7.2.1. functions/global.php (sqgetGlobalVar() function)
+ 7.2.2. functions/plugin.php (do_hook_function() function,,
+ since 1.4.4 and 1.5.1, see 7.3)
+ 7.2.3. $prefs_backend (only in 1.4.3 and 1.5.0)
+ do_hook_function('prefs_backend') (since 1.4.4 and 1.5.1)
+ functions/db_prefs.php
+ functions/file_prefs.php
+ 7.2.3.1. functions/display_messages.php
+ (loaded only by file_prefs.php)
+ 7.2.3.2. files loaded by plugin that uses 'prefs_backend' hook
7.3. functions/plugin.php
7.3.1. functions/global.php (from 1.4.0 and 1.5.0)
7.3.2. functions/prefs.php (from 1.5.1)
+ 7.3.3. plugins/*/setup.php files for enabled plugins.
+ * starts all squirrelmail_plugin_init_pluginname functions
7.4. functions/constants.php
7.5. do_hook('loading_prefs')
- 7.5.1. files loaded by plugins that use 'loading_prefs'
+ 7.5.1. files loaded by plugins that use 'loading_prefs' hook
8. functions/page_header.php
8.1. functions/strings.php
8.2. functions/html.php
8.3. functions/imap_mailbox.php
8.3.1. functions/imap_utf7_local.php
8.4. functions/global.php
- 9. functions/prefs.php
- 9.1. functions/global.php
- 9.2. $prefs_backend (only in 1.4.3 and 1.5.0)
- do_hook_function('prefs_backend') (since 1.4.4 and 1.5.1)
- functions/db_prefs.php
- functions/file_prefs.php
- 9.2.1. functions/display_messages.php
- (loaded only by file_prefs.php)
- 9.2.2. files loaded by plugin that uses 'prefs_backend'
+ 9. functions/prefs.php (already loaded. see 7.2)
+
+Since SquirrelMail 1.5.1 functions/global.php file must be loaded before
+setting any own global variables. If variables are set before loading
+functions/global.php library, they can be corrupted in PHP register_globals=On
+setups.
+
Hook Types: Parameters and Return Values
-----------------------------------------
error_box functions/display_messages.php concat_hook
get_pref_override functions/file_prefs.php hook_func
get_pref functions/file_prefs.php hook_func
+& options_identities_process functions/identity.php do_hook
+&% options_identities_renumber functions/identity.php do_hook
special_mailbox functions/imap_mailbox.php hook_func
% rename_or_delete_folder functions/imap_mailbox.php hook_func
mailbox_index_before functions/mailbox_display.php do_hook
loading_prefs include/load_prefs.php do_hook
addrbook_html_search_below src/addrbook_search_html.php do_hook
addressbook_bottom src/addressbook.php do_hook
- compose_form src/compose.php do_hook
+! compose_form src/compose.php do_hook
compose_bottom src/compose.php do_hook
compose_button_row src/compose.php do_hook
compose_send src/compose.php do_hook
+ compose_send_after src/compose.php do_hook
folders_bottom src/folders.php do_hook
help_top src/help.php do_hook
help_chapter src/help.php do_hook
left_main_after src/left_main.php do_hook
login_cookie src/login.php do_hook
login_top src/login.php do_hook
- login_form src/login.php do_hook
+ login_form src/login.php concat_hook
+ (was do_hook before 1.5.1)
login_bottom src/login.php do_hook
* optpage_set_loadinfo src/options.php do_hook
* optpage_loadhook_personal src/options.php do_hook
* options_folder_bottom src/options.php do_hook
* options_order_bottom src/options.php do_hook
* options_highlight_bottom src/options_highlight.php do_hook
-& options_identities_process src/options_identities.php do_hook
& options_identities_top src/options_identities.php do_hook
-&% options_identities_renumber src/options_identities.php do_hook
& options_identities_table src/options_identities.php concat_hook
& options_identities_buttons src/options_identities.php concat_hook
message_body src/printer_friendly_bottom.php do_hook
read_body_bottom src/read_body.php do_hook
login_before src/redirect.php do_hook
login_verified src/redirect.php do_hook
- generic_header src/right_main.php do_hook
right_main_after_header src/right_main.php do_hook
right_main_bottom src/right_main.php do_hook
search_before_form src/search.php do_hook
^ = Special attachments hook (see below)
* = Special options hooks (see below)
O = Optional hook provided by a particular plugin
+! = See below for notes about working with the compose page's <form> tag
(#) Called With
concat_hook concat_hook_function()
+(!) Compose Form
+----------------
+The compose_form hook allows plugins to insert their own code into
+the form tag for the main message composition HTML form. Usually
+plugins will want to insert some kind of code in an onsubmit event
+handler. In order to allow more than one plugin to do so, all plugins
+using this hook to add some onsubmit code need to add that code (without
+the enclosing attribute name and quotes) as a new array entry to the
+global $compose_onsubmit array. The code should use "return false"
+if the plugin has found a reason to stop form submission, otherwise,
+it should DO NOTHING (that is, please do not use "return true", as that
+will prevent other plugins from using the onsubmit handler). SquirrelMail
+itself will insert a final "return true". All onsubmit code will be
+enclosed in double quotes by SquirrelMail, so plugins need to quote
+accordingly if needed. For example:
+
+ global $compose_onsubmit;
+ $compose_onsubmit[] = ' if (somevar == \'no\') return false; ';
+
+Note the escaped single quotes. If you use double quotes, they would have
+to be escaped as such:
+
+ global $compose_onsubmit;
+ $compose_onsubmit[] = ' if (somevar == \'no\') { alert(\\"Sorry\\"); return false; }';
+
+Any other form tag additions by a plugin (beside onsubmit event code) can
+currently be echoed directly to the browser.
+
+
(&) Identity Hooks
------------------
This set of hooks is passed special information in the array of arguments:
for each identity or catch any custom submit buttons that you may
have added to the identities page. The arguments to this hook are:
+ (SquirrelMail 1.4.4 or older and 1.5.0)
[0] = hook name (always "options_identities_process")
[1] = should I run the SaveUpdateFunction() (alterable)
trigger SaveUpdateFunction() after the hook is finished - by default,
it will not be called.
+ (SquirrelMail 1.4.6+ or 1.5.1+)
+ [0] = hook name (always "options_identities_process")
+ [1] = action (hook is used only in 'update' action and any custom
+ action added to form with option_identities_table and
+ option_identities_buttons hooks)
+ [2] = processed identity number
+
+ Hook is not available in SquirrelMail 1.4.5.
+
options_identities_renumber
This hook is called when one of the identities is being renumbered,
[1] = being renumbered from ('default' or 1 through (# idents) - 1)
[2] = being renumbered to ('default' or 1 through (# idents) - 1)
+ Hook is not available in SquirrelMail 1.4.5. Renumbering order differs
+ in 1.4.5+ and 1.5.1+.
+
options_identities_table
This hook allows you to insert additional rows into the table that
holds each identity. The arguments to this hook are:
- [0] = color of table (use it like this in your plugin:
- <tr bgcolor="<?php echo $info[1]; ?>">
+ [0] = additional html attributes applied to table row.
+ use it like this in your plugin:
+ <tr "<?php echo $args[0]; ?>">
[1] = is this an empty section (the one at the end of the list)?
[2] = what is the 'post' value? (ident # or empty string if default)
. 'YOUR CODE HERE' . '</td></tr>' . "\n";
}
+ First hook argument was modified in 1.4.5/1.5.1. In SquirrelMail 1.4.1-1.4.4
+ and 1.5.0 argument contains only background color. You should use
+ <tr bgcolor="<?php echo $args[0]; ?>"> in these SquirrelMail versions.
+
options_identities_buttons
This hook allows you to add a button (or other HTML) to the row of
. '" value="Press Me" />';
}
+ Input element should use 'smaction[action_name][identity_no]' value in
+ 'name' attribute, if you want to process your button actions in
+ SquirrelMail 1.4.6+ and 1.5.1+ options_identity_process hook.
+
+
+See sample implementation of identity hooks in SquirrelMail demo plugin.
+
+ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/squirrelmail \
+ co plugins/demo
+
(^) Attachment Hooks
--------------------
htmlencoded disables html sanitizing. WARNING - don't use it, if user
input is possible in option or use own sanitizing functions.
Currently works only with SMOPT_TYPE_STRLIST.
+ folder_filter Controls folder list limits in SMOPT_TYPE_FLDRLIST widget.
+ See $flag argument in sqimap_mailbox_option_list()
+ function. Available since 1.5.1.
Note that you do not have to create a whole new section on the options
page if you merely want to add a simple input item or two to an options
accomplish the internationalization of a plugin. For more general information
about PHP and SquirrelMail translation facilities, see:
-http://www.squirrelmail.org/wiki/wiki.php?LanguageTranslation
+http://www.squirrelmail.org/wiki/LanguageTranslation
The unofficial way to internationalize a plugin is to put all plugin output
into the proper format but to rely on the SquirrelMail translation facilities
global $favorite_color;
sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
+SquirrelMail 1.5.1+ cleans globals in functions/global.php library. If
+plugin depends on PHP register_globals=On and loads this library, it will
+be broken.
+
Security considerations
-----------------------
-All plugins should consider the security implications of their plugin.
-Of course, if you call external programs you have to use great care,
-but the following issues are important to nearly every plugin.
+All plugin authors should consider the security implications of their
+plugin. Of course, if you call external programs you have to use great
+care, but the following issues are important to nearly every plugin.
- Escape any untrusted data before you output it. This is to prevent
-cross site scripting attachs. It means that you have to htmlspecialchar()
+cross site scripting attacks. It means that you have to htmlspecialchars()
every variable that comes in through the URL, a mail message or other
external factors, before outputting it.
enabled. If you just call hooks, your hooks won't be called when the
plugin is disabled, but if you also supply extra .php files, you should
check if they perform any function if accessed directly. If they do, you
-should check at the start of that file if the plugin is enabled in the
+should check at the start of that file whether the plugin is enabled in the
config, and if not, exit the script. Example:
global $plugins;
if ( !in_array('mypluginname', $plugins) ) {
more information about how to use the "Compatibility" plugin, download it and
read its README file or see:
- http://www.squirrelmail.org/wiki/wiki.php?PluginUpgrading
+ http://www.squirrelmail.org/wiki/PluginUpgrading
REQUESTING NEW HOOKS
do not respond, you should feel free to ask for help contacting them
on the squirrelmail-plugins mailing list.
- http://www.squirrelmail.org/wiki/wiki.php?SquirrelMailLeadership
+ http://www.squirrelmail.org/wiki/SquirrelMailLeadership