doc/plugin.txt

   1 A FEW NOTES ON THE PLUGIN ARCHITECTURE
   2 ======================================
   3
   4 The plugin architecture of SquirrelMail is designed to make it
   5 possible to add new features without having to patch SquirrelMail
   6 itself. At the moment the plugin part of SquirrelMail should be
   7 considered "alpha" or "beta" quality code.
   8
   9 Until the functionality and code is more stable, be prepared for
  10 plugins to suddenly stop working.
  11
  12 Functionality like password changing, displaying ads and calendars
  13 should be possible to add as plugins.
  14
  15
  16 The idea
  17 --------
  18
  19 The idea is to be able to run random code at given places in the
  20 SquirrelMail code. This random code should then be able to do whatever
  21 needed to enhance the functionality of SquirrelMail. The places where
  22 code can be executed are called "hooks".
  23
  24 There are some limitations in what these hooks can do. It is difficult
  25 to use them to change the layout and to change functionality that
  26 already is in SquirrelMail.
  27
  28 Some way for the plugins to interact with the help subsystem and
  29 translations will be provided.
  30
  31
  32 The implementation
  33 ------------------
  34
  35 In the main SquirrelMail files the file functions/plugin.php. In
  36 places where hooks are made available they are executed by calling the
  37 function do_hook("hookname").
  38
  39 The do_hook traverses the array $squirrelmail_plugin_hooks["hookname"]
  40 and executes all the functions that are named in that array.
  41
  42 A plugin must reside in a subdirectory in the plugins/ directory. The
  43 name of the subdirectory is considered the name of the plugin.
  44
  45 To start using a plugin, its name must be added to the $plugins array
  46 in config.php like this:
  47
  48   $plugins[0] = "plugin_name";
  49
  50 When a plugin is registered the file plugins/plugin_name/setup.php is
  51 included and the function squirrelmail_plugin_init_plugin_name is
  52 called with no parameters.
  53
  54
  55 Writing plugins
  56 ---------------
  57
  58 A plugin must consist of at least a file called setup.php. All other
  59 files the plugin consist of should also be in the plugin directory.
  60
  61 The function squirrelmail_plugin_init_plugin_name is called to
  62 initalize a plugin. This function could look something like this:
  63
  64 function squirrelmail_plugin_init_demo () {
  65   global $squirrelmail_plugin_hooks;
  66
  67   $squirrelmail_plugin_hooks["generic_header"]["demo"] = "plugin_demo_header";
  68   $squirrelmail_plugin_hooks["menuline"]["demo"] = "plugin_demo_menuline";
  69 }
  70
  71 Note that the SquirrelMail files assume that all other SquirrelMail
  72 files are available as ../directory/file. This means that if some file
  73 in the plugin directory is requested, it must do a chdir("..") before
  74 including any of the standard SquirrelMail files.
  75
  76
  77 List of hooks
  78 -------------
  79   generic_header                 functions/page_header.php
  80   menuline                       functions/page_header.php
  81   compose_button_row             src/compose.php
  82   compose_bottom                 src/compose.php
  83   left_main_before               src/left_main.php
  84   left_main_after                src/left_main.php
  85   options_save                   src/options.php  (see note on options)
  86   options_link_and_description   src/options.php  (see note on options)
  87   options_highlight_bottom       src/options_highlight.php
  88   options_personal_bottom        src/options_personal.php
  89   options_display_bottom         src/options_display.php
  90   options_folders_bottom         src/options_folders.php
  91   logout                         src/signout.php
  92   login_before                   src/webmail.php
  93   login_verified                 src/webmail.php
  94   loading_prefs                  src/load_prefs.php
  95   mailbox_index_before           functions/mailbox_display.php
  96   mailbox_index_after            functions/mailbox_display.php
  97   right_main_after_header        src/right_main.php
  98   right_main_bottom              src/right_main.php
  99   login_top                      src/login.php
 100   login_bottom                   src/login.php
 101   read_body_top                  src/read_body.php
 102   read_body_bottom               src/read_body.php
 103   search_before_form             src/search.php
 104   search_after_form              src/search.php
 105   search_bottom                  src/search.php
 106   help_top                       src/help.php
 107   help_bottom                    src/help.php
 108   help_chapter                   src/help.php
 109   abook_html_search_below        src/addrbook_search_html.php
 110
 111 Options
 112 -------
 113
 114 It is possible to create your own options sections with plugins.  There are
 115 three hooks you will need to use.
 116
 117 1.  options_link_and_description
 118     This creates the link and has a description that are shown on the options
 119     page.  This should output HTML that looks like this:
 120
 121     -----cut here-----
 122       function my_function() {
 123          global $color
 124          ?>
 125          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
 126             <tr>
 127                <td bgcolor="<? echo $color[9] ?>">
 128                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
 129                </td>
 130             </tr>
 131             <tr>
 132                <td bgcolor="<? echo $color[0] ?>">
 133                   YOUR DESCRIPTION
 134                </td>
 135             </tr>
 136          </table>
 137          <?php
 138       }
 139     -----cut here-----
 140
 141 2.  options_save
 142     Here is the code that you need to do to save your options in the
 143     preference files or manipulate whatever data you are trying to change
 144     through the options section.  You can look at options.php for details
 145     on how this is to be done.
 146
 147 3.  loading_prefs (optional)
 148     If you are wanting to save preferences to the preference files, then
 149     you need to do this step as well.  Otherwise if you are manipulating
 150     other data, ignore this step.
 151
 152     You should put the code in here that loads your preferences back
 153     into usable variables.  Examples of this can be found in the file
 154     src/load_prefs.php