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