doc/plugin.txt

   1 $Id$
   2
   3 It is best if you check out the SquirrelMail development FAQ for more
   4 information.  This document may be obsoleted at some point in the future (or
   5 maybe we'll write a script to get the wiki contents and dump them in here
   6 automatically).
   7
   8 FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
   9 Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
  10
  11
  12 A FEW NOTES ON THE PLUGIN ARCHITECTURE
  13 ======================================
  14
  15 The plugin architecture of SquirrelMail is designed to make it possible to
  16 add new features without having to patch SquirrelMail itself. Functionality
  17 like password changing, displaying ads and calendars should be possible to
  18 add as plugins.
  19
  20
  21 The idea
  22 --------
  23
  24 The idea is to be able to run random code at given places in the
  25 SquirrelMail code. This random code should then be able to do whatever
  26 needed to enhance the functionality of SquirrelMail. The places where
  27 code can be executed are called "hooks".
  28
  29 There are some limitations in what these hooks can do. It is difficult
  30 to use them to change the layout and to change functionality that
  31 already is in SquirrelMail.
  32
  33 Some way for the plugins to interact with the help subsystem and
  34 translations will be provided.
  35
  36
  37 The implementation
  38 ------------------
  39
  40 In the main SquirrelMail files the file functions/plugin.php. In
  41 places where hooks are made available they are executed by calling the
  42 function do_hook('hookname').
  43
  44 The do_hook traverses the array $squirrelmail_plugin_hooks['hookname']
  45 and executes all the functions that are named in that array.
  46
  47 A plugin must reside in a subdirectory in the plugins/ directory. The
  48 name of the subdirectory is considered the name of the plugin.
  49
  50 To start using a plugin, its name must be added to the $plugins array
  51 in config.php like this:
  52
  53   $plugins[0] = 'plugin_name';
  54
  55 When a plugin is registered the file plugins/plugin_name/setup.php is
  56 included and the function squirrelmail_plugin_init_plugin_name is
  57 called with no parameters.
  58
  59
  60 Writing plugins
  61 ---------------
  62
  63 A plugin must consist of at least a file called setup.php. All other
  64 files the plugin consist of should also be in the plugin directory.
  65
  66 The function squirrelmail_plugin_init_plugin_name is called to
  67 initalize a plugin. This function could look something like this:
  68
  69 function squirrelmail_plugin_init_demo () {
  70   global $squirrelmail_plugin_hooks;
  71
  72   $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header';
  73   $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline';
  74 }
  75
  76 Note that the SquirrelMail files assume that all other SquirrelMail
  77 files are available as ../directory/file. This means that if some file
  78 in the plugin directory is requested, it must do a chdir('..') before
  79 including any of the standard SquirrelMail files.
  80
  81
  82 Hook Data Passed
  83 ----------------
  84 Hooks, when executed, are called with one parameter, an array of data
  85 that is passed to the hook.  The first element in the array is the name
  86 of the hook that is being called.  Any other elements in the array are
  87 dependant on the type of hook that is being called.
  88
  89 Some of the information in the array may be changed.  By default, the
  90 plugins should never change data unless it is documented otherwise.
  91
  92
  93 List of hooks
  94 -------------
  95   generic_header                  functions/page_header.php
  96   menuline                        functions/page_header.php
  97   compose_button_row              src/compose.php
  98   compose_bottom                  src/compose.php
  99   compose_form                    src/compose.php
 100   compose_send                    src/compose.php
 101   left_main_before                src/left_main.php
 102   left_main_after                 src/left_main.php
 103   * options_save                  src/options.php  (see note on options)
 104   * options_link_and_description  src/options.php  (see note on options)
 105   * options_highlight_bottom      src/options_highlight.php
 106   * options_personal_bottom       src/options_personal.php
 107   * options_personal_inside       src/options_personal.php
 108   * options_personal_save         src/options_personal.php
 109   * options_display_bottom        src/options_display.php
 110   * options_display_inside        src/options_display.php
 111   * options_display_save          src/options_display.php
 112   * options_folders_bottom        src/options_folders.php
 113   * options_folders_inside        src/options_folders.php
 114   * options_folders_save          src/options_folders.php
 115   & options_identities_process    src/options_identities.php
 116   & options_identities_top        src/options_identities.php
 117   & options_identities_renumber   src/options_identities.php (multiple places)
 118   & options_identities_table      src/options_identities.php
 119   & options_identities_buttons    src/options_identities.php
 120   logout                          src/signout.php
 121   logout_above_text               src/signout.php
 122   login_before                    src/webmail.php
 123   login_verified                  src/webmail.php
 124   loading_prefs                   src/load_prefs.php
 125   mailbox_index_before            functions/mailbox_display.php
 126   mailbox_index_after             functions/mailbox_display.php
 127   mailbox_form_before             functions/mailbox_display.php
 128   subject_link                    functions/mailbox_display.php
 129   motd                            src/right_main.php
 130   right_main_after_header         src/right_main.php
 131   right_main_bottom               src/right_main.php
 132   login_top                       src/login.php
 133   login_bottom                    src/login.php
 134   html_top                        src/read_body.php
 135   read_body_top                   src/read_body.php
 136   read_body_bottom                src/read_body.php
 137   html_bottom                     src/read_body.php
 138   read_body_header                src/read_body.php
 139   read_body_header_right          src/read_body.php
 140   search_before_form              src/search.php
 141   search_after_form               src/search.php
 142   search_bottom                   src/search.php
 143   help_top                        src/help.php
 144   help_bottom                     src/help.php
 145   help_chapter                    src/help.php
 146   addrbook_html_search_below      src/addrbook_search_html.php
 147   addressbook_bottom              src/addressbook.php
 148   ^ attachment $type0/$type1      functions/mime.php (see note on attachments)
 149
 150 (*) Options
 151 -----------
 152 There are two ways to do options for your plugin.  First, you can incorporate it
 153 into an existing section of the preferences (Display, Personal, or Folders).
 154 The second way, you create your own section that they can choose from and it
 155 displays its own range of options.
 156
 157
 158 First:  Integrating into existing options
 159 -----------------------------------------
 160 There are two hooks you need to use for this one:
 161
 162 1.  options_YOUCHOOSE_inside
 163     This is the code that goes inside the table for the section you choose.  Since
 164     it is going inside an existing table, it must be in this form:
 165     ------cut here-------
 166       <tr>
 167          <td>
 168             OPTION_NAME
 169          </td>
 170          <td>
 171             OPTION_INPUT
 172          </td>
 173       </tr>
 174     ------cut here-------
 175
 176 2.  options_YOUCHOOSE_save
 177     This is the code that saves your preferences into the users' preference
 178     file.  For an example of how to do this, see src/options.php.
 179
 180
 181 Second:  Create your own section
 182 -------------------------------
 183 It is possible to create your own options sections with plugins.  There are
 184 three hooks you will need to use.
 185
 186 1.  options_link_and_description
 187     This creates the link and has a description that is shown on the options
 188     page.  This should output HTML that looks like this.  Make sure to read
 189     the section on outputing your own pages.
 190
 191     -----cut here-----
 192       function my_plugin_name_my_function() {
 193          global $color
 194          ?>
 195          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
 196             <tr>
 197                <td bgcolor="<?php echo $color[9] ?>">
 198                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
 199                </td>
 200             </tr>
 201             <tr>
 202                <td bgcolor="<?php echo $color[0] ?>">
 203                   YOUR DESCRIPTION
 204                </td>
 205             </tr>
 206          </table>
 207          <?php
 208       }
 209     -----cut here-----
 210
 211 2.  options_save
 212     Here is the code that you need to do to save your options in the
 213     preference files or manipulate whatever data you are trying to change
 214     through the options section.  You can look at options.php for details
 215     on how this is to be done.
 216
 217 3.  loading_prefs (optional)
 218     If you are wanting to save preferences to the preference files, then
 219     you need to do this step as well.  Otherwise if you are manipulating
 220     other data, ignore this step.
 221
 222     You should put the code in here that loads your preferences back
 223     into usable variables.  Examples of this can be found in the file
 224     src/load_prefs.php
 225
 226
 227 (&) Identity Hooks
 228 ------------------
 229 Some hooks are passed special information in the array of arguments.  See
 230 the SpamCop plugin for how to use them.
 231
 232 options_identities_process
 233    [0] = Hook's name
 234    [1] = Should I run the SaveUpdateFunction() (alterable)
 235
 236 options_identities_renumber
 237    [0] = Hook's name
 238    [1] = Renumber it from ('default' or 1 through # idents - 1)
 239    [2] = Renumber it to (same thing)
 240
 241 options_identities_table
 242    [0] = Hook's name
 243    [1] = Color of table (use it like   <tr<?PHP echo $Info[1]?>>   in your
 244          plugin)
 245    [2] = Is this an empty section?
 246    [3] = What is the 'post' value?
 247
 248 options_identities_buttons
 249    [0] = Hook's name
 250    [1] = Is this an empty section (the one at the end of the list)?
 251    [2] = What is the 'post' value?
 252
 253
 254 (^) Attachment Hooks
 255 --------------------
 256 When a message has attachments, this hook is called with the MIME types.  For
 257 instance, a .zip file hook is "attachment application/x-zip".  The hook should
 258 probably show a link to do a specific action, such as "Verify" or "View" for a
 259 .zip file.
 260
 261 This is a breakdown of the data passed in the array to the hook that is called:
 262
 263   [0] = Hook's name ('attachment text/plain')
 264   [1] = Array of links of actions (more below) (Alterable)
 265   [2] = Used for returning to mail message (startMessage)
 266   [3] = Used for finding message to display (id)
 267   [4] = Mailbox name, urlencode()'d (urlMailbox)
 268   [5] = Entity ID inside mail message (ent)
 269   [6] = Default URL to go to when filename is clicked on (Alterable)
 270   [7] = Filename that is displayed for the attachment
 271   [8] = Sent if message was found from a search (where)
 272   [9] = Sent if message was found from a search (what)
 273
 274 To set up links for actions, you assign them like this:
 275
 276   $Args[1]['your_plugin_name']['href'] = 'URL to link to';
 277   $Args[1]['your_plugin_name']['text'] = 'What to display';
 278
 279 It's also possible to specify a hook as "attachment type0/*",
 280 for example "attachment text/*". This hook will be executed whenever there's
 281 no more specific rule available for that type.
 282
 283
 284 Outputting Your Own Pages
 285 -------------------------
 286
 287 Often, when you want to provide your own customized options screen or create
 288 another web page instead of just using standard hooks, you will be creating
 289 your own .php files.  An example of this is the attachment_common plugin's
 290 image.php file.
 291
 292 To make sure that security is maintained and standards are followed, the top
 293 of your PHP script should look very similar to this:
 294
 295   <?PHP
 296     /* This is my php file.
 297      * description goes here.
 298      */
 299
 300     chdir('..');
 301     include('../src/validate.php');
 302
 303 The validate.php script will include internationalization support,
 304 config.php variables, strings.php functions, and also authenticate that the
 305 user is truly logged in.  validate.php also calls stripslashes() on incoming
 306 data (if gpc_magic_quotes() is on).  You should never need to worry about
 307 that stuff again.  As a warning, this has only really been ironed out in
 308 1.1.1.  If you create/modify a plugin to follow these rules, you must
 309 mention that it requires SquirrelMail 1.1.1 or later.
 310
 311 After that, if you need further functions, just use
 312
 313   include('../functions/filename.php');
 314
 315 in your script.  Since 1.0.5, it was no longer necessary (nor recommended)
 316 to use the "if (! isset($filename_php))" syntax.