47f31f9aa080561fb6b9c5c356e5ded70532010b
[squirrelmail.git] / 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_personal_inside       src/options_personal.php
90   * options_personal_save         src/options_personal.php
91   * options_display_bottom        src/options_display.php
92   * options_display_inside        src/options_display.php
93   * options_display_save          src/options_display.php
94   * options_folders_bottom        src/options_folders.php
95   * options_folders_inside        src/options_folders.php
96   * options_folders_save          src/options_folders.php
97   logout                          src/signout.php
98   login_before                    src/webmail.php
99   login_verified                  src/webmail.php
100   loading_prefs                   src/load_prefs.php
101   mailbox_index_before            functions/mailbox_display.php
102   mailbox_index_after             functions/mailbox_display.php
103   mailbox_form_before             functions/mailbox_display.php
104   right_main_after_header         src/right_main.php
105   right_main_bottom               src/right_main.php
106   login_top                       src/login.php
107   login_bottom                    src/login.php
108   read_body_top                   src/read_body.php
109   read_body_bottom                src/read_body.php
110   search_before_form              src/search.php
111   search_after_form               src/search.php
112   search_bottom                   src/search.php
113   help_top                        src/help.php
114   help_bottom                     src/help.php
115   help_chapter                    src/help.php
116   addrbook_html_search_below      src/addrbook_search_html.php
117   addressbook_bottom              src/addressbook.php
118   ^ attachment $type0/$type1      functions/mime.php
119    
120 (*) Options
121 -----------
122 There are two ways to do options for your plugin.  First, you can incorporate it
123 into an existing section of the preferences (Display, Personal, or Folders).
124 The second way, you create your own section that they can choose from and it 
125 displays its own range of options.
126
127
128 (^) Attachment Hooks
129 --------------------
130 When a message has attachments, this hook is called with the MIME types.  For
131 instance, a .zip file hook is "attachment application/x-zip".  The hook should
132 probably show a link to do a specific action, such as "Verify" or "View" for a
133 .zip file.
134
135
136 First:  Integrating into existing options
137 -----------------------------------------
138 There are two hooks you need to use for this one:
139
140 1.  options_YOUCHOOSE_inside
141     This is the code that goes inside the table for the section you choose.  Since
142     it is going inside an existing table, it must be in this form:
143     ------cut here-------
144       <tr>
145          <td>
146             OPTION_NAME
147          </td>
148          <td>
149             OPTION_INPUT
150          </td>
151       </tr>   
152     ------cut here-------
153
154 2.  options_YOUCHOOSE_save
155     This is the code that saves your preferences into the users' preference 
156     file.  For an example of how to do this, see src/options.php.
157
158     
159 Second:  Create your own section
160 -------------------------------
161 It is possible to create your own options sections with plugins.  There are
162 three hooks you will need to use.
163
164 1.  options_link_and_description
165     This creates the link and has a description that are shown on the options
166     page.  This should output HTML that looks like this:
167
168     -----cut here-----  
169       function my_function() {
170          global $color
171          ?>
172          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
173             <tr>
174                <td bgcolor="<? echo $color[9] ?>">
175                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
176                </td>
177             </tr>
178             <tr>
179                <td bgcolor="<? echo $color[0] ?>">
180                   YOUR DESCRIPTION
181                </td>
182             </tr>
183          </table>
184          <?php
185       }
186     -----cut here-----  
187
188 2.  options_save
189     Here is the code that you need to do to save your options in the 
190     preference files or manipulate whatever data you are trying to change
191     through the options section.  You can look at options.php for details 
192     on how this is to be done.
193
194 3.  loading_prefs (optional)
195     If you are wanting to save preferences to the preference files, then
196     you need to do this step as well.  Otherwise if you are manipulating
197     other data, ignore this step.
198
199     You should put the code in here that loads your preferences back
200     into usable variables.  Examples of this can be found in the file
201     src/load_prefs.php