X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2Fplugin.txt;h=a05a67096ae76fb64d8a11144f909834456c1ad1;hb=35b5fa1362017c76255ea8a99222818d7caec5a3;hp=99e5998d4cd4a783657f0a70e8b75fbbca88ee5a;hpb=6b6381715922c24dc8664cc62464096814d6a291;p=squirrelmail.git diff --git a/doc/plugin.txt b/doc/plugin.txt index 99e5998d..a05a6709 100644 --- a/doc/plugin.txt +++ b/doc/plugin.txt @@ -1,16 +1,21 @@ -A FEW NOTES ON THE PLUGIN ARCHITECTURE -====================================== +$Id$ -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. +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). -Until the functionality and code is more stable, be prepared for -plugins to suddenly stop working. +FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ +Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins -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,55 +69,138 @@ 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. +Hook Data Passed +---------------- +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. + +Some of the information in the array may be changed. By default, the +plugins should never change data unless it is documented otherwise. + + List of hooks ------------- - generic_header functions/page_header.php - menuline functions/page_header.php - compose_button_row src/compose.php - left_main_before src/left_main.php - left_main_after src/left_main.php - options_save src/options.php (see note on options) - options_link_and_description src/options.php (see note on options) - logout src/signout.php - login_before src/webmail.php - login_verified src/webmail.php - loading_prefs src/load_prefs.php - mailbox_index_before functions/mailbox_display.php - mailbox_index_after functions/mailbox_display.php - - -Options -------- - + generic_header functions/page_header.php + menuline functions/page_header.php + compose_button_row src/compose.php + compose_bottom src/compose.php + compose_form src/compose.php + compose_send src/compose.php + left_main_before src/left_main.php + left_main_after src/left_main.php + * options_save src/options.php (see note on options) + * options_link_and_description src/options.php (see note on options) + * options_highlight_bottom src/options_highlight.php + * options_personal_bottom src/options_personal.php + * options_personal_inside src/options_personal.php + * options_personal_save src/options_personal.php + * options_display_bottom src/options_display.php + * options_display_inside src/options_display.php + * options_display_save src/options_display.php + * 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 + mailbox_index_before functions/mailbox_display.php + 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 + login_bottom src/login.php + html_top src/read_body.php + read_body_top src/read_body.php + 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 + help_top src/help.php + help_bottom src/help.php + help_chapter src/help.php + addrbook_html_search_below src/addrbook_search_html.php + 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 +into an existing section of the preferences (Display, Personal, or Folders). +The second way, you create your own section that they can choose from and it +displays its own range of options. + + +First: Integrating into existing options +----------------------------------------- +There are two hooks you need to use for this one: + +1. options_YOUCHOOSE_inside + This is the code that goes inside the table for the section you choose. Since + it is going inside an existing table, it must be in this form: + ------cut here------- +
+ | YOUR OPTIONS NAME |
+ | YOUR DESCRIPTION |