1aaef171 |
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. |
6b638171 |
75 | |
76 | |
a3a95e4a |
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 | |
6b638171 |
88 | List of hooks |
89 | ------------- |
ef3c69f0 |
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 |
b3911477 |
94 | compose_form src/compose.php |
ef3c69f0 |
95 | left_main_before src/left_main.php |
96 | left_main_after src/left_main.php |
97 | * options_save src/options.php (see note on options) |
98 | * options_link_and_description src/options.php (see note on options) |
99 | * options_highlight_bottom src/options_highlight.php |
100 | * options_personal_bottom src/options_personal.php |
101 | * options_personal_inside src/options_personal.php |
102 | * options_personal_save src/options_personal.php |
103 | * options_display_bottom src/options_display.php |
104 | * options_display_inside src/options_display.php |
3751dc7f |
105 | * options_display_save src/options_display.php |
ef3c69f0 |
106 | * options_folders_bottom src/options_folders.php |
107 | * options_folders_inside src/options_folders.php |
108 | * options_folders_save src/options_folders.php |
109 | logout src/signout.php |
110 | login_before src/webmail.php |
111 | login_verified src/webmail.php |
112 | loading_prefs src/load_prefs.php |
113 | mailbox_index_before functions/mailbox_display.php |
114 | mailbox_index_after functions/mailbox_display.php |
3751dc7f |
115 | mailbox_form_before functions/mailbox_display.php |
1ffd5e31 |
116 | subject_link functions/mailbox_display.php |
ef3c69f0 |
117 | right_main_after_header src/right_main.php |
118 | right_main_bottom src/right_main.php |
119 | login_top src/login.php |
120 | login_bottom src/login.php |
441f2d33 |
121 | html_top src/read_body.php |
ef3c69f0 |
122 | read_body_top src/read_body.php |
123 | read_body_bottom src/read_body.php |
441f2d33 |
124 | html_bottom src/read_body.php |
7137f80f |
125 | read_body_header src/read_body.php |
ef3c69f0 |
126 | search_before_form src/search.php |
127 | search_after_form src/search.php |
128 | search_bottom src/search.php |
129 | help_top src/help.php |
130 | help_bottom src/help.php |
131 | help_chapter src/help.php |
3937dc89 |
132 | addrbook_html_search_below src/addrbook_search_html.php |
ef3c69f0 |
133 | addressbook_bottom src/addressbook.php |
a3a95e4a |
134 | ^ attachment $type0/$type1 functions/mime.php (see note on attachments) |
135 | |
06ad27a2 |
136 | |
ef3c69f0 |
137 | (*) Options |
138 | ----------- |
139 | There are two ways to do options for your plugin. First, you can incorporate it |
140 | into an existing section of the preferences (Display, Personal, or Folders). |
141 | The second way, you create your own section that they can choose from and it |
142 | displays its own range of options. |
143 | |
144 | |
145 | First: Integrating into existing options |
146 | ----------------------------------------- |
147 | There are two hooks you need to use for this one: |
148 | |
149 | 1. options_YOUCHOOSE_inside |
150 | This is the code that goes inside the table for the section you choose. Since |
151 | it is going inside an existing table, it must be in this form: |
152 | ------cut here------- |
153 | <tr> |
154 | <td> |
155 | OPTION_NAME |
156 | </td> |
157 | <td> |
158 | OPTION_INPUT |
159 | </td> |
160 | </tr> |
161 | ------cut here------- |
162 | |
163 | 2. options_YOUCHOOSE_save |
164 | This is the code that saves your preferences into the users' preference |
165 | file. For an example of how to do this, see src/options.php. |
166 | |
167 | |
168 | Second: Create your own section |
169 | ------------------------------- |
6b638171 |
170 | It is possible to create your own options sections with plugins. There are |
171 | three hooks you will need to use. |
172 | |
173 | 1. options_link_and_description |
174 | This creates the link and has a description that are shown on the options |
175 | page. This should output HTML that looks like this: |
176 | |
177 | -----cut here----- |
178 | function my_function() { |
179 | global $color |
180 | ?> |
181 | <table width=50% cellpadding=3 cellspacing=0 border=0 align=center> |
182 | <tr> |
183 | <td bgcolor="<? echo $color[9] ?>"> |
184 | <a href="../plugins/YOUR_PLUGIN/YOUR_OPTIONS.php">YOUR OPTIONS NAME</a> |
185 | </td> |
186 | </tr> |
187 | <tr> |
188 | <td bgcolor="<? echo $color[0] ?>"> |
189 | YOUR DESCRIPTION |
190 | </td> |
191 | </tr> |
192 | </table> |
193 | <?php |
194 | } |
195 | -----cut here----- |
196 | |
197 | 2. options_save |
198 | Here is the code that you need to do to save your options in the |
199 | preference files or manipulate whatever data you are trying to change |
200 | through the options section. You can look at options.php for details |
201 | on how this is to be done. |
202 | |
203 | 3. loading_prefs (optional) |
204 | If you are wanting to save preferences to the preference files, then |
205 | you need to do this step as well. Otherwise if you are manipulating |
206 | other data, ignore this step. |
207 | |
208 | You should put the code in here that loads your preferences back |
209 | into usable variables. Examples of this can be found in the file |
210 | src/load_prefs.php |
a3a95e4a |
211 | |
212 | |
213 | (^) Attachment Hooks |
214 | -------------------- |
215 | When a message has attachments, this hook is called with the MIME types. For |
216 | instance, a .zip file hook is "attachment application/x-zip". The hook should |
217 | probably show a link to do a specific action, such as "Verify" or "View" for a |
218 | .zip file. |
219 | |
220 | This is a breakdown of the data passed in the array to the hook that is called: |
221 | |
222 | [0] = Hook's name ('attachment text/plain') |
223 | [1] = Array of links of actions (more below) (Alterable) |
224 | [2] = Used for returning to mail message (startMessage) |
225 | [3] = Used for finding message to display (id) |
226 | [4] = Mailbox name, urlencode()'d (urlMailbox) |
227 | [5] = Entity ID inside mail message (ent) |
228 | [6] = Default URL to go to when filename is clicked on (Alterable) |
ef30bf50 |
229 | [7] = Filename that is displayed for the attachment |
230 | [8] = Sent if message was found from a search (where) |
231 | [9] = Sent if message was found from a search (what) |
a3a95e4a |
232 | |
233 | To set up links for actions, you assign them like this: |
234 | |
235 | $Args[1]['your_plugin_name']['href'] = 'URL to link to'; |
236 | $Args[1]['your_plugin_name']['text'] = 'What to display'; |
441f2d33 |
237 | |