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 Hook Data Passed
  78 ----------------
  79 Hooks, when executed, are called with one parameter, an array of data
  80 that is passed to the hook.  The first element in the array is the name
  81 of the hook that is being called.  Any other elements in the array are
  82 dependant on the type of hook that is being called.
  83
  84 Some of the information in the array may be changed.  By default, the
  85 plugins should never change data unless it is documented otherwise.
  86
  87
  88 List of hooks
  89 -------------
  90   generic_header                  functions/page_header.php
  91   menuline                        functions/page_header.php
  92   compose_button_row              src/compose.php
  93   compose_bottom                  src/compose.php
  94   compose_form                    src/compose.php
  95   compose_send                    src/compose.php
  96   left_main_before                src/left_main.php
  97   left_main_after                 src/left_main.php
  98   * options_save                  src/options.php  (see note on options)
  99   * options_link_and_description  src/options.php  (see note on options)
 100   * options_highlight_bottom      src/options_highlight.php
 101   * options_personal_bottom       src/options_personal.php
 102   * options_personal_inside       src/options_personal.php
 103   * options_personal_save         src/options_personal.php
 104   * options_display_bottom        src/options_display.php
 105   * options_display_inside        src/options_display.php
 106   * options_display_save          src/options_display.php
 107   * options_folders_bottom        src/options_folders.php
 108   * options_folders_inside        src/options_folders.php
 109   * options_folders_save          src/options_folders.php
 110   logout                          src/signout.php
 111   login_before                    src/webmail.php
 112   login_verified                  src/webmail.php
 113   loading_prefs                   src/load_prefs.php
 114   mailbox_index_before            functions/mailbox_display.php
 115   mailbox_index_after             functions/mailbox_display.php
 116   mailbox_form_before             functions/mailbox_display.php
 117   subject_link                    functions/mailbox_display.php
 118   right_main_after_header         src/right_main.php
 119   right_main_bottom               src/right_main.php
 120   login_top                       src/login.php
 121   login_bottom                    src/login.php
 122   html_top                        src/read_body.php
 123   read_body_top                   src/read_body.php
 124   read_body_bottom                src/read_body.php
 125   html_bottom                     src/read_body.php
 126   read_body_header                src/read_body.php
 127   read_body_header_right          src/read_body.php
 128   search_before_form              src/search.php
 129   search_after_form               src/search.php
 130   search_bottom                   src/search.php
 131   help_top                        src/help.php
 132   help_bottom                     src/help.php
 133   help_chapter                    src/help.php
 134   addrbook_html_search_below      src/addrbook_search_html.php
 135   addressbook_bottom              src/addressbook.php
 136   ^ attachment $type0/$type1      functions/mime.php (see note on attachments)
 137
 138
 139 (*) Options
 140 -----------
 141 There are two ways to do options for your plugin.  First, you can incorporate it
 142 into an existing section of the preferences (Display, Personal, or Folders).
 143 The second way, you create your own section that they can choose from and it
 144 displays its own range of options.
 145
 146
 147 First:  Integrating into existing options
 148 -----------------------------------------
 149 There are two hooks you need to use for this one:
 150
 151 1.  options_YOUCHOOSE_inside
 152     This is the code that goes inside the table for the section you choose.  Since
 153     it is going inside an existing table, it must be in this form:
 154     ------cut here-------
 155       <tr>
 156          <td>
 157             OPTION_NAME
 158          </td>
 159          <td>
 160             OPTION_INPUT
 161          </td>
 162       </tr>
 163     ------cut here-------
 164
 165 2.  options_YOUCHOOSE_save
 166     This is the code that saves your preferences into the users' preference
 167     file.  For an example of how to do this, see src/options.php.
 168
 169
 170 Second:  Create your own section
 171 -------------------------------
 172 It is possible to create your own options sections with plugins.  There are
 173 three hooks you will need to use.
 174
 175 1.  options_link_and_description
 176     This creates the link and has a description that are shown on the options
 177     page.  This should output HTML that looks like this.  Make sure to read
 178     the section on outputting your own pages.
 179
 180     -----cut here-----
 181       function my_plugin_name_my_function() {
 182          global $color
 183          ?>
 184          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
 185             <tr>
 186                <td bgcolor="<? echo $color[9] ?>">
 187                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
 188                </td>
 189             </tr>
 190             <tr>
 191                <td bgcolor="<? echo $color[0] ?>">
 192                   YOUR DESCRIPTION
 193                </td>
 194             </tr>
 195          </table>
 196          <?php
 197       }
 198     -----cut here-----
 199
 200 2.  options_save
 201     Here is the code that you need to do to save your options in the
 202     preference files or manipulate whatever data you are trying to change
 203     through the options section.  You can look at options.php for details
 204     on how this is to be done.
 205
 206 3.  loading_prefs (optional)
 207     If you are wanting to save preferences to the preference files, then
 208     you need to do this step as well.  Otherwise if you are manipulating
 209     other data, ignore this step.
 210
 211     You should put the code in here that loads your preferences back
 212     into usable variables.  Examples of this can be found in the file
 213     src/load_prefs.php
 214
 215
 216 (^) Attachment Hooks
 217 --------------------
 218 When a message has attachments, this hook is called with the MIME types.  For
 219 instance, a .zip file hook is "attachment application/x-zip".  The hook should
 220 probably show a link to do a specific action, such as "Verify" or "View" for a
 221 .zip file.
 222
 223 This is a breakdown of the data passed in the array to the hook that is called:
 224
 225   [0] = Hook's name ('attachment text/plain')
 226   [1] = Array of links of actions (more below) (Alterable)
 227   [2] = Used for returning to mail message (startMessage)
 228   [3] = Used for finding message to display (id)
 229   [4] = Mailbox name, urlencode()'d (urlMailbox)
 230   [5] = Entity ID inside mail message (ent)
 231   [6] = Default URL to go to when filename is clicked on (Alterable)
 232   [7] = Filename that is displayed for the attachment
 233   [8] = Sent if message was found from a search (where)
 234   [9] = Sent if message was found from a search (what)
 235
 236 To set up links for actions, you assign them like this:
 237
 238   $Args[1]['your_plugin_name']['href'] = 'URL to link to';
 239   $Args[1]['your_plugin_name']['text'] = 'What to display';
 240
 241
 242 Outputting Your Own Pages
 243 -------------------------
 244
 245 Often, when you want to provide your own customized options screen or create
 246 another web page instead of just using standard hooks, you will be creating
 247 your own .php files.  An example of this is the attachment_common plugin's
 248 image.php file.
 249
 250 To make sure that security is maintained and standards are followed, the top
 251 of your PHP script should look very similar to this:
 252
 253   <?PHP
 254     /* This is my php file.
 255      * description goes here.
 256      */
 257
 258     chdir('..');
 259     include('../src/validate.php');
 260
 261 The validate.php script will include internationalization support,
 262 config.php variables, strings.php functions, and also authenticate that the
 263 user is truly logged in.  Validate.php also calls stripslashes() on incoming
 264 data (if gpc_magic_quotes() is on).  You should never need to worry about
 265 that stuff again.  As a warning, this has only really been ironed out in
 266 1.1.1.  If you create/modify a plugin to follow these rules, you must
 267 mention that it requires SquirrelMail 1.1.1 or later.
 268
 269 After that, if you need further functions, just use
 270
 271   include('../functions/filename.php');
 272
 273 in your script.  Since 1.0.5, it was no longer necessary (nor recommended)
 274 to use the "if (! isset($filename_php))" syntax.