X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2Fplugin.txt;h=a05a67096ae76fb64d8a11144f909834456c1ad1;hb=924b0caccf7a39b4e79850f608a122e867708631;hp=c3244660b26a2e3f171a7417ff35d835cf018401;hpb=0e8c1c9a1191a7dfae532c959e30a8a846a131e7;p=squirrelmail.git diff --git a/doc/plugin.txt b/doc/plugin.txt index c3244660..a05a6709 100644 --- a/doc/plugin.txt +++ b/doc/plugin.txt @@ -1,16 +1,21 @@ -A FEW NOTES ON THE PLUGIN ARCHITECTURE -====================================== +$Id$ + +It is best if you check out the SquirrelMail development FAQ for more +information. This document may be obsoleted at some point in the future (or +maybe we'll write a script to get the wiki contents and dump them in here +automatically). -The plugin architecture of SquirrelMail is designed to make it -possible to add new features without having to patch SquirrelMail -itself. At the moment the plugin part of SquirrelMail should be -considered "alpha" or "beta" quality code. +FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ +Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins -Until the functionality and code is more stable, be prepared for -plugins to suddenly stop working. -Functionality like password changing, displaying ads and calendars -should be possible to add as plugins. +A FEW NOTES ON THE PLUGIN ARCHITECTURE +====================================== + +The plugin architecture of SquirrelMail is designed to make it possible to +add new features without having to patch SquirrelMail itself. Functionality +like password changing, displaying ads and calendars should be possible to +add as plugins. The idea @@ -34,9 +39,9 @@ The implementation In the main SquirrelMail files the file functions/plugin.php. In places where hooks are made available they are executed by calling the -function do_hook("hookname"). +function do_hook('hookname'). -The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"] +The do_hook traverses the array $squirrelmail_plugin_hooks['hookname'] and executes all the functions that are named in that array. A plugin must reside in a subdirectory in the plugins/ directory. The @@ -45,7 +50,7 @@ name of the subdirectory is considered the name of the plugin. To start using a plugin, its name must be added to the $plugins array in config.php like this: - $plugins[0] = "plugin_name"; + $plugins[0] = 'plugin_name'; When a plugin is registered the file plugins/plugin_name/setup.php is included and the function squirrelmail_plugin_init_plugin_name is @@ -64,13 +69,13 @@ initalize a plugin. This function could look something like this: function squirrelmail_plugin_init_demo () { global $squirrelmail_plugin_hooks; - $squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header"; - $squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline"; + $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; + $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline'; } Note that the SquirrelMail files assume that all other SquirrelMail files are available as ../directory/file. This means that if some file -in the plugin directory is requested, it must do a chdir("..") before +in the plugin directory is requested, it must do a chdir('..') before including any of the standard SquirrelMail files. @@ -107,7 +112,13 @@ List of hooks * options_folders_bottom src/options_folders.php * options_folders_inside src/options_folders.php * options_folders_save src/options_folders.php + & options_identities_process src/options_identities.php + & options_identities_top src/options_identities.php + & options_identities_renumber src/options_identities.php (multiple places) + & options_identities_table src/options_identities.php + & options_identities_buttons src/options_identities.php logout src/signout.php + logout_above_text src/signout.php login_before src/webmail.php login_verified src/webmail.php loading_prefs src/load_prefs.php @@ -115,6 +126,7 @@ List of hooks mailbox_index_after functions/mailbox_display.php mailbox_form_before functions/mailbox_display.php subject_link functions/mailbox_display.php + motd src/right_main.php right_main_after_header src/right_main.php right_main_bottom src/right_main.php login_top src/login.php @@ -124,6 +136,8 @@ List of hooks read_body_bottom src/read_body.php html_bottom src/read_body.php read_body_header src/read_body.php + read_body_header_right src/read_body.php + read_body_after_from src/read_body.php search_before_form src/search.php search_after_form src/search.php search_bottom src/search.php @@ -134,7 +148,6 @@ List of hooks addressbook_bottom src/addressbook.php ^ attachment $type0/$type1 functions/mime.php (see note on attachments) - (*) Options ----------- There are two ways to do options for your plugin. First, you can incorporate it @@ -172,21 +185,22 @@ It is possible to create your own options sections with plugins. There are three hooks you will need to use. 1. options_link_and_description - This creates the link and has a description that are shown on the options - page. This should output HTML that looks like this: + This creates the link and has a description that is shown on the options + page. This should output HTML that looks like this. Make sure to read + the section on outputing your own pages. -----cut here----- - function my_function() { + function my_plugin_name_my_function() { global $color ?> - - @@ -211,6 +225,33 @@ three hooks you will need to use. src/load_prefs.php +(&) Identity Hooks +------------------ +Some hooks are passed special information in the array of arguments. See +the SpamCop plugin for how to use them. + +options_identities_process + [0] = Hook's name + [1] = Should I run the SaveUpdateFunction() (alterable) + +options_identities_renumber + [0] = Hook's name + [1] = Renumber it from ('default' or 1 through # idents - 1) + [2] = Renumber it to (same thing) + +options_identities_table + [0] = Hook's name + [1] = Color of table (use it like > in your + plugin) + [2] = Is this an empty section? + [3] = What is the 'post' value? + +options_identities_buttons + [0] = Hook's name + [1] = Is this an empty section (the one at the end of the list)? + [2] = What is the 'post' value? + + (^) Attachment Hooks -------------------- When a message has attachments, this hook is called with the MIME types. For @@ -236,3 +277,41 @@ To set up links for actions, you assign them like this: $Args[1]['your_plugin_name']['href'] = 'URL to link to'; $Args[1]['your_plugin_name']['text'] = 'What to display'; +It's also possible to specify a hook as "attachment type0/*", +for example "attachment text/*". This hook will be executed whenever there's +no more specific rule available for that type. + + +Outputting Your Own Pages +------------------------- + +Often, when you want to provide your own customized options screen or create +another web page instead of just using standard hooks, you will be creating +your own .php files. An example of this is the attachment_common plugin's +image.php file. + +To make sure that security is maintained and standards are followed, the top +of your PHP script should look very similar to this: + +
+ YOUR OPTIONS NAME
+ YOUR DESCRIPTION