Forgot one {
[squirrelmail.git] / 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    
151 (*) Options
152 -----------
153 There are two ways to do options for your plugin.  First, you can incorporate it
154 into an existing section of the preferences (Display, Personal, or Folders).
155 The second way, you create your own section that they can choose from and it 
156 displays its own range of options.
157
158
159 First:  Integrating into existing options
160 -----------------------------------------
161 There are two hooks you need to use for this one:
162
163 1.  options_YOUCHOOSE_inside
164     This is the code that goes inside the table for the section you choose.  Since
165     it is going inside an existing table, it must be in this form:
166     ------cut here-------
167       <tr>
168          <td>
169             OPTION_NAME
170          </td>
171          <td>
172             OPTION_INPUT
173          </td>
174       </tr>   
175     ------cut here-------
176
177 2.  options_YOUCHOOSE_save
178     This is the code that saves your preferences into the users' preference 
179     file.  For an example of how to do this, see src/options.php.
180
181     
182 Second:  Create your own section
183 -------------------------------
184 It is possible to create your own options sections with plugins.  There are
185 three hooks you will need to use.
186
187 1.  options_link_and_description
188     This creates the link and has a description that are shown on the options
189     page.  This should output HTML that looks like this.  Make sure to read
190     the section on outputting your own pages.
191
192     -----cut here-----  
193       function my_plugin_name_my_function() {
194          global $color
195          ?>
196          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
197             <tr>
198                <td bgcolor="<?php echo $color[9] ?>">
199                   <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
200                </td>
201             </tr>
202             <tr>
203                <td bgcolor="<?php echo $color[0] ?>">
204                   YOUR DESCRIPTION
205                </td>
206             </tr>
207          </table>
208          <?php
209       }
210     -----cut here-----  
211
212 2.  options_save
213     Here is the code that you need to do to save your options in the 
214     preference files or manipulate whatever data you are trying to change
215     through the options section.  You can look at options.php for details 
216     on how this is to be done.
217
218 3.  loading_prefs (optional)
219     If you are wanting to save preferences to the preference files, then
220     you need to do this step as well.  Otherwise if you are manipulating
221     other data, ignore this step.
222
223     You should put the code in here that loads your preferences back
224     into usable variables.  Examples of this can be found in the file
225     src/load_prefs.php
226
227
228 (&) Identity Hooks
229 ------------------
230 Some hooks are passed special information in the array of arguments.  See
231 the SpamCop plugin for how to use them.
232
233 options_identities_process
234    [0] = Hook's name
235    [1] = Should I run the SaveUpdateFunction() (alterable)
236
237 options_identities_renumber
238    [0] = Hook's name
239    [1] = Renumber it from ('default' or 1 through # idents - 1)
240    [2] = Renumber it to (same thing)
241    
242 options_identities_table
243    [0] = Hook's name
244    [1] = Color of table (use it like   <tr<?PHP echo $Info[1]?>>   in your
245          plugin)
246    [2] = Is this an empty section?
247    [3] = What is the 'post' value?
248   
249 options_identities_buttons
250    [0] = Hook's name
251    [1] = Is this an empty section (the one at the end of the list)?
252    [2] = What is the 'post' value?
253
254
255 (^) Attachment Hooks
256 --------------------
257 When a message has attachments, this hook is called with the MIME types.  For
258 instance, a .zip file hook is "attachment application/x-zip".  The hook should
259 probably show a link to do a specific action, such as "Verify" or "View" for a
260 .zip file.
261
262 This is a breakdown of the data passed in the array to the hook that is called:
263
264   [0] = Hook's name ('attachment text/plain')
265   [1] = Array of links of actions (more below) (Alterable)
266   [2] = Used for returning to mail message (startMessage)
267   [3] = Used for finding message to display (id)
268   [4] = Mailbox name, urlencode()'d (urlMailbox)
269   [5] = Entity ID inside mail message (ent)
270   [6] = Default URL to go to when filename is clicked on (Alterable)
271   [7] = Filename that is displayed for the attachment
272   [8] = Sent if message was found from a search (where)
273   [9] = Sent if message was found from a search (what)
274   
275 To set up links for actions, you assign them like this:
276   
277   $Args[1]['your_plugin_name']['href'] = 'URL to link to';
278   $Args[1]['your_plugin_name']['text'] = 'What to display';
279     
280
281 Outputting Your Own Pages
282 -------------------------
283
284 Often, when you want to provide your own customized options screen or create
285 another web page instead of just using standard hooks, you will be creating
286 your own .php files.  An example of this is the attachment_common plugin's
287 image.php file.
288
289 To make sure that security is maintained and standards are followed, the top
290 of your PHP script should look very similar to this:
291
292   <?PHP
293     /* This is my php file.
294      * description goes here.
295      */
296      
297     chdir('..');
298     include('../src/validate.php');
299     
300 The validate.php script will include internationalization support,
301 config.php variables, strings.php functions, and also authenticate that the
302 user is truly logged in.  Validate.php also calls stripslashes() on incoming
303 data (if gpc_magic_quotes() is on).  You should never need to worry about
304 that stuff again.  As a warning, this has only really been ironed out in
305 1.1.1.  If you create/modify a plugin to follow these rules, you must
306 mention that it requires SquirrelMail 1.1.1 or later.
307
308 After that, if you need further functions, just use
309
310   include('../functions/filename.php');
311   
312 in your script.  Since 1.0.5, it was no longer necessary (nor recommended)
313 to use the "if (! isset($filename_php))" syntax.