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
8 FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ
9 Plugin Hooks -> http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins
12 A FEW NOTES ON THE PLUGIN ARCHITECTURE
13 ======================================
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
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".
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.
33 Some way for the plugins to interact with the help subsystem and
34 translations will be provided.
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').
44 The do_hook traverses the array $squirrelmail_plugin_hooks['hookname']
45 and executes all the functions that are named in that array.
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.
50 To start using a plugin, its name must be added to the $plugins array
51 in config.php like this:
53 $plugins[0] = 'plugin_name';
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.
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.
66 The function squirrelmail_plugin_init_plugin_name is called to
67 initalize a plugin. This function could look something like this:
69 function squirrelmail_plugin_init_demo () {
70 global $squirrelmail_plugin_hooks;
72 $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header';
73 $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline';
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.
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.
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.
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)
152 There are two ways to do options for your plugin. First, you can incorporate it
153 into an existing section of the preferences (Display, Personal, or Folders).
154 The second way, you create your own section that they can choose from and it
155 displays its own range of options.
158 First: Integrating into existing options
159 -----------------------------------------
160 There are two hooks you need to use for this one:
162 1. options_YOUCHOOSE_inside
163 This is the code that goes inside the table for the section you choose. Since
164 it is going inside an existing table, it must be in this form:
165 ------cut here-------
174 ------cut here-------
176 2. options_YOUCHOOSE_save
177 This is the code that saves your preferences into the users' preference
178 file. For an example of how to do this, see src/options.php.
181 Second: Create your own section
182 -------------------------------
183 It is possible to create your own options sections with plugins. There are
184 three hooks you will need to use.
186 1. options_link_and_description
187 This creates the link and has a description that is shown on the options
188 page. This should output HTML that looks like this. Make sure to read
189 the section on outputing your own pages.
192 function my_plugin_name_my_function() {
195 <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
197 <td bgcolor="<?php echo $color[9] ?>">
198 <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a>
202 <td bgcolor="<?php echo $color[0] ?>">
212 Here is the code that you need to do to save your options in the
213 preference files or manipulate whatever data you are trying to change
214 through the options section. You can look at options.php for details
215 on how this is to be done.
217 3. loading_prefs (optional)
218 If you are wanting to save preferences to the preference files, then
219 you need to do this step as well. Otherwise if you are manipulating
220 other data, ignore this step.
222 You should put the code in here that loads your preferences back
223 into usable variables. Examples of this can be found in the file
229 Some hooks are passed special information in the array of arguments. See
230 the SpamCop plugin for how to use them.
232 options_identities_process
234 [1] = Should I run the SaveUpdateFunction() (alterable)
236 options_identities_renumber
238 [1] = Renumber it from ('default' or 1 through # idents - 1)
239 [2] = Renumber it to (same thing)
241 options_identities_table
243 [1] = Color of table (use it like <tr<?PHP echo $Info[1]?>> in your
245 [2] = Is this an empty section?
246 [3] = What is the 'post' value?
248 options_identities_buttons
250 [1] = Is this an empty section (the one at the end of the list)?
251 [2] = What is the 'post' value?
256 When a message has attachments, this hook is called with the MIME types. For
257 instance, a .zip file hook is "attachment application/x-zip". The hook should
258 probably show a link to do a specific action, such as "Verify" or "View" for a
261 This is a breakdown of the data passed in the array to the hook that is called:
263 [0] = Hook's name ('attachment text/plain')
264 [1] = Array of links of actions (more below) (Alterable)
265 [2] = Used for returning to mail message (startMessage)
266 [3] = Used for finding message to display (id)
267 [4] = Mailbox name, urlencode()'d (urlMailbox)
268 [5] = Entity ID inside mail message (ent)
269 [6] = Default URL to go to when filename is clicked on (Alterable)
270 [7] = Filename that is displayed for the attachment
271 [8] = Sent if message was found from a search (where)
272 [9] = Sent if message was found from a search (what)
274 To set up links for actions, you assign them like this:
276 $Args[1]['your_plugin_name']['href'] = 'URL to link to';
277 $Args[1]['your_plugin_name']['text'] = 'What to display';
279 It's also possible to specify a hook as "attachment type0/*",
280 for example "attachment text/*". This hook will be executed whenever there's
281 no more specific rule available for that type.
284 Outputting Your Own Pages
285 -------------------------
287 Often, when you want to provide your own customized options screen or create
288 another web page instead of just using standard hooks, you will be creating
289 your own .php files. An example of this is the attachment_common plugin's
292 To make sure that security is maintained and standards are followed, the top
293 of your PHP script should look very similar to this:
296 /* This is my php file.
297 * description goes here.
301 include('../src/validate.php');
303 The validate.php script will include internationalization support,
304 config.php variables, strings.php functions, and also authenticate that the
305 user is truly logged in. validate.php also calls stripslashes() on incoming
306 data (if gpc_magic_quotes() is on). You should never need to worry about
307 that stuff again. As a warning, this has only really been ironed out in
308 1.1.1. If you create/modify a plugin to follow these rules, you must
309 mention that it requires SquirrelMail 1.1.1 or later.
311 After that, if you need further functions, just use
313 include('../functions/filename.php');
315 in your script. Since 1.0.5, it was no longer necessary (nor recommended)
316 to use the "if (! isset($filename_php))" syntax.