for you to use when including other files from the SquirrelMail core,
your own plugin, or other plugins, should the need arise. If any of
your plugin files are requested directly from the client browser,
-you will need to define this constant before you do anything else:
+you will need to include the SquirrelMail initialization file which is present
+since SquirrelMail 1.5.2.
- define('SM_PATH', '../../');
+The SquirrelMail initialization file which is located in include/init.php does
+take care of setting up the session, defining the constants like SM_PATH and
+it take care of including a minimum set of required files.
-Files are included like this:
+The files which are included depends on which file the hook operates on.
+For all hook locations the following files are included:
- include_once(SM_PATH . 'include/validate.php');
+ require(SM_PATH . 'functions/global.php');
+ require(SM_PATH . 'config/config.php');
+ require(SM_PATH . 'functions/plugin.php');
+ require(SM_PATH . 'include/constants.php');
+ require(SM_PATH . 'include/languages.php');
+ require(SM_PATH . 'functions/display_messages.php' );
+ require(SM_PATH . 'functions/page_header.php');
+ require(SM_PATH . 'functions/html.php');
+
+Except login.php also the following files are included:
+ require(SM_PATH . 'functions/prefs.php');
+
+ require(SM_PATH . 'functions/db_prefs.php');
+OR
+ require(SM_PATH . 'functions/file_prefs.php');
+(dependent of the configured preference backend)
+
+For all files except login.php and redirect.php also the following files are
+included:
+ require(SM_PATH . 'functions/strings.php');
+ require(SM_PATH . 'functions/auth.php');
+
+Because the use of "require" in include/init.php your plugin will fail if it
+tries to include the file in the plugin as well.
+Be aware of that.
+
+To include the init.php file add the following in your plugin:
+
+ /**
+ * Include the SquirrelMail initialization file.
+ */
+ require('../../include/init.php');
+
+Other files then the files mentioned above can be included by your plugin
+like this:
+
+ include_once(SM_PATH . 'functions/imap_general.php');
When including files, please make sure to use the include_once() function
-and NOT include(), require(), or require_once(), since these all are much
-less efficient than include_once() and can have a cumulative effect on
-SquirrelMail performance.
+and NOT include(), require() because they can cause fatal errors when other
+plugins or SquirrelMail files include the same file.
+If you use require_once() instead of include_once() then if something cause
+wrong with the include then php will raise a fatal error. That's the reason
+plugins MUST use include_once() instead of require_once().
The files that you may need to include in a plugin will vary greatly
depending upon what the plugin is designed to do. For files that are
-requested directly by the client browser, we strongly recommend that
-you include the file include/validate.php, since it will set up the
-SquirrelMail environment automatically. It will ensure the the user
-has been authenticated and is currently logged in, load all user
-preferences, include internationalization support, call stripslashes()
-on all incoming data (if magic_quotes_gpc is on), and initialize and
-include all other basic SquirrelMail resources and functions. You may
-see other plugins that directly include other SquirrelMail files, but
+requested directly by the client browser, you MUST includey the file
+ include/init.php
+, since it will set up the SquirrelMail environment automatically.
+It will ensure the the user has been authenticated and is currently logged in,
+load all user preferences, include internationalization support,
+call stripslashes() on all incoming data (if magic_quotes_gpc is on), and
+initialize and include all other basic SquirrelMail resources and functions.
+You may see other plugins that directly include other SquirrelMail files, but
that is no longer necessary and is a hold-over from older SquirrelMail
versions.
List of files, that are included by include/validate.php (If SquirrelMail
-version is not listed, files are included from v.1.3.2.):
+version is not listed, files are included from v.1.3.2.). This table is
+specific to SquirrelMail 1.3.2 - 1.5.1. Script layout was changed in 1.5.2.
1. class/mime.class.php
1.1. class/mime/Rfc822Header.class.php
1.2. class/mime/MessageHeader.class.php
1.7. class/mime/Language.class.php
1.8. class/mime/ContentType.class.php
2. functions/global.php
- * fixes differences between php 4.0.x and 4.1+ globals (only in 1.4.x).
+ * fixes differences between php 4.0.x and 4.1+ globals (only in 1.4.x).
* undoes magic_quotes_gpc=on sanitizing
* sets $PHP_SELF (since 1.5.1)
* starts session
7.1. include/validate.php
7.2. functions/prefs.php
7.2.1. functions/global.php (sqgetGlobalVar() function)
- 7.2.2. functions/plugin.php (do_hook_function() function,,
+ 7.2.2. functions/plugin.php (do_hook_function() function,,
since 1.4.4 and 1.5.1, see 7.3)
7.2.3. $prefs_backend (only in 1.4.3 and 1.5.0)
do_hook_function('prefs_backend') (since 1.4.4 and 1.5.1)
7.3. functions/plugin.php
7.3.1. functions/global.php (from 1.4.0 and 1.5.0)
7.3.2. functions/prefs.php (from 1.5.1)
- 7.3.3. plugins/*/setup.php files for enabled plugins.
+ 7.3.3. plugins/*/setup.php files for enabled plugins.
* starts all squirrelmail_plugin_init_pluginname functions
7.4. functions/constants.php
7.5. do_hook('loading_prefs')
8.4. functions/global.php
9. functions/prefs.php (already loaded. see 7.2)
-Since SquirrelMail 1.5.1 functions/global.php file must be loaded before
-setting any own global variables. If variables are set before loading
-functions/global.php library, they can be corrupted in PHP register_globals=On
+In SquirrelMail 1.4.7+ and 1.5.1 functions/global.php file must be loaded before
+setting any own global variables. If variables are set before loading
+functions/global.php library, they can be corrupted in PHP register_globals=On
setups.
&% options_identities_renumber functions/identity.php do_hook
special_mailbox functions/imap_mailbox.php hook_func
% rename_or_delete_folder functions/imap_mailbox.php hook_func
+ folder_status (since 1.5.1) functions/imap_mailbox.php hook_func
+ functions/imap_general.php hook_func
mailbox_index_before functions/mailbox_display.php do_hook
mailbox_form_before functions/mailbox_display.php do_hook
mailbox_index_after functions/mailbox_display.php do_hook
compose_button_row src/compose.php do_hook
compose_send src/compose.php do_hook
compose_send_after src/compose.php do_hook
+ configtest (since 1.5.2) src/configtest.php boolean_hook
folders_bottom src/folders.php do_hook
help_top src/help.php do_hook
help_chapter src/help.php do_hook
search_after_form src/search.php do_hook
search_bottom src/search.php do_hook
logout src/signout.php do_hook
+ message_body (since 1.5.2) src/view_html.php do_hook
+ message_body (since 1.5.2) src/view_text.php do_hook
webmail_top src/webmail.php do_hook
webmail_bottom src/webmail.php concat_hook
logout_above_text src/signout.php concat_hook
(!) Compose Form
----------------
-The compose_form hook allows plugins to insert their own code into
+The compose_form hook allows plugins to insert their own code into
the form tag for the main message composition HTML form. Usually
plugins will want to insert some kind of code in an onsubmit event
handler. In order to allow more than one plugin to do so, all plugins
using this hook to add some onsubmit code need to add that code (without
-the enclosing attribute name and quotes) as a new array entry to the
+the enclosing attribute name and quotes) as a new array entry to the
global $compose_onsubmit array. The code should use "return false"
if the plugin has found a reason to stop form submission, otherwise,
it should DO NOTHING (that is, please do not use "return true", as that
will prevent other plugins from using the onsubmit handler). SquirrelMail
itself will insert a final "return true". All onsubmit code will be
-enclosed in double quotes by SquirrelMail, so plugins need to quote
+enclosed in double quotes by SquirrelMail, so plugins need to quote
accordingly if needed. For example:
global $compose_onsubmit;
global $compose_onsubmit;
$compose_onsubmit[] = ' if (somevar == \'no\') { alert(\\"Sorry\\"); return false; }';
-Any other form tag additions by a plugin (beside onsubmit event code) can
+Any other form tag additions by a plugin (beside onsubmit event code) can
currently be echoed directly to the browser.
(SquirrelMail 1.4.6+ or 1.5.1+)
[0] = hook name (always "options_identities_process")
- [1] = action (hook is used only in 'update' action and any custom
- action added to form with option_identities_table and
+ [1] = action (hook is used only in 'update' action and any custom
+ action added to form with option_identities_table and
option_identities_buttons hooks)
[2] = processed identity number
. 'YOUR CODE HERE' . '</td></tr>' . "\n";
}
- First hook argument was modified in 1.4.5/1.5.1. In SquirrelMail 1.4.1-1.4.4
- and 1.5.0 argument contains only background color. You should use
+ First hook argument was modified in 1.4.5/1.5.1. In SquirrelMail 1.4.1-1.4.4
+ and 1.5.0 argument contains only background color. You should use
<tr bgcolor="<?php echo $args[0]; ?>"> in these SquirrelMail versions.
options_identities_buttons
. '" value="Press Me" />';
}
- Input element should use 'smaction[action_name][identity_no]' value in
+ Input element should use 'smaction[action_name][identity_no]' value in
'name' attribute, if you want to process your button actions in
SquirrelMail 1.4.6+ and 1.5.1+ options_identity_process hook.
the top of any file that produces any output, place the following code
(again, using "demo" as the plugin name):
- bindtextdomain('demo', SM_PATH . 'plugins/demo/locale');
+ bindtextdomain('demo', SM_PATH . 'locale');
textdomain('demo');
Now all output will be translated using your own custom locale files.
bindtextdomain('squirrelmail', SM_PATH . 'locale');
textdomain('squirrelmail');
displayPageHeader($color, 'None');
- bindtextdomain('demo', SM_PATH . 'plugins/demo/locale');
+ bindtextdomain('demo', SM_PATH . 'locale');
textdomain('demo');
Note that technically speaking, you only need to have one bindtextdomain
since PHP installations without gettext compiled into them will not
function properly if you do not.
- 3. Finally, you just need to create your own locale. You should create
- a directory structure like this in the plugin directory:
+ 3. Finally, you just need to create your own locale. There is a directory
+ structure like this in the locale directory:
- demo
- |
- ------locale
- |
- ------de_DE
- | |
- | ------LC_MESSAGES
+ locale
+ |
+ ------de_DE
+ | |
+ | ------LC_MESSAGES
+ |
+ ------ja_JP
|
- ------ja_JP
- |
- ------LC_MESSAGES
-
- Create a directories such as de_DE for each language (de_DE is German,
- ja_JP is Japanese, etc. - check the SquirrelMail locale directory for
- a fairly comprehensive listing). Inside of each LC_MESSAGES directory
- you should place two files, one with your translations in it, called
- <plugin name>.po (in this case, "demo.po"), and one that is a compiled
- version of the ".po" file, called <plugin name>.mo (in this case,
- "demo.mo"). On most linux systems, there is a tool you can use to pull
- out most of the strings that you need to have translated from your PHP
- files into a sample .po file:
+ ------LC_MESSAGES
+
+ There is a directory such as de_DE for each language (de_DE is German,
+ ja_JP is Japanese, etc.). Inside of each LC_MESSAGES directory you should
+ place two files; one with your translations in it, called <plugin name>.po
+ (in this case, "demo.po"), and one that is a compiled version of the ".po"
+ file, called <plugin name>.mo (in this case, "demo.mo"). On most linux
+ systems, there is a tool you can use to pull out most of the strings that
+ you need to have translated from your PHP files into a sample .po file:
xgettext --keyword=_ -d <plugin name> -s -C *.php
You should change the header to look something more like:
- # Copyright (c) 1999-2005 The SquirrelMail Project Team
+ # Copyright (c) 1999-2006 The SquirrelMail Project Team
# Roland Bauerschmidt <rb@debian.org>, 1999.
# $Id$
msgid ""
global $favorite_color;
sqgetGlobalVar('favorite_color', $favorite_color, SQ_FORM);
-SquirrelMail 1.5.1+ cleans globals in functions/global.php library. If
-plugin depends on PHP register_globals=On and loads this library, it will
+SquirrelMail 1.5.1+ cleans globals in functions/global.php library. If
+plugin depends on PHP register_globals=On and loads this library, it will
be broken.
projects / squirrelmail.git / blobdiff