X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2Fplugin.txt;h=6116ae6e510904980fdc2b9b7003f69acf6d718e;hb=8ed1cfc66bd1501fbea3bdd70661a9e31ef6e6be;hp=342ac78b13c1cfb8ed92eb4d9e28913f4ea14d44;hpb=c4115032a99a993a6f2e4dd8fe43fa2d555bea46;p=squirrelmail.git diff --git a/doc/plugin.txt b/doc/plugin.txt index 342ac78b..6116ae6e 100644 --- a/doc/plugin.txt +++ b/doc/plugin.txt @@ -155,28 +155,72 @@ versions. 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 @@ -189,12 +233,15 @@ but may be out of date soon thereafter. You never know. ;-) 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 @@ -222,7 +269,6 @@ but may be out of date soon thereafter. You never know. ;-) left_main_after_each_folder src/left_main.php concat_hook left_main_before src/left_main.php do_hook left_main_after src/left_main.php do_hook - create_collapse_link src/left_main.php hook_func login_cookie src/login.php do_hook login_top src/login.php do_hook login_form src/login.php do_hook @@ -259,7 +305,7 @@ but may be out of date soon thereafter. You never know. ;-) & 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 @@ -276,14 +322,16 @@ but may be out of date soon thereafter. You never know. ;-) 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 @@ -331,7 +379,7 @@ options_identities_table holds each identity. The arguments to this hook are: [0] = color of table (use it like this in your plugin: -