squirrelmail/doc/plugin.txt

$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


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
--------

The idea is to be able to run random code at given places in the
SquirrelMail code. This random code should then be able to do whatever
needed to enhance the functionality of SquirrelMail. The places where
code can be executed are called "hooks".

There are some limitations in what these hooks can do. It is difficult
to use them to change the layout and to change functionality that
already is in SquirrelMail.

Some way for the plugins to interact with the help subsystem and
translations will be provided.


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').

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
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';

When a plugin is registered the file plugins/plugin_name/setup.php is
included and the function squirrelmail_plugin_init_plugin_name is
called with no parameters.


Writing plugins
---------------

A plugin must consist of at least a file called setup.php. All other
files the plugin consist of should also be in the plugin directory.

The function squirrelmail_plugin_init_plugin_name is called to
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';
}

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
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
  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
  read_body_after_from            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-------
      <tr>
         <td>
            OPTION_NAME
         </td>
         <td>
            OPTION_INPUT
         </td>
      </tr>   
    ------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 is shown on the options
    page.  This should output HTML that looks like this.  Make sure to read
    the section on outputing your own pages.

    -----cut here-----  
      function my_plugin_name_my_function() {
         global $color
         ?>
         <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
            <tr>
               <td bgcolor="<?php echo $color[9] ?>">
                  <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
               </td>
            </tr>
            <tr>
               <td bgcolor="<?php echo $color[0] ?>">
                  YOUR DESCRIPTION
               </td>
            </tr>
         </table>
         <?php
      }
    -----cut here-----  

2.  options_save
    Here is the code that you need to do to save your options in the 
    preference files or manipulate whatever data you are trying to change
    through the options section.  You can look at options.php for details 
    on how this is to be done.

3.  loading_prefs (optional)
    If you are wanting to save preferences to the preference files, then
    you need to do this step as well.  Otherwise if you are manipulating
    other data, ignore this step.

    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   <tr<?PHP echo $Info[1]?>>   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';
    
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
-------------------------

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:

  <?PHP
    /* This is my php file.
     * description goes here.
     */
     
    chdir('..');
    include('../src/validate.php');
    
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
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
mention that it requires SquirrelMail 1.1.1 or later.

After that, if you need further functions, just use

  include('../functions/filename.php');
  
in your script.  Since 1.0.5, it was no longer necessary (nor recommended)
to use the "if (! isset($filename_php))" syntax.