X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2Fplugin.txt;h=ecbfc0c7a6e4e74ad0b945819e2b5087ac35a2b4;hb=6e097fb53cbf92507816803f9a7c0fa3a7cbac53;hp=42da7736fdfa35f3f64c4480be9fce38c0b77f74;hpb=d2b351d70c68d3cdc031cf1e7b8fcabf4e1066f4;p=squirrelmail.git diff --git a/doc/plugin.txt b/doc/plugin.txt index 42da7736..ecbfc0c7 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 @@ -190,11 +234,12 @@ but may be out of date soon thereafter. You never know. ;-) Hook Name Found In Called With(#) --------- -------- -------------- 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 @@ -204,6 +249,7 @@ but may be out of date soon thereafter. You never know. ;-) 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 @@ -221,7 +267,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 @@ -1056,6 +1101,41 @@ files. 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 + * 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 =================================