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