| 1 | $Id$ |
| 2 | |
| 3 | In addition to this document, please check out the SquirrelMail |
| 4 | development FAQ for more information. Also, help writing plugins |
| 5 | is easily obtained by posting to the squirrelmail-plugins mailing |
| 6 | list. (See details about mailing lists on the website) |
| 7 | |
| 8 | FAQ -> http://www.squirrelmail.org/wiki/wiki.php?DeveloperFAQ |
| 9 | Plugin Development -> |
| 10 | http://www.squirrelmail.org/wiki/wiki.php?DevelopingPlugins |
| 11 | |
| 12 | |
| 13 | A FEW NOTES ON THE PLUGIN ARCHITECTURE |
| 14 | ====================================== |
| 15 | |
| 16 | The plugin architecture of SquirrelMail is designed to make it possible |
| 17 | to add new features without having to patch SquirrelMail itself. |
| 18 | Functionality like password changing, displaying ads and calendars should |
| 19 | be possible to add as plugins. |
| 20 | |
| 21 | |
| 22 | The Idea |
| 23 | -------- |
| 24 | |
| 25 | The idea is to be able to run random code at given places in the |
| 26 | SquirrelMail code. This random code should then be able to do whatever |
| 27 | needed to enhance the functionality of SquirrelMail. The places where |
| 28 | code can be executed are called "hooks". |
| 29 | |
| 30 | There are some limitations in what these hooks can do. It is difficult |
| 31 | to use them to change the layout and to change functionality that |
| 32 | already is in SquirrelMail. |
| 33 | |
| 34 | Some way for the plugins to interact with the help subsystem and |
| 35 | translations will be provided. |
| 36 | |
| 37 | |
| 38 | The Implementation |
| 39 | ------------------ |
| 40 | |
| 41 | The plugin jumping off point in the main SquirrelMail code is in the |
| 42 | file functions/plugin.php. In places where hooks are made available, |
| 43 | they are executed by calling the function do_hook('hookname'). The |
| 44 | do_hook function then traverses the array |
| 45 | $squirrelmail_plugin_hooks['hookname'] and executes all the functions |
| 46 | that are named in that array. Those functions are placed there when |
| 47 | plugins register themselves with SquirrelMail as discussed below. A |
| 48 | plugin may add its own internal functions to this array under any |
| 49 | hook name provided by the SquirrelMail developers. |
| 50 | |
| 51 | A plugin must reside in a subdirectory in the plugins/ directory. The |
| 52 | name of the subdirectory is considered to be the name of the plugin. |
| 53 | (The plugin will not function correctly if this is not the case.) |
| 54 | |
| 55 | To start using a plugin, its name must be added to the $plugins array |
| 56 | in config.php like this: |
| 57 | |
| 58 | $plugins[0] = 'plugin_name'; |
| 59 | |
| 60 | When a plugin is registered, the file plugins/plugin_name/setup.php is |
| 61 | included and the function squirrelmail_plugin_init_plugin_name() is |
| 62 | called with no parameters. That function is where the plugin may |
| 63 | register itself against any hooks it wishes to take advantage of. |
| 64 | |
| 65 | |
| 66 | WRITING PLUGINS |
| 67 | =============== |
| 68 | |
| 69 | All plugins must contain a file called setup.php and must include a |
| 70 | function called squirrelmail_plugin_init_plugin_name() therein. Since |
| 71 | including numerous plugins can slow SquirrelMail performance |
| 72 | considerably, the setup.php file should contain little else. Any |
| 73 | functions that are registered against plugin hooks should do little |
| 74 | more than call another function in a different file. |
| 75 | |
| 76 | Any other files used by the plugin should also be placed in the |
| 77 | plugin directory (or subdirectory thereof) and should contain the |
| 78 | bulk of the plugin logic. |
| 79 | |
| 80 | The function squirrelmail_plugin_init_plugin_name() is called to |
| 81 | initalize a plugin. This function could look something like this (if |
| 82 | the plugin was named "demo" and resided in the directory plugins/demo/): |
| 83 | |
| 84 | function squirrelmail_plugin_init_demo () |
| 85 | { |
| 86 | global $squirrelmail_plugin_hooks; |
| 87 | |
| 88 | $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; |
| 89 | $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline'; |
| 90 | } |
| 91 | |
| 92 | Please note that as of SquirrelMail 1.5.0, this function will no longer |
| 93 | be called at run time and will instead be called only once at configure- |
| 94 | time. Thus, the inclusion of any dynamic code (anything except hook |
| 95 | registration) here is strongly discouraged. |
| 96 | |
| 97 | In this example, the "demo" plugin should also have two other functions |
| 98 | in its setup.php file called plugin_demo_header() and plugin_demo_menuline(). |
| 99 | The first of these might look something like this: |
| 100 | |
| 101 | function plugin_demo_header() |
| 102 | { |
| 103 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
| 104 | plugin_demo_header_do(); |
| 105 | } |
| 106 | |
| 107 | The function called plugin_demo_header_do() would be in the file called |
| 108 | functions.php in the demo plugin directory and would contain the plugin's |
| 109 | core logic for the "generic_header" hook. |
| 110 | |
| 111 | |
| 112 | Including Other Files |
| 113 | --------------------- |
| 114 | |
| 115 | A plugin may need to reference functionality provided in other |
| 116 | files, and therefore need to include those files. Most of the |
| 117 | core SquirrelMail functions are already available to your plugin |
| 118 | unless it has any files that are requested directly by the client |
| 119 | browser (custom options page, etc.). In this case, you'll need |
| 120 | to make sure you include the files you need (see below). |
| 121 | |
| 122 | Note that as of SquirrelMail 1.4.0, all files are accessed using a |
| 123 | constant called SM_PATH that always contains the relative path to |
| 124 | the main SquirrelMail directory. This constant is always available |
| 125 | for you to use when including other files from the SquirrelMail core, |
| 126 | your own plugin, or other plugins, should the need arise. If any of |
| 127 | your plugin files are requested directly from the client browser, |
| 128 | you will need to define this constant before you do anything else: |
| 129 | |
| 130 | define('SM_PATH', '../../'); |
| 131 | |
| 132 | Files are included like this: |
| 133 | |
| 134 | include_once(SM_PATH . 'include/validate.php'); |
| 135 | |
| 136 | When including files, please make sure to use the include_once() function |
| 137 | and NOT include(), require(), or require_once(), since these all are much |
| 138 | less efficient than include_once() and can have a cumulative effect on |
| 139 | SquirrelMail performance. |
| 140 | |
| 141 | The files that you may need to include in a plugin will vary greatly |
| 142 | depending upon what the plugin is designed to do. For files that are |
| 143 | requested directly by the client browser, we strongly recommend that |
| 144 | you include the file include/validate.php, since it will set up the |
| 145 | SquirrelMail environment automatically. It will ensure the the user |
| 146 | has been authenticated and is currently logged in, load all user |
| 147 | preferences, include internationalization support, call stripslashes() |
| 148 | on all incoming data (if magic_quotes_gpc is on), and initialize and |
| 149 | include all other basic SquirrelMail resources and functions. You may |
| 150 | see other plugins that directly include other SquirrelMail files, but |
| 151 | that is no longer necessary and is a hold-over from older SquirrelMail |
| 152 | versions. |
| 153 | |
| 154 | |
| 155 | Hook Types: Parameters and Return Values |
| 156 | ----------------------------------------- |
| 157 | |
| 158 | Hooks, when executed, are called with differing parameters and may or may |
| 159 | not take return values, all depending on the type of hook being called and |
| 160 | the context in which it is being used. On the source side (where the hook |
| 161 | call originates), all hooks have at least one parameter, which is the |
| 162 | name of the hook. After that, things get complicated. |
| 163 | |
| 164 | do_hook |
| 165 | ------- |
| 166 | Most hook calls don't pass any data and don't ask for anything back. |
| 167 | These always use the do_hook call. A limited number of do_hook calls do |
| 168 | pass some extra parameters, in which case your plugin may modify the |
| 169 | given data if you do so by reference. It is not necessary to return |
| 170 | anything from your function in such a case; modifying the parameter |
| 171 | data by reference is what does the job (although the hook call itself |
| 172 | (in the source) must grab the return value for this to work). Note |
| 173 | that in this case, the parameter to your hook function will be an array, |
| 174 | the first element simply being the hook name, followed by any other |
| 175 | parameters that may have been included in the actual hook call in the |
| 176 | source. Modify parameters with care! |
| 177 | |
| 178 | do_hook_function |
| 179 | ---------------- |
| 180 | This hook type was intended to be the main hook type used when the |
| 181 | source needs to get something back from your plugin. It is somewhat |
| 182 | limited in that it will only use the value returned from the LAST |
| 183 | plugin registered against the hook. The source for this hook might |
| 184 | use the return value for internal purposes, or might expect you to |
| 185 | provide text or HTML to be sent to the client browser (you'll have to |
| 186 | look at its use in context to understand how you should return values |
| 187 | here). The parameters that your hook function gets will be anything |
| 188 | you see AFTER the hook name in the actual hook call in the source. |
| 189 | These cannot be changed in the same way that the do_hook parameters |
| 190 | can be. |
| 191 | |
| 192 | concat_hook_function |
| 193 | -------------------- |
| 194 | This is a newer hook type meant to address the shortcomings of |
| 195 | do_hook_function; specifically in that it uses the return values of |
| 196 | all plugins registered against the hook. In order to do so, the |
| 197 | return value is assumed to be a string, which is just piled on top |
| 198 | of whatever it got from the other plugins working on the same hook. |
| 199 | Again, you'll have to inspect the source code to see how such data |
| 200 | is put to use, but most of the time, it is used to create a string |
| 201 | of HTML to be inserted into the output page. The parameters that |
| 202 | your hook function will get are the same as for the do_hook_function; |
| 203 | they are anything AFTER the hook name in the actual hook call in the |
| 204 | source. |
| 205 | |
| 206 | boolean_hook_function |
| 207 | --------------------- |
| 208 | The newest of the SquirrelMail hooks, this type is used to let all |
| 209 | plugins registered against the hook to "vote" for some action. What |
| 210 | that action is is entirely dependent on how the hook is used in the |
| 211 | source (look for yourself). Plugins make their "vote" by returning |
| 212 | TRUE or FALSE. This hook may be configured to "tally votes" in one |
| 213 | of three ways. This configuration is done with the third parameter |
| 214 | in the hook call in the source: |
| 215 | > 0 -- Any one or more TRUEs will override any FALSEs |
| 216 | < 0 -- Any one or more FALSEs will override any TRUEs |
| 217 | = 0 -- Majority wins. Ties are broken in this case with |
| 218 | the last parameter in the hook call in the source. |
| 219 | Your hook function will get the second paramter in the hook call in |
| 220 | the source as its parameter (this might be an array if multiple values |
| 221 | need to be passed). |
| 222 | |
| 223 | See below for further discussion of special hook types and the values |
| 224 | |
| 225 | |
| 226 | List of Hooks |
| 227 | ------------- |
| 228 | |
| 229 | This is a list of all hooks currently available in SquirrelMail, ordered |
| 230 | by file. Note that this list is accurate as of June 17, 2003 (should be |
| 231 | close to what is contained in release 1.4.1, plus or minus a hook or two), |
| 232 | but may be out of date soon thereafter. You never know. ;-) |
| 233 | |
| 234 | Hook Name Found In Called With(#) |
| 235 | --------- -------- -------------- |
| 236 | loading_constants functions/constants.php do_hook |
| 237 | logout_error functions/display_messages.php do_hook |
| 238 | error_box functions/display_messages.php concat_hook |
| 239 | get_pref_override functions/file_prefs.php hook_func |
| 240 | get_pref functions/file_prefs.php hook_func |
| 241 | special_mailbox functions/imap_mailbox.php hook_func |
| 242 | % rename_or_delete_folder functions/imap_mailbox.php hook_func |
| 243 | mailbox_index_before functions/mailbox_display.php do_hook |
| 244 | mailbox_form_before functions/mailbox_display.php do_hook |
| 245 | mailbox_index_after functions/mailbox_display.php do_hook |
| 246 | check_handleAsSent_result functions/mailbox_display.php do_hook |
| 247 | subject_link functions/mailbox_display.php concat_hook |
| 248 | mailbox_display_buttons functions/mailbox_display.php do_hook |
| 249 | message_body functions/mime.php do_hook |
| 250 | ^ attachment $type0/$type1 functions/mime.php do_hook |
| 251 | attachments_bottom functions/mime.php hook_func |
| 252 | decode_body functions/mime.php hook_func |
| 253 | generic_header functions/page_header.php do_hook |
| 254 | menuline functions/page_header.php do_hook |
| 255 | internal_link functions/page_header.php hook_func |
| 256 | loading_prefs include/load_prefs.php do_hook |
| 257 | addrbook_html_search_below src/addrbook_search_html.php do_hook |
| 258 | addressbook_bottom src/addressbook.php do_hook |
| 259 | compose_form src/compose.php do_hook |
| 260 | compose_bottom src/compose.php do_hook |
| 261 | compose_button_row src/compose.php do_hook |
| 262 | compose_send src/compose.php do_hook |
| 263 | folders_bottom src/folders.php do_hook |
| 264 | help_top src/help.php do_hook |
| 265 | help_chapter src/help.php do_hook |
| 266 | help_bottom src/help.php do_hook |
| 267 | left_main_after_each_folder src/left_main.php concat_hook |
| 268 | left_main_before src/left_main.php do_hook |
| 269 | left_main_after src/left_main.php do_hook |
| 270 | login_cookie src/login.php do_hook |
| 271 | login_top src/login.php do_hook |
| 272 | login_form src/login.php do_hook |
| 273 | login_bottom src/login.php do_hook |
| 274 | move_before_move src/move_messages.php do_hook |
| 275 | move_messages_button_action src/move_messages.php concat_hook |
| 276 | * optpage_set_loadinfo src/options.php do_hook |
| 277 | * optpage_loadhook_personal src/options.php do_hook |
| 278 | * optpage_loadhook_display src/options.php do_hook |
| 279 | * optpage_loadhook_highlight src/options.php do_hook |
| 280 | * optpage_loadhook_folder src/options.php do_hook |
| 281 | * optpage_loadhook_order src/options.php do_hook |
| 282 | * options_personal_save src/options.php do_hook |
| 283 | * options_display_save src/options.php do_hook |
| 284 | * options_folder_save src/options.php do_hook |
| 285 | * options_save src/options.php do_hook |
| 286 | * optpage_register_block src/options.php do_hook |
| 287 | * options_link_and_description src/options.php do_hook |
| 288 | * options_personal_inside src/options.php do_hook |
| 289 | * options_display_inside src/options.php do_hook |
| 290 | * options_highlight_inside src/options.php do_hook |
| 291 | * options_folder_inside src/options.php do_hook |
| 292 | * options_order_inside src/options.php do_hook |
| 293 | * options_personal_bottom src/options.php do_hook |
| 294 | * options_display_bottom src/options.php do_hook |
| 295 | * options_highlight_bottom src/options.php do_hook |
| 296 | * options_folder_bottom src/options.php do_hook |
| 297 | * options_order_bottom src/options.php do_hook |
| 298 | * options_highlight_bottom src/options_highlight.php do_hook |
| 299 | & options_identities_process src/options_identities.php do_hook |
| 300 | & options_identities_top src/options_identities.php do_hook |
| 301 | &% options_identities_renumber src/options_identities.php do_hook |
| 302 | & options_identities_table src/options_identities.php concat_hook |
| 303 | & options_identities_buttons src/options_identities.php concat_hook |
| 304 | message_body src/printer_friendly_bottom.php do_hook |
| 305 | read_body_header src/read_body.php do_hook |
| 306 | read_body_menu_top src/read_body.php hook_func |
| 307 | read_body_menu_bottom src/read_body.php do_hook |
| 308 | read_body_header_right src/read_body.php do_hook |
| 309 | html_top src/read_body.php do_hook |
| 310 | read_body_top src/read_body.php do_hook |
| 311 | read_body_bottom src/read_body.php do_hook |
| 312 | html_bottom src/read_body.php do_hook |
| 313 | login_before src/redirect.php do_hook |
| 314 | login_verified src/redirect.php do_hook |
| 315 | generic_header src/right_main.php do_hook |
| 316 | right_main_after_header src/right_main.php do_hook |
| 317 | right_main_bottom src/right_main.php do_hook |
| 318 | search_before_form src/search.php do_hook |
| 319 | search_after_form src/search.php do_hook |
| 320 | search_bottom src/search.php do_hook |
| 321 | logout src/signout.php do_hook |
| 322 | webmail_top src/webmail.php do_hook |
| 323 | webmail_bottom src/webmail.php concat_hook |
| 324 | logout_above_text src/signout.php concat_hook |
| 325 | |
| 326 | % = This hook is used in multiple places in the given file |
| 327 | # = Called with hook type (see below) |
| 328 | & = Special identity hooks (see below) |
| 329 | ^ = Special attachments hook (see below) |
| 330 | * = Special options hooks (see below) |
| 331 | |
| 332 | |
| 333 | (#) Called With |
| 334 | --------------- |
| 335 | Each hook is called using the hook type specified in the list above: |
| 336 | do_hook do_hook() |
| 337 | hook_func do_hook_function() |
| 338 | concat_hook concat_hook_function() |
| 339 | |
| 340 | |
| 341 | (&) Identity Hooks |
| 342 | ------------------ |
| 343 | This set of hooks is passed special information in the array of arguments: |
| 344 | |
| 345 | options_identities_process |
| 346 | |
| 347 | This hook is called at the top of the Identities page, which is |
| 348 | most useful when the user has changed any identity settings - this |
| 349 | is where you'll want to save any custom information you are keeping |
| 350 | for each identity or catch any custom submit buttons that you may |
| 351 | have added to the identities page. The arguments to this hook are: |
| 352 | |
| 353 | [0] = hook name (always "options_identities_process") |
| 354 | [1] = should I run the SaveUpdateFunction() (alterable) |
| 355 | |
| 356 | Obviously, set the second array element to 1/true if you want to |
| 357 | trigger SaveUpdateFunction() after the hook is finished - by default, |
| 358 | it will not be called. |
| 359 | |
| 360 | options_identities_renumber |
| 361 | |
| 362 | This hook is called when one of the identities is being renumbered, |
| 363 | such as if the user had three identities and deletes the second - |
| 364 | this hook would be called with an array that looks like this: |
| 365 | ('options_identities_renumber', 2, 1). The arguments to this hook |
| 366 | are: |
| 367 | |
| 368 | [0] = hook name (always "options_identities_renumber") |
| 369 | [1] = being renumbered from ('default' or 1 through (# idents) - 1) |
| 370 | [2] = being renumbered to ('default' or 1 through (# idents) - 1) |
| 371 | |
| 372 | options_identities_table |
| 373 | |
| 374 | This hook allows you to insert additional rows into the table that |
| 375 | holds each identity. The arguments to this hook are: |
| 376 | |
| 377 | [0] = color of table (use it like this in your plugin: |
| 378 | <tr bgcolor="<?PHP echo $info[1]?>"> |
| 379 | [1] = is this an empty section (the one at the end of the list)? |
| 380 | [2] = what is the 'post' value? (ident # or empty string if default) |
| 381 | |
| 382 | You need to return any HTML you would like to add to the table. |
| 383 | You could add a table row with code similar to this: |
| 384 | |
| 385 | function demo_identities_table(&$args) |
| 386 | { |
| 387 | return '<tr bgcolor="' . $args[0] . '"><td> </td><td>' |
| 388 | . 'YOUR CODE HERE' . '</td></tr>' . "\n"; |
| 389 | } |
| 390 | |
| 391 | options_identities_buttons |
| 392 | |
| 393 | This hook allows you to add a button (or other HTML) to the row of |
| 394 | buttons under each identity. The arguments to this hook are: |
| 395 | |
| 396 | [0] = is this an empty section (the one at the end of the list)? |
| 397 | [1] = what is the 'post' value? (ident # or empty string if default) |
| 398 | |
| 399 | You need to return any HTML you would like to add here. You could add |
| 400 | a button with code similar to this: |
| 401 | |
| 402 | function demo_identities_button(&$args) |
| 403 | { |
| 404 | return '<input type="submit" name="demo_button_' . $args[1] |
| 405 | . '" value="Press Me">'; |
| 406 | } |
| 407 | |
| 408 | |
| 409 | (^) Attachment Hooks |
| 410 | -------------------- |
| 411 | When a message has attachments, this hook is called with the MIME types. For |
| 412 | instance, a .zip file hook is "attachment application/x-zip". The hook should |
| 413 | probably show a link to do a specific action, such as "Verify" or "View" for a |
| 414 | .zip file. Thus, to register your plugin for .zip attachments, you'd do this |
| 415 | in setup.php (assuming your plugin is called "demo"): |
| 416 | |
| 417 | $squirrelmail_plugin_hooks['attachment application/x-zip']['demo'] |
| 418 | = 'demo_handle_zip_attachment'; |
| 419 | |
| 420 | This is a breakdown of the data passed in the array to the hook that is called: |
| 421 | |
| 422 | [0] = Hook's name ('attachment text/plain') |
| 423 | [1] = Array of links of actions (see below) (alterable) |
| 424 | [2] = Used for returning to mail message (startMessage) |
| 425 | [3] = Used for finding message to display (id) |
| 426 | [4] = Mailbox name, urlencode()'d (urlMailbox) |
| 427 | [5] = Entity ID inside mail message (ent) |
| 428 | [6] = Default URL to go to when filename is clicked on (alterable) |
| 429 | [7] = Filename that is displayed for the attachment |
| 430 | [8] = Sent if message was found from a search (where) |
| 431 | [9] = Sent if message was found from a search (what) |
| 432 | |
| 433 | To set up links for actions, you assign them like this: |
| 434 | |
| 435 | $Args[1]['<plugin_name>']['href'] = 'URL to link to'; |
| 436 | $Args[1]['<plugin_name>']['text'] = 'What to display'; |
| 437 | |
| 438 | It's also possible to specify a hook as "attachment type0/*", |
| 439 | for example "attachment text/*". This hook will be executed whenever there's |
| 440 | no more specific rule available for that type. |
| 441 | |
| 442 | Putting all this together, the demo_handle_zip_attachment() function should |
| 443 | look like this (note the argument being passed): |
| 444 | |
| 445 | function demo_handle_zip_attachment(&$Args) |
| 446 | { |
| 447 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
| 448 | demo_handle_zip_attachment_do($Args); |
| 449 | } |
| 450 | |
| 451 | And the demo_handle_zip_attachment_do() function in the |
| 452 | plugins/demo/functions.php file would typically (but not necessarily) |
| 453 | display a custom link: |
| 454 | |
| 455 | function demo_handle_zip_attachment_do(&$Args) |
| 456 | { |
| 457 | $Args[1]['demo']['href'] = SM_PATH . 'plugins/demo/zip_handler.php?' |
| 458 | . 'passed_id=' . $Args[3] . '&mailbox=' . $Args[4] |
| 459 | . '&passed_ent_id=' . $Args[5]; |
| 460 | $Args[1]['demo']['text'] = 'show zip contents'; |
| 461 | } |
| 462 | |
| 463 | The file plugins/demo/zip_handler.php can now do whatever it needs with the |
| 464 | attachment (note that this will hand information about how to retrieve the |
| 465 | source message from the IMAP server as GET varibles). |
| 466 | |
| 467 | |
| 468 | (*) Options |
| 469 | ----------- |
| 470 | Before you start adding user preferences to your plugin, please take a moment |
| 471 | to think about it: in some cases, more options may not be a good thing. |
| 472 | Having too many options can be confusing. Thinking from the user's |
| 473 | perspective, will the proposed options actually be used? Will users |
| 474 | understand what these options are for? |
| 475 | |
| 476 | There are two ways to add options for your plugin. When you only have a few |
| 477 | options that don't merit an entirely new preferences page, you can incorporate |
| 478 | them into an existing section of SquirrelMail preferences (Personal |
| 479 | Information, Display Preferences, Message Highlighting, Folder Preferences or |
| 480 | Index Order). Or, if you have an extensive number of settings or for some |
| 481 | reason need a separate page for the user to interact with, you can create your |
| 482 | own preferences page. |
| 483 | |
| 484 | |
| 485 | Integrating Your Options Into Existing SquirrelMail Preferences Pages |
| 486 | --------------------------------------------------------------------- |
| 487 | |
| 488 | There are two ways to accomplish the integration of your plugin's settings |
| 489 | into another preferences page. The first method is to add the HTML code |
| 490 | for your options directly to the preferences page of your choice. Although |
| 491 | currently very popular, this method will soon be deprecated, so avoid it |
| 492 | if you can. That said, here is how it works. :) Look for any of the hooks |
| 493 | named as "options_<pref page>_inside", where <pref page> is "display", |
| 494 | "personal", etc. For this example, we'll use "options_display_inside" and, |
| 495 | as above, "demo" as our plugin name: |
| 496 | |
| 497 | 1. In setup.php in the squirrelmail_plugin_init_demo() function: |
| 498 | |
| 499 | $squirrelmail_plugin_hooks['options_display_inside']['demo'] |
| 500 | = 'demo_show_options'; |
| 501 | |
| 502 | Note that there are also hooks such as "options_display_bottom", |
| 503 | however, they place your options at the bottom of the preferences |
| 504 | page, which is usually not desirable (mostly because they also |
| 505 | come AFTER the HTML FORM tag is already closed). It is possible |
| 506 | to use these hooks if you want to create your own FORM with custom |
| 507 | submission logic. |
| 508 | |
| 509 | 2. Assuming the function demo_show_options() calls another function |
| 510 | elsewhere called demo_show_options_do(), that function should have |
| 511 | output similar to this (note that you will be inserting code into |
| 512 | a table that is already defined with two columns, so please be sure |
| 513 | to keep this framework in your plugin): |
| 514 | |
| 515 | ------cut here------- |
| 516 | <tr> |
| 517 | <td> |
| 518 | OPTION_NAME |
| 519 | </td> |
| 520 | <td> |
| 521 | OPTION_INPUT |
| 522 | </td> |
| 523 | </tr> |
| 524 | ------cut here------- |
| 525 | |
| 526 | Of course, you can place any text where OPTION_NAME is and any input |
| 527 | tags where OPTION_INPUT is. |
| 528 | |
| 529 | 3. You will want to use the "options_<pref page>_save" hook (in this case, |
| 530 | "options_display_save") to save the user's settings after they have |
| 531 | pressed the "Submit" button. Again, back in setup.php in the |
| 532 | squirrelmail_plugin_init_demo() function: |
| 533 | |
| 534 | $squirrelmail_plugin_hooks['options_display_save']['demo'] |
| 535 | = 'demo_save_options'; |
| 536 | |
| 537 | 4. Assuming the function demo_save_options() calls another function |
| 538 | elsewhere called demo_save_options_do(), that function should put |
| 539 | the user's settings into permanent storage (see the preferences |
| 540 | section below for more information). This example assumes that |
| 541 | in the preferences page, the INPUT tag's NAME attribute was set |
| 542 | to "demo_option": |
| 543 | |
| 544 | global $data_dir, $username; |
| 545 | sqgetGlobalVar('demo_option', $demo_option); |
| 546 | setPref($data_dir, $username, 'demo_option', $demo_option); |
| 547 | |
| 548 | |
| 549 | The second way to add options to one of the SquirrelMail preferences page is |
| 550 | to use one of the "optpage_loadhook_<pref page>" hooks. The sent_subfolders |
| 551 | plugin has an excellent example of this method. Briefly, this way of adding |
| 552 | options consists of adding some plugin-specific information to a predefined |
| 553 | data structure which SquirrelMail then uses to build the HTML input forms |
| 554 | for you. This is the preferred method of building options lists going forward. |
| 555 | |
| 556 | 1. We'll use the "optpage_loadhook_display" hook to add a new group of |
| 557 | options to the display preferences page. In setup.php in the |
| 558 | squirrelmail_plugin_init_demo() function: |
| 559 | |
| 560 | $squirrelmail_plugin_hooks['optpage_loadhook_display']['demo'] |
| 561 | = 'demo_options'; |
| 562 | |
| 563 | 2. Assuming the function demo_options() calls another function elsewhere |
| 564 | called demo_options_do(), that function needs to add a new key to two |
| 565 | arrays, $optpage_data['grps'] and $optpage_data['vals']. The value |
| 566 | associated with that key should simply be a section heading for your |
| 567 | plugin on the preferences page for the $optpage_data['grps'] array, |
| 568 | and yet another array with all of your plugin's options for the |
| 569 | $optpage_data['vals'] array. The options are built as arrays (yes, |
| 570 | that's four levels of nested arrays) that specify attributes that are |
| 571 | used by SquirrelMail to build your HTML input tags automatically. |
| 572 | This example includes just one input element, a SELECT (drop-down) |
| 573 | list: |
| 574 | |
| 575 | global $optpage_data; |
| 576 | $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options'; |
| 577 | $optionValues = array(); |
| 578 | $optionValues[] = array( |
| 579 | 'name' => 'plugin_demo_favorite_color', |
| 580 | 'caption' => 'Please Choose Your Favorite Color', |
| 581 | 'type' => SMOPT_TYPE_STRLIST, |
| 582 | 'refresh' => SMOPT_REFRESH_ALL, |
| 583 | 'posvals' => array(0 => 'red', |
| 584 | 1 => 'blue', |
| 585 | 2 => 'green', |
| 586 | 3 => 'orange'), |
| 587 | 'save' => 'save_plugin_demo_favorite_color' |
| 588 | ); |
| 589 | $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues; |
| 590 | |
| 591 | The array that you use to specify each plugin option has the following |
| 592 | possible attributes: |
| 593 | |
| 594 | name The name of this setting, which is used not only for |
| 595 | the INPUT tag name, but also for the name of this |
| 596 | setting in the user's preferences |
| 597 | caption The text that prefaces this setting on the preferences |
| 598 | page |
| 599 | type The type of INPUT element, which should be one of: |
| 600 | SMOPT_TYPE_STRING String/text input |
| 601 | SMOPT_TYPE_STRLIST Select list input |
| 602 | SMOPT_TYPE_TEXTAREA Text area input |
| 603 | SMOPT_TYPE_INTEGER Integer input |
| 604 | SMOPT_TYPE_FLOAT Floating point number input |
| 605 | SMOPT_TYPE_BOOLEAN Boolean (yes/no radio buttons) |
| 606 | input |
| 607 | SMOPT_TYPE_HIDDEN Hidden input (not actually |
| 608 | shown on preferences page) |
| 609 | SMOPT_TYPE_COMMENT Text is shown (specified by the |
| 610 | 'comment' attribute), but no |
| 611 | user input is needed |
| 612 | SMOPT_TYPE_FLDRLIST Select list of IMAP folders |
| 613 | refresh Indicates if a link should be shown to refresh part or |
| 614 | all of the window (optional). Possible values are: |
| 615 | SMOPT_REFRESH_NONE No refresh link is shown |
| 616 | SMOPT_REFRESH_FOLDERLIST Link is shown to refresh |
| 617 | only the folder list |
| 618 | SMOPT_REFRESH_ALL Link is shown to refresh |
| 619 | the entire window |
| 620 | initial_value The value that should initially be placed in this |
| 621 | INPUT element |
| 622 | posvals For select lists, this should be an associative array, |
| 623 | where each key is an actual input value and the |
| 624 | corresponding value is what is displayed to the user |
| 625 | for that list item in the drop-down list |
| 626 | value Specify the default/preselected value for this option |
| 627 | input |
| 628 | save You may indicate that special functionality needs to be |
| 629 | used instead of just saving this setting by giving the |
| 630 | name of a function to call when this value would |
| 631 | otherwise just be saved in the user's preferences |
| 632 | size Specifies the size of certain input items (typically |
| 633 | textual inputs). Possible values are: |
| 634 | SMOPT_SIZE_TINY |
| 635 | SMOPT_SIZE_SMALL |
| 636 | SMOPT_SIZE_MEDIUM |
| 637 | SMOPT_SIZE_LARGE |
| 638 | SMOPT_SIZE_HUGE |
| 639 | SMOPT_SIZE_NORMAL |
| 640 | comment For SMOPT_TYPE_COMMENT type options, this is the text |
| 641 | displayed to the user |
| 642 | script This is where you may add any additional javascript |
| 643 | or other code to the user input |
| 644 | post_script You may specify some script (usually Javascript) that |
| 645 | will be placed after (outside of) the INPUT tag. |
| 646 | |
| 647 | Note that you do not have to create a whole new section on the options |
| 648 | page if you merely want to add a simple input item or two to an options |
| 649 | section that already exists. For example, the Display Options page has |
| 650 | these groups: |
| 651 | |
| 652 | 0 - General Display Options |
| 653 | 1 - Mailbox Display Options |
| 654 | 2 - Message Display and Composition |
| 655 | |
| 656 | To add our previous input drop-down to the Mailbox Display Options, |
| 657 | we would not have to create our own group; just add it to group |
| 658 | number one: |
| 659 | |
| 660 | global $optpage_data; |
| 661 | $optpage_data['vals'][1][] = array( |
| 662 | 'name' => 'plugin_demo_favorite_color', |
| 663 | 'caption' => 'Please Choose Your Favorite Color', |
| 664 | 'type' => SMOPT_TYPE_STRLIST, |
| 665 | 'refresh' => SMOPT_REFRESH_ALL, |
| 666 | 'posvals' => array(0 => 'red', |
| 667 | 1 => 'blue', |
| 668 | 2 => 'green', |
| 669 | 3 => 'orange'), |
| 670 | 'save' => 'save_plugin_demo_favorite_color' |
| 671 | ); |
| 672 | |
| 673 | 3. If you indicated a 'save' attribute for any of your options, you must |
| 674 | create that function (you'll only need to do this if you need to do |
| 675 | some special processing for one of your settings). The function gets |
| 676 | one parameter, which is an object with mostly the same attributes you |
| 677 | defined when you made the option above... the 'new_value' (and possibly |
| 678 | 'value', which is the current value for this setting) is the most useful |
| 679 | attribute in this context: |
| 680 | |
| 681 | function save_plugin_demo_favorite_color($option) |
| 682 | { |
| 683 | // if user chose orange, make note that they are really dumb |
| 684 | if ($option->new_value == 3) |
| 685 | { |
| 686 | // more code here as needed |
| 687 | } |
| 688 | |
| 689 | // don't even save this setting if user chose green (old |
| 690 | // setting will remain) |
| 691 | if ($option->new_value == 2) |
| 692 | return; |
| 693 | |
| 694 | // for all other colors, save as normal |
| 695 | save_option($option); |
| 696 | } |
| 697 | |
| 698 | |
| 699 | Creating Your Own Preferences Page |
| 700 | ---------------------------------- |
| 701 | |
| 702 | It is also possible to create your own preferences page for a plugin. This |
| 703 | is particularly useful when your plugin has numerous options or needs to |
| 704 | offer special interaction with the user (for things such as changing password, |
| 705 | etc.). Here is an outline of how to do so (again, using the "demo" plugin |
| 706 | name): |
| 707 | |
| 708 | 1. Add a new listing to the main Options page. Older versions of |
| 709 | SquirrelMail offered a hook called "options_link_and_description" |
| 710 | although its use is deprecated (and it is harder to use in that |
| 711 | it requires you to write your own HTML to add the option). Instead, |
| 712 | you should always use the "optpage_register_block" hook where you |
| 713 | create a simple array that lets SquirrelMail build the HTML |
| 714 | to add the plugin options entry automatically. In setup.php in the |
| 715 | squirrelmail_plugin_init_demo() function: |
| 716 | |
| 717 | $squirrelmail_plugin_hooks['optpage_register_block']['demo'] |
| 718 | = 'demo_options_block'; |
| 719 | |
| 720 | 2. Assuming the function demo_options_block() calls another function |
| 721 | elsewhere called demo_options_block_do(), that function only needs |
| 722 | to create a simple array and add it to the $optpage_blocks array: |
| 723 | |
| 724 | global $optpage_blocks; |
| 725 | $optpage_blocks[] = array( |
| 726 | 'name' => 'Favorite Color Settings', |
| 727 | 'url' => SM_PATH . 'plugins/demo/options.php', |
| 728 | 'desc' => 'Change your favorite color & find new exciting colors', |
| 729 | 'js' => FALSE |
| 730 | ); |
| 731 | |
| 732 | The array should have four elements: |
| 733 | name The title of the plugin's options as it will be displayed on |
| 734 | the Options page |
| 735 | url The URI that points to your plugin's custom preferences page |
| 736 | desc A description of what the preferences page offers the user, |
| 737 | displayed on the Options page below the title |
| 738 | js Indicates if this option page requires the client browser |
| 739 | to be Javascript-capable. Should be TRUE or FALSE. |
| 740 | |
| 741 | 3. There are two different ways to create the actual preferences page |
| 742 | itself. One is to simply write all of your own HTML and other |
| 743 | interactive functionality, while the other is to define some data |
| 744 | structures that allow SquirrelMail to build your user inputs and save |
| 745 | your data automatically. |
| 746 | |
| 747 | Building your own page is wide open, and for ideas, you should look at |
| 748 | any of the plugins that currently have their own preferences pages. If |
| 749 | you do this, make sure to read step number 4 below for information on |
| 750 | saving settings. In order to maintain security, consistant look and |
| 751 | feel, internationalization support and overall integrity, there are just |
| 752 | a few things you should always do in this case: define the SM_PATH |
| 753 | constant, include the file include/validate.php (see the section about |
| 754 | including other files above) and make a call to place the standard page |
| 755 | heading at the top of your preferences page. The top of your PHP file |
| 756 | might look something like this: |
| 757 | |
| 758 | define('SM_PATH', '../../'); |
| 759 | include_once(SM_PATH . 'include/validate.php'); |
| 760 | global $color; |
| 761 | displayPageHeader($color, 'None'); |
| 762 | |
| 763 | From here you are on your own, although you are encouraged to do things |
| 764 | such as use the $color array to keep your HTML correctly themed, etc. |
| 765 | |
| 766 | If you want SquirrelMail to build your preferences page for you, |
| 767 | creating input forms and automatically saving users' settings, then |
| 768 | you should change the 'url' attribute in the options block you created |
| 769 | in step number 2 above to read as follows: |
| 770 | |
| 771 | 'url' => SM_PATH . 'src/options.php?optpage=plugin_demo', |
| 772 | |
| 773 | Now, you will need to use the "optpage_set_loadinfo" hook to tell |
| 774 | SquirrelMail about your new preferences page. In setup.php in the |
| 775 | squirrelmail_plugin_init_demo() function: |
| 776 | |
| 777 | $squirrelmail_plugin_hooks['optpage_set_loadinfo']['demo'] |
| 778 | = 'demo_optpage_loadinfo'; |
| 779 | |
| 780 | Assuming the function demo_optpage_loadinfo() calls another function |
| 781 | elsewhere called demo_optpage_loadinfo_do(), that function needs to |
| 782 | define values for four variables (make sure you test to see that it |
| 783 | is your plugin that is being called by checking the GET variable you |
| 784 | added to the url just above): |
| 785 | |
| 786 | global $optpage, $optpage_name, $optpage_file, |
| 787 | $optpage_loader, $optpage_loadhook; |
| 788 | if ($optpage == 'plugin_demo') |
| 789 | { |
| 790 | $optpage_name = "Favorite Color Preferences"; |
| 791 | $optpage_file = SM_PATH . 'plugins/demo/options.php'; |
| 792 | $optpage_loader = 'load_optpage_data_demo'; |
| 793 | $optpage_loadhook = 'optpage_loadhook_demo'; |
| 794 | } |
| 795 | |
| 796 | Now you are ready to build all of your options. In the file you |
| 797 | indicated for the variable $optpage_file above, you'll need to create |
| 798 | a function named the same as the value you used for $optpage_loader |
| 799 | above. In this example, the file plugins/demo/options.php should |
| 800 | have at least this function in it: |
| 801 | |
| 802 | function load_optpage_data_demo() |
| 803 | { |
| 804 | $optpage_data = array(); |
| 805 | $optpage_data['grps']['DEMO_PLUGIN'] = 'Demo Options'; |
| 806 | $optionValues = array(); |
| 807 | $optionValues[] = array( |
| 808 | 'name' => 'plugin_demo_favorite_color', |
| 809 | 'caption' => 'Please Choose Your Favorite Color', |
| 810 | 'type' => SMOPT_TYPE_STRLIST, |
| 811 | 'refresh' => SMOPT_REFRESH_ALL, |
| 812 | 'posvals' => array(0 => 'red', |
| 813 | 1 => 'blue', |
| 814 | 2 => 'green', |
| 815 | 3 => 'orange'), |
| 816 | 'save' => 'save_plugin_demo_favorite_color' |
| 817 | ); |
| 818 | $optpage_data['vals']['DEMO_PLUGIN'] = $optionValues; |
| 819 | return $optpage_data; |
| 820 | } |
| 821 | |
| 822 | For a detailed description of how you build these options, please read |
| 823 | step number 2 for the second method of adding options to an existing |
| 824 | preferences page above. Notice that the only difference here is in the |
| 825 | very first and last lines of this function where you are actually |
| 826 | creating and returning the options array instead of just adding onto it. |
| 827 | |
| 828 | That's all there is to it - SquirrelMail will create a preferences page |
| 829 | titled as you indicated for $optpage_name above, and other plugins |
| 830 | can even add extra options to this new preferences page. To do so, |
| 831 | they should use the hook name you specified for $optpage_loadhook above |
| 832 | and use the second method for adding option settings to existing |
| 833 | preferences pages described above. |
| 834 | |
| 835 | 4. Saving your options settings: if you used the second method in step |
| 836 | number 3 above, your settings will be saved automatically (or you can |
| 837 | define special functions to save special settings such as the |
| 838 | save_plugin_demo_favorite_color() function in the example described |
| 839 | above) and there is probably no need to follow this step. If you |
| 840 | created your own preferences page from scratch, you'll need to follow |
| 841 | this step. First, you need to register your plugin against the |
| 842 | "options_save" hook. In setup.php in the squirrelmail_plugin_init_demo() |
| 843 | function: |
| 844 | |
| 845 | $squirrelmail_plugin_hooks['options_save']['demo'] |
| 846 | = 'demo_save_options'; |
| 847 | |
| 848 | Assuming the function demo_save_options() calls another function |
| 849 | elsewhere called demo_save_options_do(), that function needs to grab |
| 850 | all of your POST and/or GET settings values and save them in the user's |
| 851 | preferences (for more about preferences, see that section below). Since |
| 852 | this is a generic hook called for all custom preferences pages, you |
| 853 | should always set "optpage" as a POST or GET variable with a string that |
| 854 | uniquely identifies your plugin: |
| 855 | |
| 856 | <input type="hidden" name="optpage" value="plugin_demo"> |
| 857 | |
| 858 | Now in your demo_save_options_do() function, do something like this: |
| 859 | |
| 860 | global $username, $data_dir, $optpage, $favorite_color; |
| 861 | if ($optpage == 'plugin_demo') |
| 862 | { |
| 863 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
| 864 | setPref($data_dir, $username, 'favorite_color', $favorite_color); |
| 865 | } |
| 866 | |
| 867 | Note that $favorite_color may not need to be globalized, although |
| 868 | experience has shown that some versions of PHP don't behave as expected |
| 869 | unless you do so. Even when you use SquirrelMail's built-in preferences |
| 870 | page generation functionality, you may still use this hook, although |
| 871 | there should be no need to do so. If you need to do some complex |
| 872 | validation routines, note that it might be better to do so in the file |
| 873 | you specified as the "$optpage_file" (in our example, that was the |
| 874 | plugins/demo/options.php file), since at this point, you can still |
| 875 | redisplay your preferences page. You could put code similar to this |
| 876 | in the plugins/demp/options.php file (note that there is no function; |
| 877 | this code needs to be executed at include time): |
| 878 | |
| 879 | global $optmode; |
| 880 | if ($optmode == 'submit') |
| 881 | { |
| 882 | // do something here such as validation, etc |
| 883 | if (you want to redisplay your preferences page) |
| 884 | $optmode = ''; |
| 885 | } |
| 886 | |
| 887 | |
| 888 | Preferences |
| 889 | ----------- |
| 890 | |
| 891 | Saving and retrieving user preferences is very easy in SquirrelMail. |
| 892 | SquirrelMail supports preference storage in files or in a database |
| 893 | backend, however, the code you need to write to manipulate preferences |
| 894 | is the same in both cases. |
| 895 | |
| 896 | Setting preferences: |
| 897 | |
| 898 | Setting preferences is done for you if you use the built-in facilities |
| 899 | for automatic options construction and presentation (see above). If |
| 900 | you need to manually set preferences, however, all you need to do is: |
| 901 | |
| 902 | global $data_dir, $username; |
| 903 | setPref($data_dir, $username, 'pref_name', $pref_value); |
| 904 | |
| 905 | Where "pref_name" is the key under which the value will be stored |
| 906 | and "pref_value" is a variable that should contain the actual |
| 907 | preference value to be stored. |
| 908 | |
| 909 | Loading preferences: |
| 910 | |
| 911 | There are two approaches to retrieving plugin (or any other) preferences. |
| 912 | You can grab individual preferences one at a time or you can add your |
| 913 | plugin's preferences to the routine that loads up user preferences at |
| 914 | the beginning of each page request. If you do the latter, making sure |
| 915 | to place your preference variables into the global scope, they will be |
| 916 | immediately available in all other plugin code. To retrieve a single |
| 917 | preference value at any time, do this: |
| 918 | |
| 919 | global $data_dir, $username; |
| 920 | $pref_value = getPref($data_dir, $username, 'pref_name', 'default value'); |
| 921 | |
| 922 | Where "pref_name" is the preference you are retrieving, "default_value" |
| 923 | is what will be returned if the preference is not found for this user, |
| 924 | and, of course, "pref_value" is the variable that will get the actual |
| 925 | preference value. |
| 926 | |
| 927 | To have all your preferences loaded at once when each page request is |
| 928 | made, you'll need to register a function against the "loading_prefs" hook. |
| 929 | For our "demo" plugin, in setup.php in the squirrelmail_plugin_init_demo() |
| 930 | function: |
| 931 | |
| 932 | $squirrelmail_plugin_hooks['loading_prefs']['demo'] |
| 933 | = 'demo_load_prefs'; |
| 934 | |
| 935 | Assuming the function demo_load_prefs() calls another function |
| 936 | elsewhere called demo_load_prefs_do(), that function just needs to |
| 937 | pull out any all all preferences you'll be needing elsewhere: |
| 938 | |
| 939 | global $data_dir, $username, $pref_value; |
| 940 | $pref_value = getPref($data_dir, $username, 'pref_name', 'default value'); |
| 941 | |
| 942 | Remember to globalize each preference, or this code is useless. |
| 943 | |
| 944 | |
| 945 | Internationalization |
| 946 | -------------------- |
| 947 | |
| 948 | Although this document may only be available in English, we sure hope that you |
| 949 | are thinking about making your plugin useful to the thousands of non-English |
| 950 | speaking SquirrelMail users out there! It is almost rude not to do so, and |
| 951 | it isn't much trouble, either. This document will only describe how you can |
| 952 | accomplish the internationalization of a plugin. For more general information |
| 953 | about PHP and SquirrelMail translation facilities, see: |
| 954 | |
| 955 | http://www.squirrelmail.org/wiki/wiki.php?LanguageTranslation |
| 956 | |
| 957 | The unofficial way to internationalize a plugin is to put all plugin output |
| 958 | into the proper format but to rely on the SquirrelMail translation facilities |
| 959 | for all the rest. If the plugin were really to get translated, you'd need |
| 960 | to make sure that all output strings for your plugin are either added to or |
| 961 | already exist in the main SquirrelMail locale files. |
| 962 | |
| 963 | The better way to make sure your plugin is translated is to create your own |
| 964 | locale files and what is called a "gettext domain" (see the link above for |
| 965 | more information). |
| 966 | |
| 967 | There are three basic steps to getting your plugins internationalized: put |
| 968 | all output into the proper format, switch gettext domains and create locale |
| 969 | files. |
| 970 | |
| 971 | 1. Putting plugin output into the correct format is quite easy. The hard |
| 972 | part is making sure you catch every last echo statement. You need to |
| 973 | echo text like this: |
| 974 | |
| 975 | echo _("Hello"); |
| 976 | |
| 977 | So, even in the HTML segments of your plugin files, you need to do this: |
| 978 | |
| 979 | <input type="submit" value="<?php echo _("Submit") ?>"> |
| 980 | |
| 981 | You can put any text you want inside of the quotes (you MUST use double |
| 982 | quotes!), including HTML tags, etc. What you should think carefully |
| 983 | about is that some languages may use different word ordering, so this |
| 984 | might be problematic: |
| 985 | |
| 986 | echo _("I want to eat a ") . $fruitName . _(" before noon"); |
| 987 | |
| 988 | Because some languages (Japanese, for instance) would need to translate |
| 989 | such a sentence to "Before noon " . $fruitName . " I want to eat", but |
| 990 | with the format above, they are stuck having to translate each piece |
| 991 | separately. You might want to reword your original sentence: |
| 992 | |
| 993 | echo _("This is what I want to eat before noon: ") . $fruitName; |
| 994 | |
| 995 | 2. By default, the SquirrelMail gettext domain is always in use. That |
| 996 | means that any text in the format described above will be translated |
| 997 | using the locale files found in the main SquirrelMail locale directory. |
| 998 | Unless your plugin produces no output or only output that is in fact |
| 999 | translated under the default SquirrelMail domain, you need to create |
| 1000 | your own gettext domain. The PHP for doing so is very simple. At |
| 1001 | the top of any file that produces any output, place the following code |
| 1002 | (again, using "demo" as the plugin name): |
| 1003 | |
| 1004 | bindtextdomain('demo', SM_PATH . 'plugins/demo/locale'); |
| 1005 | textdomain('demo'); |
| 1006 | |
| 1007 | Now all output will be translated using your own custom locale files. |
| 1008 | Please be sure to switch back to the SquirrelMail domain at the end |
| 1009 | of the file, or many of the other SquirrelMail files may misbehave: |
| 1010 | |
| 1011 | bindtextdomain('squirrelmail', SM_PATH . 'locale'); |
| 1012 | textdomain('squirrelmail'); |
| 1013 | |
| 1014 | Note that if, in the middle of your plugin file, you use any |
| 1015 | SquirrelMail functions that send output to the browser, you'll need |
| 1016 | to temporarily switch back to the SquirrelMail domain: |
| 1017 | |
| 1018 | bindtextdomain('squirrelmail', SM_PATH . 'locale'); |
| 1019 | textdomain('squirrelmail'); |
| 1020 | displayPageHeader($color, 'None'); |
| 1021 | bindtextdomain('demo', SM_PATH . 'plugins/demo/locale'); |
| 1022 | textdomain('demo'); |
| 1023 | |
| 1024 | Note that technically speaking, you only need to have one bindtextdomain |
| 1025 | call per file, you should always use it before every textdomain call, |
| 1026 | since PHP installations without gettext compiled into them will not |
| 1027 | function properly if you do not. |
| 1028 | |
| 1029 | 3. Finally, you just need to create your own locale. You should create |
| 1030 | a directory structure like this in the plugin directory: |
| 1031 | |
| 1032 | demo |
| 1033 | | |
| 1034 | ------locale |
| 1035 | | |
| 1036 | ------de_DE |
| 1037 | | | |
| 1038 | | ------LC_MESSAGES |
| 1039 | | |
| 1040 | ------ja_JP |
| 1041 | | |
| 1042 | ------LC_MESSAGES |
| 1043 | |
| 1044 | Create a directories such as de_DE for each language (de_DE is German, |
| 1045 | ja_JP is Japanese, etc. - check the SquirrelMail locale directory for |
| 1046 | a fairly comprehensive listing). Inside of each LC_MESSAGES directory |
| 1047 | you should place two files, one with your translations in it, called |
| 1048 | <plugin name>.po (in this case, "demo.po"), and one that is a compiled |
| 1049 | version of the ".po" file, called <plugin name>.mo (in this case, |
| 1050 | "demo.mo"). On most linux systems, there is a tool you can use to pull |
| 1051 | out most of the strings that you need to have translated from your PHP |
| 1052 | files into a sample .po file: |
| 1053 | |
| 1054 | xgettext --keyword=_ -d <plugin name> -s -C *.php |
| 1055 | |
| 1056 | --keyword option tells xgettext what your strings are enclosed in |
| 1057 | -d is the domain of your plugin which should be the plugin's name |
| 1058 | -s tells xgettext to sort the results and remove duplicate strings |
| 1059 | -C means you are translating a file with C/C++ type syntax (ie. PHP) |
| 1060 | *.php is all the files you want translations for |
| 1061 | |
| 1062 | Note, however, that this will not always pick up all strings, so you |
| 1063 | should double-check manually. Of course, it's easiest if you just keep |
| 1064 | track of all your strings as you are coding your plugin. Your .po file |
| 1065 | will now look something like: |
| 1066 | |
| 1067 | # SOME DESCRIPTIVE TITLE. |
| 1068 | # Copyright (C) YEAR Free Software Foundation, Inc. |
| 1069 | # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. |
| 1070 | # |
| 1071 | #, fuzzy |
| 1072 | msgid "" |
| 1073 | msgstr "" |
| 1074 | "Project-Id-Version: PACKAGE VERSION\n" |
| 1075 | "POT-Creation-Date: 2003-06-18 11:22-0600\n" |
| 1076 | "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" |
| 1077 | "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" |
| 1078 | "Language-Team: LANGUAGE <LL@li.org>\n" |
| 1079 | "MIME-Version: 1.0\n" |
| 1080 | "Content-Type: text/plain; charset=CHARSET\n" |
| 1081 | "Content-Transfer-Encoding: ENCODING\n" |
| 1082 | |
| 1083 | #: functions.php:45 |
| 1084 | msgid "Hello" |
| 1085 | msgstr "" |
| 1086 | |
| 1087 | #: functions.php:87 |
| 1088 | msgid "Favorite Color" |
| 1089 | msgstr "" |
| 1090 | |
| 1091 | You should change the header to look something more like: |
| 1092 | |
| 1093 | # Copyright (c) 1999-2003 The Squirrelmail Development Team |
| 1094 | # Roland Bauerschmidt <rb@debian.org>, 1999. |
| 1095 | msgid "" |
| 1096 | msgstr "" |
| 1097 | "Project-Id-Version: $Id: squirrelmail.po,v 1.10 2003/06/04 15:01:59 |
| 1098 | philippe_mingo Exp $\n" |
| 1099 | "POT-Creation-Date: 2003-01-21 19:21+0100\n" |
| 1100 | "PO-Revision-Date: 2003-01-21 21:01+0100\n" |
| 1101 | "Last-Translator: Juergen Edner <juergen.edner@epost.de>\n" |
| 1102 | "Language-Team: German <squirrelmail-i18n@lists.squirrelmail.net>\n" |
| 1103 | "MIME-Version: 1.0\n" |
| 1104 | "Content-Type: text/plain; charset=ISO-8859-1\n" |
| 1105 | "Content-Transfer-Encoding: 8bit\n" |
| 1106 | |
| 1107 | The most important thing to change here is the charset on the next to |
| 1108 | last line. You'll want to keep a master copy of the .po file and make |
| 1109 | a copy for each language you have a translation for. You'll need to |
| 1110 | translate each string in the .po file: |
| 1111 | |
| 1112 | msgid "Hello" |
| 1113 | msgstr "Guten Tag" |
| 1114 | |
| 1115 | After you're done translating, you can create the .mo file very simply |
| 1116 | by running the following command (available on most linux systems): |
| 1117 | |
| 1118 | msgfmt -o <plugin name>.mo <plugin name>.po |
| 1119 | |
| 1120 | In the case of the "demo" plugin: |
| 1121 | |
| 1122 | msgfmt -o demo.mo demo.po |
| 1123 | |
| 1124 | Please be sure that the .po and .mo files both are named exactly the |
| 1125 | same as the domain you bound in step 2 above and everything else works |
| 1126 | automatically. In SquirrelMail, go to Options -> Display Preferences |
| 1127 | and change your Language setting to see the translations in action! |
| 1128 | |
| 1129 | |
| 1130 | |
| 1131 | Documenting the Code (Optional) |
| 1132 | ------------------------------- |
| 1133 | |
| 1134 | If you wish, you can use phpdoc (Javadoc-style) comments, when documenting your |
| 1135 | code. |
| 1136 | |
| 1137 | If you follow the standards that are followed between Squirrelmail core & |
| 1138 | plugin developers, the resulted documentation can be included with the rest of |
| 1139 | the Squirrelmail code & API documentation. Specifically, in the page-level |
| 1140 | docblock, declare the package to be 'plugins', and the subpackage to be the |
| 1141 | name of your plugin. For instance: |
| 1142 | |
| 1143 | /** |
| 1144 | * demo.php |
| 1145 | * |
| 1146 | * Copyright (c) 2003 My Name <my-email-address> |
| 1147 | * Licensed under the GNU GPL. For full terms see the file COPYING. |
| 1148 | * |
| 1149 | * @package plugins |
| 1150 | * @subpackage demo |
| 1151 | */ |
| 1152 | |
| 1153 | The rest is up to you. Try to follow some common sense and document what is |
| 1154 | really needed. Documenting the code properly can be a big help not only to |
| 1155 | yourself, but to those who will take a look at your code, fix the bugs and even |
| 1156 | improve it, in the true open-source spirit that Squirrelmail was built upon. |
| 1157 | |
| 1158 | For more information about phpdocumentor and how to write proper-tagged |
| 1159 | comments, you are directed at: |
| 1160 | |
| 1161 | http://phpdocu.sourceforge.net/ |
| 1162 | |
| 1163 | |
| 1164 | |
| 1165 | PLUGIN STANDARDS AND REQUIREMENTS |
| 1166 | ================================= |
| 1167 | |
| 1168 | The SquirrelMail project has some important goals, such as avoiding the |
| 1169 | use of JavaScript, avoiding non-standard HTML tags, keeping file sizes |
| 1170 | small and providing the fastest webmail client on the Internet. As such, |
| 1171 | we'd like it if plugin authors coded with the same goals in mind that the |
| 1172 | core developers do. Common sense is always a good tool to have in your |
| 1173 | programming repertoire, but below is an outline of some standards that we |
| 1174 | ask you as a plugin developer to meet. Depending upon how far you bend |
| 1175 | these rules, we may not want to post your plugin on the SquirrelMail |
| 1176 | website... and of course, no one really wants your efforts to go to waste |
| 1177 | and for the SquirrelMail community to miss out on a potentially useful |
| 1178 | plugin, so please try to follow these guidelines as closely as possible. |
| 1179 | |
| 1180 | |
| 1181 | Small setup.php |
| 1182 | --------------- |
| 1183 | |
| 1184 | In order for SquirrelMail to remain fast and lean, we are now asking |
| 1185 | that all plugin authors remove all unnecessary functionality from setup.php |
| 1186 | and refactor it into another file. There are a few ways to accomplish |
| 1187 | this, none of which are difficult. At a minimum, you'll want to have the |
| 1188 | squirrelmail_plugin_init_<plugin name>() function in setup.php, and naturally, |
| 1189 | you'll need functions that are merely stubs for each hook that you are using. |
| 1190 | One (but not the only) way to do it is: |
| 1191 | |
| 1192 | function squirrelmail_plugin_init_demo() |
| 1193 | { |
| 1194 | global $squirrelmail_plugin_hooks; |
| 1195 | $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; |
| 1196 | } |
| 1197 | function plugin_demo_header() |
| 1198 | { |
| 1199 | include_once(SM_PATH . 'plugins/demo/functions.php'); |
| 1200 | plugin_demo_header_do(); |
| 1201 | } |
| 1202 | |
| 1203 | |
| 1204 | Internationalization |
| 1205 | -------------------- |
| 1206 | |
| 1207 | Q: What is more disappointing to users in France who would make good |
| 1208 | use of your plugin than learning that it is written entirely in English? |
| 1209 | A: Learning that they cannot send you a French translation file for your |
| 1210 | plugin. |
| 1211 | |
| 1212 | There are thousands of users out there whose native tongue is not English, |
| 1213 | and when you develop your plugin without going through the three simple steps |
| 1214 | needed to internationalize it, you are effectively writing them all off. |
| 1215 | PLEASE consider internationalizing your plugin! |
| 1216 | |
| 1217 | |
| 1218 | Developing with E_ALL |
| 1219 | --------------------- |
| 1220 | |
| 1221 | When you are developing your plugin, you should always have error reporting |
| 1222 | turned all the way up. You can do this by changing two settings in your |
| 1223 | php.ini and restarting your web server: |
| 1224 | |
| 1225 | display_errors = On |
| 1226 | error_reporting = E_ALL |
| 1227 | |
| 1228 | This way, you'll be sure to see all Notices, Warnings and Errors that your |
| 1229 | code generates (it's OK, really, it happens to the best of us... except me!). |
| 1230 | Please make sure to fix them all before you release the plugin. |
| 1231 | |
| 1232 | |
| 1233 | Compatibility with register_globals=Off |
| 1234 | --------------------------------------- |
| 1235 | |
| 1236 | Most sensible systems administrators now run their PHP systems with the |
| 1237 | setting "register_globals" as OFF. This is a prudent security setting, |
| 1238 | and as the SquirrelMail core code has long since been upgraded to work |
| 1239 | in such an environment, we are now requiring that all plugins do the same. |
| 1240 | Compatibility with this setting amounts to little more than explicitly |
| 1241 | gathering any and all variables you sent from a <form> tag as GET or POST |
| 1242 | values instead of just assuming that they will be placed in the global |
| 1243 | scope automatically. There is nothing more to do than this: |
| 1244 | |
| 1245 | global $favorite_color; |
| 1246 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
| 1247 | |
| 1248 | |
| 1249 | Extra Blank Lines |
| 1250 | ----------------- |
| 1251 | |
| 1252 | It may seem innocuous, but if you have any blank lines either before the |
| 1253 | first <?php tag or after the last ?> tag in any of your plugin files, you |
| 1254 | you will break SquirrelMail in ways that may seem entirely unrelated. For |
| 1255 | instance, this will often cause a line feed character to be included with |
| 1256 | email attachments when they are viewed or downloaded, rendering them useless! |
| 1257 | |
| 1258 | |
| 1259 | include_once |
| 1260 | ------------ |
| 1261 | |
| 1262 | When including files, please make sure to use the include_once() function |
| 1263 | and NOT include(), require(), or require_once(), since these all are much |
| 1264 | less efficient than include_once() and can have a cumulative effect on |
| 1265 | SquirrelMail performance. |
| 1266 | |
| 1267 | |
| 1268 | Version Reporting |
| 1269 | ----------------- |
| 1270 | |
| 1271 | In order for systems administrators to keep better track of your plugin and |
| 1272 | get upgrades more efficiently, you are requested to make version information |
| 1273 | available to SquirrelMail in a format that it understands. There are two |
| 1274 | ways to do this. Presently, we are asking that you do both, since we are |
| 1275 | still in a transition period between the two. This is painless, so please |
| 1276 | be sure to include it: |
| 1277 | |
| 1278 | 1. Create a file called "version" in the plugin directory. That file |
| 1279 | should have only two lines: the first line should have the name of |
| 1280 | the plugin as named on the SquirrelMail web site (this is often a |
| 1281 | prettified version of the plugin directory name), the second line |
| 1282 | must have the version and nothing more. So for our "demo" plugin, |
| 1283 | whose name on the web site might be something like "Demo Favorite |
| 1284 | Colors", the file plugins/demo/version should have these two lines: |
| 1285 | |
| 1286 | Demo Favorite Colors |
| 1287 | 1.0 |
| 1288 | |
| 1289 | 2. In setup.php, you should have a function called <plugin name>_version(). |
| 1290 | That function should return the version of your plugin. For the "demo" |
| 1291 | plugin, that should look like this: |
| 1292 | |
| 1293 | function demo_version() |
| 1294 | { |
| 1295 | return '1.0'; |
| 1296 | } |
| 1297 | |
| 1298 | |
| 1299 | Configuration Files |
| 1300 | ------------------- |
| 1301 | |
| 1302 | It is common to need a configuration file that holds some variables that |
| 1303 | are set up at install time. For ease of installation and maintenance, you |
| 1304 | should place all behavioral settings in a config file, isolated from the |
| 1305 | rest of your plugin code. A typical file name to use is "config.php". If |
| 1306 | you are using such a file, you should NOT include a file called "config.php" |
| 1307 | in your plugin distribution, but instead a copy of that file called |
| 1308 | "config.php.sample". This helps systems administrators avoid overwriting |
| 1309 | the "config.php" files and losing all of their setup information when they |
| 1310 | upgrade your plugin. |
| 1311 | |
| 1312 | |
| 1313 | Session Variables |
| 1314 | ----------------- |
| 1315 | |
| 1316 | In the past, there have been some rather serious issues with PHP sessions |
| 1317 | and SquirrelMail, and certain people have worked long and hard to ensure |
| 1318 | that these problems no longer occur in an extremely wide variety of OS/PHP/ |
| 1319 | web server environments. Thus, if you need to place any values into the |
| 1320 | user's session, there are some built-in SquirrelMail functions that you are |
| 1321 | strongly encouraged to make use of. Using them also makes your job easier. |
| 1322 | |
| 1323 | 1. To place a variable into the session: |
| 1324 | |
| 1325 | global $favorite_color; |
| 1326 | $favoriteColor = 'green'; |
| 1327 | sqsession_register($favorite_color, 'favorite_color'); |
| 1328 | |
| 1329 | Strictly speaking, globalizing the variable shouldn't be necessary, |
| 1330 | but certain versions of PHP seem to behave more predictably if you do. |
| 1331 | |
| 1332 | 2. To retrieve a variable from the session: |
| 1333 | |
| 1334 | global $favorite_color; |
| 1335 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_SESSION); |
| 1336 | |
| 1337 | 3. You can also check for the presence of a variable in the session: |
| 1338 | |
| 1339 | if (sqsession_is_registered('favorite_color')) |
| 1340 | // do something important |
| 1341 | |
| 1342 | 4. To remove a variable from the session: |
| 1343 | |
| 1344 | global $favorite_color; |
| 1345 | sqsession_unregister('favorite_color'); |
| 1346 | |
| 1347 | Strictly speaking, globalizing the variable shouldn't be necessary, |
| 1348 | but certain versions of PHP seem to behave more predictably if you do. |
| 1349 | |
| 1350 | |
| 1351 | Form Variables |
| 1352 | -------------- |
| 1353 | |
| 1354 | You are also encouraged to use SquirrelMail's built-in facilities to |
| 1355 | retrieve variables from POST and GET submissions. This is also much |
| 1356 | easier on you and makes sure that all PHP installations are accounted |
| 1357 | for (such as those that don't make the $_POST array automatically |
| 1358 | global, etc.): |
| 1359 | |
| 1360 | global $favorite_color; |
| 1361 | sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM); |
| 1362 | |
| 1363 | |
| 1364 | Files In Plugin Directory |
| 1365 | ------------------------- |
| 1366 | |
| 1367 | There are a few files that you should make sure to include when you build |
| 1368 | your final plugin distribution: |
| 1369 | |
| 1370 | 1. A copy of the file index.php from the main plugins directory. When |
| 1371 | working in your plugin directory, just copy it in like this: |
| 1372 | |
| 1373 | $ cp ../index.php . |
| 1374 | |
| 1375 | This will redirect anyone who tries to browse to your plugin directory |
| 1376 | to somewhere more appropriate. If you create other directories under |
| 1377 | your plugin directory, you may copy the file there as well to be extra |
| 1378 | safe. If you are storing sensitive configuration files or other data |
| 1379 | in such a directory, you could even include a .htaccess file with the |
| 1380 | contents "Deny From All" that will disallow access to that directory |
| 1381 | entirely (when the target system is running the Apache web server). |
| 1382 | Keep in mind that not all web servers will honor an .htaccess file, so |
| 1383 | don't depend on it for security. Make sure not to put such a file in |
| 1384 | your main plugin directory! |
| 1385 | |
| 1386 | 2. A file that describes your plugin and offers detailed instructions for |
| 1387 | configuration or help with troubleshooting, etc. This file is usually |
| 1388 | entitled "README". Some useful sections to include might be: |
| 1389 | |
| 1390 | Plugin Name and Author |
| 1391 | Current Version |
| 1392 | Plugin Features |
| 1393 | Detailed Plugin Description |
| 1394 | How-to for Plugin Configuration |
| 1395 | Change Log |
| 1396 | Future Ideas/Enhancements/To Do List |
| 1397 | |
| 1398 | 3. A file that explains how to install your plugin. This file is typically |
| 1399 | called "INSTALL". If you do not require any special installation |
| 1400 | actions, you can probably copy one from another plugin or use this as |
| 1401 | a template: |
| 1402 | |
| 1403 | Installing the Demo Plugin |
| 1404 | ========================== |
| 1405 | |
| 1406 | 1) Start with untaring the file into the plugins directory. |
| 1407 | Here is a example for the 1.0 version of the Demo plugin. |
| 1408 | |
| 1409 | $ cd plugins |
| 1410 | $ tar -zxvf demo-1.0-1.4.0.tar.gz |
| 1411 | |
| 1412 | 2) Change into the demo directory, copy config.php.sample |
| 1413 | to config.php and edit config.php, making adjustments as |
| 1414 | you deem necessary. For more detailed explanations about |
| 1415 | each of these parameters, consult the README file. |
| 1416 | |
| 1417 | $ cd demo |
| 1418 | $ cp config.php.sample config.php |
| 1419 | $ vi config.php |
| 1420 | |
| 1421 | |
| 1422 | 3) Then go to your config directory and run conf.pl. Choose |
| 1423 | option 8 and move the plugin from the "Available Plugins" |
| 1424 | category to the "Installed Plugins" category. Save and exit. |
| 1425 | |
| 1426 | $ cd ../../config/ |
| 1427 | $ ./conf.pl |
| 1428 | |
| 1429 | |
| 1430 | Upgrading the Demo Plugin |
| 1431 | ========================= |
| 1432 | |
| 1433 | 1) Start with untaring the file into the plugins directory. |
| 1434 | Here is a example for the 3.1 version of the demo plugin. |
| 1435 | |
| 1436 | $ cd plugins |
| 1437 | $ tar -zxvf demo-3.1-1.4.0.tar.gz |
| 1438 | |
| 1439 | |
| 1440 | 2) Change into the demo directory, check your config.php |
| 1441 | file against the new version, to see if there are any new |
| 1442 | settings that you must add to your config.php file. |
| 1443 | |
| 1444 | $ diff -Nau config.php config.php.sample |
| 1445 | |
| 1446 | Or simply replace your config.php file with the provided sample |
| 1447 | and reconfigure the plugin from scratch (see step 2 under the |
| 1448 | installation procedure above). |
| 1449 | |
| 1450 | |
| 1451 | COMPATIBILITY WITH OLDER VERSIONS OF SQUIRRELMAIL |
| 1452 | ================================================= |
| 1453 | |
| 1454 | Whenever new versions of SquirrelMail are released, there is always a |
| 1455 | considerable lag time before it is widely adopted. During that transitional |
| 1456 | time, especially when the new SquirrelMail version contains any architectural |
| 1457 | and/or functional changes, plugin developers are put in a unique and very |
| 1458 | difficult position. That is, there will be people running both the old and |
| 1459 | new versions of SquirrelMail who want to use your plugin, and you will |
| 1460 | probably want to accomodate them both. |
| 1461 | |
| 1462 | The easiest way to keep both sides happy is to keep two different versions |
| 1463 | of your pluign up to date, one that runs under the older SquirrelMail, and |
| 1464 | one that requires the newest SquirrelMail. This is inconvenient, however, |
| 1465 | especially if you are continuing to develop the plugin. Depending on the |
| 1466 | changes the SquirrelMail has implemented in the new version, you may be able |
| 1467 | to include code that can auto-sense SquirrelMail version and make adjustments |
| 1468 | on the fly. There is a function available to you for determining the |
| 1469 | SquirrelMail version called check_sm_version() and it can be used as such: |
| 1470 | |
| 1471 | check_sm_version(1, 4, 0) |
| 1472 | |
| 1473 | This will return TRUE if the SquirrelMail being used is at least 1.4.0, and |
| 1474 | FALSE otherwise. |
| 1475 | |
| 1476 | As this document is written, we are in a transition period between versions |
| 1477 | 1.2.11 and 1.4.0. There is a plugin called "Compatibilty" that is intended |
| 1478 | for use by plugin authors so they can develop one version of their plugin |
| 1479 | and seamlessly support both 1.2.x and 1.4.x SquirrelMail installations. For |
| 1480 | more information about how to use the "Compatibility" plugin, download it and |
| 1481 | read its README file or see: |
| 1482 | |
| 1483 | http://www.squirrelmail.org/wiki/wiki.php?PluginUpgrading |
| 1484 | |
| 1485 | |
| 1486 | REQUESTING NEW HOOKS |
| 1487 | ==================== |
| 1488 | |
| 1489 | It's impossible to foresee all of the places where hooks might be useful |
| 1490 | (it's also impossible to put in hooks everywhere!), so you might need to |
| 1491 | negotiate the insertion of a new hook to make your plugin work. In order |
| 1492 | to do so, you should post such a request to the squirrelmail-devel mailing |
| 1493 | list. |
| 1494 | |
| 1495 | |
| 1496 | HOW TO RELEASE YOUR PLUGIN |
| 1497 | ========================== |
| 1498 | |
| 1499 | As long as you've consulted the list of plugin standards and done your |
| 1500 | best to follow them, there's little standing in the way of great fame as an |
| 1501 | official SquirrelMail plugin developer. |
| 1502 | |
| 1503 | 1. Make a distribution file. There is a convenient Perl script in |
| 1504 | the plugins directory that will help you do this: |
| 1505 | |
| 1506 | make_archive.pl -v demo 1.0 1.4.0 |
| 1507 | |
| 1508 | -v is optional and indicates that the script should run in verbose mode |
| 1509 | demo is the name of your plugin |
| 1510 | 1.0 is the version of your plugin |
| 1511 | 1.4.0 is the version of SquirrelMail that is required to run your plugin |
| 1512 | |
| 1513 | You can also create the distribution file manually in most *nix |
| 1514 | environments by running this command from the plugins directory (NOT |
| 1515 | your plugin directory): |
| 1516 | |
| 1517 | $ tar czvf demo-1.0-1.4.0.tar.gz demo |
| 1518 | |
| 1519 | Where "demo" is the name of your plugin, "1.0" is the version of |
| 1520 | your plugin, and "1.4.0" is the version of SquirrelMail required |
| 1521 | to use your plugin. |
| 1522 | |
| 1523 | 2. Consult the SquirrelMail web site for contact information for the |
| 1524 | Plugins Team Leaders, to whom you should make your request. If they |
| 1525 | do not respond, you should feel free to ask for help contacting them |
| 1526 | on the squirrelmail-plugins mailing list. |
| 1527 | |
| 1528 | http://www.squirrelmail.org/wiki/wiki.php?SquirrelMailLeadership |
| 1529 | |