Hook Types: Parameters and Return Values
-----------------------------------------
-Hooks, when executed, are called with one parameter, an array of data
-that is passed to the hook. The first element in the array is the name
-of the hook that is being called. Any other elements in the array are
-dependant on the type of hook that is being called. Most hooks do not
-pass any other data, but be sure to check the hook you are using for
-any useful information it may provide. Generally speaking, in the case
-that any extra data is available here, your plugin should NOT change
-it unless you know what you are doing or it is documented otherwise.
-See below for further discussion of special hook types and the values
+Hooks, when executed, are called with differing parameters and may or may
+not take return values, all depending on the type of hook being called and
+the context in which it is being used. On the source side (where the hook
+call originates), all hooks have at least one parameter, which is the
+name of the hook. After that, things get complicated.
+
+ do_hook
+ -------
+ Most hook calls don't pass any data and don't ask for anything back.
+ These always use the do_hook call. A limited number of do_hook calls do
+ pass some extra parameters, in which case your plugin may modify the
+ given data if you do so by reference. It is not necessary to return
+ anything from your function in such a case; modifying the parameter
+ data by reference is what does the job (although the hook call itself
+ (in the source) must grab the return value for this to work). Note
+ that in this case, the parameter to your hook function will be an array,
+ the first element simply being the hook name, followed by any other
+ parameters that may have been included in the actual hook call in the
+ source. Modify parameters with care!
+
+ do_hook_function
+ ----------------
+ This hook type was intended to be the main hook type used when the
+ source needs to get something back from your plugin. It is somewhat
+ limited in that it will only use the value returned from the LAST
+ plugin registered against the hook. The source for this hook might
+ use the return value for internal purposes, or might expect you to
+ provide text or HTML to be sent to the client browser (you'll have to
+ look at its use in context to understand how you should return values
+ here). The parameters that your hook function gets will be anything
+ you see AFTER the hook name in the actual hook call in the source.
+ These cannot be changed in the same way that the do_hook parameters
+ can be.
+
+ concat_hook_function
+ --------------------
+ This is a newer hook type meant to address the shortcomings of
+ do_hook_function; specifically in that it uses the return values of
+ all plugins registered against the hook. In order to do so, the
+ return value is assumed to be a string, which is just piled on top
+ of whatever it got from the other plugins working on the same hook.
+ Again, you'll have to inspect the source code to see how such data
+ is put to use, but most of the time, it is used to create a string
+ of HTML to be inserted into the output page. The parameters that
+ your hook function will get are the same as for the do_hook_function;
+ they are anything AFTER the hook name in the actual hook call in the
+ source.
+
+ boolean_hook_function
+ ---------------------
+ The newest of the SquirrelMail hooks, this type is used to let all
+ plugins registered against the hook to "vote" for some action. What
+ that action is is entirely dependent on how the hook is used in the
+ source (look for yourself). Plugins make their "vote" by returning
+ TRUE or FALSE. This hook may be configured to "tally votes" in one
+ of three ways. This configuration is done with the third parameter
+ in the hook call in the source:
+ > 0 -- Any one or more TRUEs will override any FALSEs
+ < 0 -- Any one or more FALSEs will override any TRUEs
+ = 0 -- Majority wins. Ties are broken in this case with
+ the last parameter in the hook call in the source.
+ Your hook function will get the second paramter in the hook call in
+ the source as its parameter (this might be an array if multiple values
+ need to be passed).
-Most hooks, when executed, are called using the do_hook() function,
-where no return value is used. There are a limited number of hooks,
-however, that are called using the do_hook_function() and
-concat_hook_function() function calls. Both of these hook types may
-use the value returned by your plugin for its own purposes or to
-display in the resultant HTML output (you need to research the specific
-hook to determine its use). The do_hook_function() type hook will
-only use the return value it retrieves from the LAST plugin in the
-list of plugins registered against such a hook, whereas the
-concat_hook_function() type hook will concatenate the return values
-from all plugins that are registered against the hook and use that
-value (usually as a string of HTML code to output to the client).
+See below for further discussion of special hook types and the values
List of Hooks
Hook Name Found In Called With(#)
--------- -------- --------------
+ abook_init functions/addressbook.php do_hook
+ abook_add_class functions/addressbook.php do_hook
loading_constants functions/constants.php do_hook
+ logout_error functions/display_messages.php do_hook
+ 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
special_mailbox functions/imap_mailbox.php hook_func
% rename_or_delete_folder functions/imap_mailbox.php hook_func
- msg_envelope functions/mailbox_display.php do_hook
mailbox_index_before functions/mailbox_display.php do_hook
mailbox_form_before functions/mailbox_display.php do_hook
mailbox_index_after functions/mailbox_display.php do_hook
check_handleAsSent_result functions/mailbox_display.php do_hook
subject_link functions/mailbox_display.php concat_hook
+ mailbox_display_buttons functions/mailbox_display.php do_hook
message_body functions/mime.php do_hook
^ attachment $type0/$type1 functions/mime.php do_hook
+ attachments_bottom functions/mime.php hook_func
+ decode_body functions/mime.php hook_func
generic_header functions/page_header.php do_hook
menuline functions/page_header.php do_hook
+ internal_link functions/page_header.php hook_func
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
login_form src/login.php do_hook
login_bottom src/login.php do_hook
move_before_move src/move_messages.php do_hook
+ move_messages_button_action src/move_messages.php concat_hook
* optpage_set_loadinfo src/options.php do_hook
* optpage_loadhook_personal src/options.php do_hook
* optpage_loadhook_display src/options.php do_hook
& options_identities_buttons src/options_identities.php concat_hook
message_body src/printer_friendly_bottom.php do_hook
read_body_header src/read_body.php do_hook
- read_body_menu_top src/read_body.php do_hook
+ read_body_menu_top src/read_body.php hook_func
read_body_menu_bottom src/read_body.php do_hook
read_body_header_right src/read_body.php do_hook
- html_top src/read_body.php do_hook
read_body_top src/read_body.php do_hook
read_body_bottom src/read_body.php do_hook
- html_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
search_bottom src/search.php do_hook
logout src/signout.php do_hook
webmail_top src/webmail.php do_hook
- webmail_bottom src/webmail.php do_hook
+ webmail_bottom src/webmail.php concat_hook
logout_above_text src/signout.php concat_hook
+ O info_bottom plugins/info/options.php do_hook
% = This hook is used in multiple places in the given file
# = Called with hook type (see below)
& = Special identity hooks (see below)
^ = Special attachments hook (see below)
* = Special options hooks (see below)
+O = optional hook used by plugin
(#) Called With
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]?>">
+ <tr bgcolor="<?php echo $info[1]; ?>">
[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)
function demo_identities_button(&$args)
{
return '<input type="submit" name="demo_button_' . $args[1]
- . '" value="Press Me">';
+ . '" value="Press Me" />';
}
The second way to add options to one of the SquirrelMail preferences page is
to use one of the "optpage_loadhook_<pref page>" hooks. The sent_subfolders
-plugin is an excellent example of this method. Briefly, this way of adding
+plugin has an excellent example of this method. Briefly, this way of adding
options consists of adding some plugin-specific information to a predefined
data structure which SquirrelMail then uses to build the HTML input forms
for you. This is the preferred method of building options lists going forward.
The array that you use to specify each plugin option has the following
possible attributes:
- name The name of this setting, which is used not only for
- the INPUT tag name, but also for the name of this
- setting in the user's preferences
- caption The text that prefaces this setting on the preferences page
- type The type of INPUT element, which should be one of:
- SMOPT_TYPE_STRING String/text input
- SMOPT_TYPE_STRLIST Select list input
- SMOPT_TYPE_TEXTAREA Text area input
- SMOPT_TYPE_INTEGER Integer input
- SMOPT_TYPE_FLOAT Floating point number input
- SMOPT_TYPE_BOOLEAN Boolean (yes/no radio buttons)
- input
- SMOPT_TYPE_HIDDEN Hidden input (not actually shown
- on preferences page)
- SMOPT_TYPE_COMMENT Text is shown (specified by the
- 'comment' attribute), but no user
- input is needed
- SMOPT_TYPE_FLDRLIST Select list of IMAP folders
- refresh Indicates if a link should be shown to refresh part or all
- of the window (optional). Possible values are:
- SMOPT_REFRESH_NONE No refresh link is shown
- SMOPT_REFRESH_FOLDERLIST Link is shown to refresh
- only the folder list
- SMOPT_REFRESH_ALL Link is shown to refresh
- the entire window
- posvals For select lists, this should be an associative array,
- where each key is an actual input value and the
- corresponding value is what is displayed to the user
- for that list item in the drop-down list
- value Specify the default/preselected value for this option input
- save You may indicate that special functionality needs to be
- used instead of just saving this setting by giving the
- name of a function to call when this value would otherwise
- just be saved in the user's preferences
- size Specifies the size of certain input items (typically
- textual inputs). Possible values are:
- SMOPT_SIZE_TINY
- SMOPT_SIZE_SMALL
- SMOPT_SIZE_MEDIUM
- SMOPT_SIZE_LARGE
- SMOPT_SIZE_HUGE
- SMOPT_SIZE_NORMAL
- comment For SMOPT_TYPE_COMMENT type options, this is the text
- displayed to the user
- script This is where you may add any additional javascript
- or other code to the user input
+ name The name of this setting, which is used not only for
+ the INPUT tag name, but also for the name of this
+ setting in the user's preferences
+ caption The text that prefaces this setting on the preferences
+ page
+ trailing_text Text that follows a text input or select list input on
+ the preferences page (useful for indicating units,
+ meanings of special values, etc.)
+ type The type of INPUT element, which should be one of:
+ SMOPT_TYPE_STRING String/text input
+ SMOPT_TYPE_STRLIST Select list input
+ SMOPT_TYPE_TEXTAREA Text area input
+ SMOPT_TYPE_INTEGER Integer input
+ SMOPT_TYPE_FLOAT Floating point number input
+ SMOPT_TYPE_BOOLEAN Boolean (yes/no radio buttons)
+ input
+ SMOPT_TYPE_HIDDEN Hidden input (not actually
+ shown on preferences page)
+ SMOPT_TYPE_COMMENT Text is shown (specified by the
+ 'comment' attribute), but no
+ user input is needed
+ SMOPT_TYPE_FLDRLIST Select list of IMAP folders
+ refresh Indicates if a link should be shown to refresh part or
+ all of the window (optional). Possible values are:
+ SMOPT_REFRESH_NONE No refresh link is shown
+ SMOPT_REFRESH_FOLDERLIST Link is shown to refresh
+ only the folder list
+ SMOPT_REFRESH_ALL Link is shown to refresh
+ the entire window
+ initial_value The value that should initially be placed in this
+ INPUT element
+ posvals For select lists, this should be an associative array,
+ where each key is an actual input value and the
+ corresponding value is what is displayed to the user
+ for that list item in the drop-down list
+ value Specify the default/preselected value for this option
+ input
+ save You may indicate that special functionality needs to be
+ used instead of just saving this setting by giving the
+ name of a function to call when this value would
+ otherwise just be saved in the user's preferences
+ size Specifies the size of certain input items (typically
+ textual inputs). Possible values are:
+ SMOPT_SIZE_TINY
+ SMOPT_SIZE_SMALL
+ SMOPT_SIZE_MEDIUM
+ SMOPT_SIZE_LARGE
+ SMOPT_SIZE_HUGE
+ SMOPT_SIZE_NORMAL
+ comment For SMOPT_TYPE_COMMENT type options, this is the text
+ displayed to the user
+ script This is where you may add any additional javascript
+ or other code to the user input
+ post_script You may specify some script (usually Javascript) that
+ will be placed after (outside of) the INPUT tag.
+
+ 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
+ section that already exists. For example, the Display Options page has
+ these groups:
+
+ 0 - General Display Options
+ 1 - Mailbox Display Options
+ 2 - Message Display and Composition
+
+ To add our previous input drop-down to the Mailbox Display Options,
+ we would not have to create our own group; just add it to group
+ number one:
+
+ global $optpage_data;
+ $optpage_data['vals'][1][] = array(
+ 'name' => 'plugin_demo_favorite_color',
+ 'caption' => 'Please Choose Your Favorite Color',
+ 'type' => SMOPT_TYPE_STRLIST,
+ 'refresh' => SMOPT_REFRESH_ALL,
+ 'posvals' => array(0 => 'red',
+ 1 => 'blue',
+ 2 => 'green',
+ 3 => 'orange'),
+ 'save' => 'save_plugin_demo_favorite_color'
+ );
3. If you indicated a 'save' attribute for any of your options, you must
create that function (you'll only need to do this if you need to do
should always set "optpage" as a POST or GET variable with a string that
uniquely identifies your plugin:
- <input type="hidden" name="optpage" value="plugin_demo">
+ <input type="hidden" name="optpage" value="plugin_demo" />
Now in your demo_save_options_do() function, do something like this:
So, even in the HTML segments of your plugin files, you need to do this:
- <input type="submit" value="<?php echo _("Submit") ?>">
+ <input type="submit" value="<?php echo _("Submit"); ?>" />
You can put any text you want inside of the quotes (you MUST use double
quotes!), including HTML tags, etc. What you should think carefully
# Copyright (c) 1999-2003 The Squirrelmail Development Team
# Roland Bauerschmidt <rb@debian.org>, 1999.
+ # $Id$
msgid ""
msgstr ""
- "Project-Id-Version: $Id: squirrelmail.po,v 1.10 2003/06/04 15:01:59
- philippe_mingo Exp $\n"
+ "Project-Id-Version: plugin-name version\n"
"POT-Creation-Date: 2003-01-21 19:21+0100\n"
"PO-Revision-Date: 2003-01-21 21:01+0100\n"
"Last-Translator: Juergen Edner <juergen.edner@epost.de>\n"
After you're done translating, you can create the .mo file very simply
by running the following command (available on most linux systems):
- msgfmt -
0 <plugin name>.mo <plugin name>.po
+ msgfmt -
o <plugin name>.mo <plugin name>.po
In the case of the "demo" plugin:
- msgfmt -0 demo.mo demo.po
+ msgfmt -o demo.mo demo.po
Please be sure that the .po and .mo files both are named exactly the
same as the domain you bound in step 2 above and everything else works
and change your Language setting to see the translations in action!
+
+Documenting the Code (Optional)
+-------------------------------
+
+If you wish, you can use phpdoc (Javadoc-style) comments, when documenting your
+code.
+
+If you follow the standards that are followed between Squirrelmail core &
+plugin developers, the resulted documentation can be included with the rest of
+the Squirrelmail code & API documentation. Specifically, in the page-level
+docblock, declare the package to be 'plugins', and the subpackage to be the
+name of your plugin. For instance:
+
+/**
+ * demo.php
+ *
+ * Copyright (c) 2003 My Name <my-email-address>
+ * Licensed under the GNU GPL. For full terms see the file COPYING.
+ *
+ * @package plugins
+ * @subpackage demo
+ */
+
+The rest is up to you. Try to follow some common sense and document what is
+really needed. Documenting the code properly can be a big help not only to
+yourself, but to those who will take a look at your code, fix the bugs and even
+improve it, in the true open-source spirit that Squirrelmail was built upon.
+
+For more information about phpdocumentor and how to write proper-tagged
+comments, you are directed at:
+
+http://phpdocu.sourceforge.net/
+
+
+
PLUGIN STANDARDS AND REQUIREMENTS
=================================
In order for SquirrelMail to remain fast and lean, we are now asking
that all plugin authors remove all unnecessary functionality from setup.php
-and refactoring it into another file. There are a few ways to accomplish
+and refactor it into another file. There are a few ways to accomplish
this, none of which are difficult. At a minimum, you'll want to have the
squirrelmail_plugin_init_<plugin name>() function in setup.php, and naturally,
you'll need functions that are merely stubs for each hook that you are using.
turned all the way up. You can do this by changing two settings in your
php.ini and restarting your web server:
- display_errors = Off
+ display_errors = On
error_reporting = E_ALL
This way, you'll be sure to see all Notices, Warnings and Errors that your
Please make sure to fix them all before you release the plugin.
+Compatibility with register_globals=Off
+---------------------------------------
+
+Most sensible systems administrators now run their PHP systems with the
+setting "register_globals" as OFF. This is a prudent security setting,
+and as the SquirrelMail core code has long since been upgraded to work
+in such an environment, we are now requiring that all plugins do the same.
+Compatibility with this setting amounts to little more than explicitly
+gathering any and all variables you sent from a <form> tag as GET or POST
+values instead of just assuming that they will be placed in the global
+scope automatically. There is nothing more to do than this:
+
+ global $favorite_color;
+ sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
+
+
Extra Blank Lines
-----------------
projects / squirrelmail.git / blobdiff