X-Git-Url: https://vcs.fsf.org/?p=squirrelmail.git;a=blobdiff_plain;f=doc%2Fplugin.txt;h=dbd6ab52f9601d86d827f947301d78902980335f;hp=99e5998d4cd4a783657f0a70e8b75fbbca88ee5a;hb=97445d7d882729c7b222b4f35395b61e31d5049e;hpb=6b6381715922c24dc8664cc62464096814d6a291
diff --git a/doc/plugin.txt b/doc/plugin.txt
index 99e5998d..dbd6ab52 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
+ 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-------
+
+ |
+ OPTION_NAME
+ |
+
+ OPTION_INPUT
+ |
+
+ ------cut here-------
+
+2. options_YOUCHOOSE_save
+ This is the code that saves your preferences into the users' preference
+ file. For an example of how to do this, see src/options.php.
+
+
+Second: Create your own section
+-------------------------------
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:
+ page. This should output HTML that looks like this. Make sure to read
+ the section on outputting your own pages.
-----cut here-----
- function my_function() {
+ function my_plugin_name_my_function() {
global $color
?>
- |
+ |
YOUR OPTIONS NAME
|
- |
+ |
YOUR DESCRIPTION
|
@@ -135,3 +223,91 @@ three hooks you will need to use.
You should put the code in here that loads your preferences back
into usable variables. Examples of this can be found in the file
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
+instance, a .zip file hook is "attachment application/x-zip". The hook should
+probably show a link to do a specific action, such as "Verify" or "View" for a
+.zip file.
+
+This is a breakdown of the data passed in the array to the hook that is called:
+
+ [0] = Hook's name ('attachment text/plain')
+ [1] = Array of links of actions (more below) (Alterable)
+ [2] = Used for returning to mail message (startMessage)
+ [3] = Used for finding message to display (id)
+ [4] = Mailbox name, urlencode()'d (urlMailbox)
+ [5] = Entity ID inside mail message (ent)
+ [6] = Default URL to go to when filename is clicked on (Alterable)
+ [7] = Filename that is displayed for the attachment
+ [8] = Sent if message was found from a search (where)
+ [9] = Sent if message was found from a search (what)
+
+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';
+
+
+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:
+
+