projects / squirrelmail.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Note about db prefs not currently working on postgres
[squirrelmail.git] / doc / plugin.txt
diff --git a/doc/plugin.txt b/doc/plugin.txt
index ccdff59da7bd13b52921e82af73e61b37e7a4246..f5d32035e45b2a22c309fe20c2ab55b1d2c6639b 100644 (file)
--- 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).
+
+FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
+Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
 
 
-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.
 
 
-Until the functionality and code is more stable, be prepared for
-plugins to suddenly stop working.
+A FEW NOTES ON THE PLUGIN ARCHITECTURE
+======================================
 
 
-Functionality like password changing, displaying ads and calendars
-should be possible to add as plugins.
+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
 
 
 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
 
 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
 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:
 
 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
 
 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;
 
 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
 }
 
 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.
 
 
 including any of the standard SquirrelMail files.
 
 
@@ -113,6 +118,7 @@ List of hooks
   & options_identities_table      src/options_identities.php
   & options_identities_buttons    src/options_identities.php
   logout                          src/signout.php
   & 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
   login_before                    src/webmail.php
   login_verified                  src/webmail.php
   loading_prefs                   src/load_prefs.php
@@ -120,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
   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
   right_main_after_header         src/right_main.php
   right_main_bottom               src/right_main.php
   login_top                       src/login.php
@@ -140,7 +147,6 @@ List of hooks
   addressbook_bottom              src/addressbook.php
   ^ attachment $type0/$type1      functions/mime.php (see note on attachments)
    
   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
 (*) Options
 -----------
 There are two ways to do options for your plugin.  First, you can incorporate it
@@ -178,9 +184,9 @@ 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
 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
+    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
     page.  This should output HTML that looks like this.  Make sure to read
-    the section on outputting your own pages.
+    the section on outputing your own pages.
 
     -----cut here-----  
       function my_plugin_name_my_function() {
 
     -----cut here-----  
       function my_plugin_name_my_function() {
@@ -188,12 +194,12 @@ three hooks you will need to use.
          ?>
          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
             <tr>
          ?>
          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
             <tr>
-               <td bgcolor="<? echo $color[9] ?>">
+               <td bgcolor="<?php echo $color[9] ?>">
                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
                </td>
             </tr>
             <tr>
                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
                </td>
             </tr>
             <tr>
-               <td bgcolor="<? echo $color[0] ?>">
+               <td bgcolor="<?php echo $color[0] ?>">
                   YOUR DESCRIPTION
                </td>
             </tr>
                   YOUR DESCRIPTION
                </td>
             </tr>
@@ -270,6 +276,10 @@ 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';
     
   $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
 -------------------------
 
 Outputting Your Own Pages
 -------------------------
@@ -292,7 +302,7 @@ of your PHP script should look very similar to this:
     
 The validate.php script will include internationalization support,
 config.php variables, strings.php functions, and also authenticate that the
     
 The validate.php script will include internationalization support,
 config.php variables, strings.php functions, and also authenticate that the
-user is truly logged in.  Validate.php also calls stripslashes() on incoming
+user is truly logged in.  validate.php also calls stripslashes() on incoming
 data (if gpc_magic_quotes() is on).  You should never need to worry about
 that stuff again.  As a warning, this has only really been ironed out in
 1.1.1.  If you create/modify a plugin to follow these rules, you must
 data (if gpc_magic_quotes() is on).  You should never need to worry about
 that stuff again.  As a warning, this has only really been ironed out in
 1.1.1.  If you create/modify a plugin to follow these rules, you must
Unnamed repository; edit this file 'description' to name the repository.