7. Customizing SquirrelMail

SquirrelMail can be customized in a couple of ways, both to fit your system better and by changing some of the visual appearance. This chapter provides information about how to that.

7.1 Plugins

What is a plugin?

SquirrelMail is a modular system, wherein its functionality can be extended with extra features provided by various plugins. The plugins may be downloaded from various sources, one of them being the SquirrelMail Project's official plugin page.

Read the plugin's documentation and requirements to find out if this is a plugin that might be used in your setup. Sometimes you might need to uncompress the plugin package to be able to read the full documentation about it.

Plugins available to SquirrelMail must be stored in the SquirrelMail plugins directory. Each plugin uses its own subdirectory therein.

Installing a plugin

Installation of a new plugin is done it in a number of steps described below.

1. Uncompressing
2. Configurating
3. Enabling
4. Testing

Uncompressing a plugin

Download the plugin package, save it in /[path to SquirrelMail]/plugins/ and uncompress it. This should create a new directory with the uncompressed plugin in it. Obviously, you have to substitute [path to SquirrelMail] with the path used at your system. Here's an example:

cd /var/www/squirrelmail/plugins/
tar -xzvf newplugin-1.0.tar.gz

Configuring a plugin

Every plugin should come with a README and/or INSTALL file (and maybe some other documentation as well) which should always be read before enabling the plugin. There might be some extra setup steps needed, such as configuring or patching, that are specific to that plugin or your system, and those steps are described there. Any dependencies, such as special libraries, should also be listed in the plugin documentation. However, many plugins require no additional configuration.

Some plugins depend on the Compatibility plugin, but it might be important which version of the Compatibility plugin is used. The wiki provides more information as a complement to the plugin's documentation.

Enabling or disabling a plugin

There are two ways to enable or disable a plugin: the configuration script tool, or to edit the configuration manually. Using the configuration script is recommended.

Using the configuration script

Go to the main SquirrelMail directory and run the configuration script, by executing;

cd /[path to SquirrelMail]/
config/conf.pl

Select the menu option "8. Plugins". This option displays all plugins present in the directory plugins/ divided in two categories: installed and available. The installed category lists plugins that are currently enabled, and the available category lists plugins that are not currently enabled but are available for use. If you correctly uncompressed the plugin in the right place, it should be listed among the available plugins.

SquirrelMail Configuration : Read: config.php (1.4.0)
---------------------------------------------------------
Plugins
  Installed Plugins
    1. abook_take
    2. delete_move_next
    3. listcommands
    4. message_details

  Available Plugins:
    5. administrator
    6. bug_report
    7. calendar
    8. filters
    9. fortune
    10. info
    11. mail_fetch
    12. newmail
    13. newplugin
    14. sent_subfolders
    15. spamcop
    16. squirrelspell
    17. translate

R   Return to Main Menu
C   Turn color on
S   Save data
Q   Quit

Command >>

Each plugin has a number written next to its name. If you enter that number on the command line, the corresponding plugin is enabled or disabled. Don.t forget to save your changes by entering "S" at the command line.

Manually editing the configuration file

Find the SquirrelMail configuration file config.php file (usually located in /[path to SquirrelMail]/config/. Edit it using your favorite text editor, and add a line similar to this:

$plugins[0] = 'newplugin';

The example above will add "newplugin" as the first plugin (index zero). There might already be other plugins installed, and if that is the case, make sure to change the zero to the first available plugin index number, since two plugins aren't allowed to share index number.

Since SquirrelMail 1.5.2 you also need to edit the file plugin_hooks.php (usually located in /[path to SquirrelMail]/config/. Inside of that file, you must add all of the plugin hook registration points that are listed in the plugin's setup.php file, inside the squirrelmail_plugin_init_[plugin name]() function.

Make sure that there is no trailing end of line character and save the configuration.

Testing a plugin

Test the plugin to make sure that it works. This step is almost always successful, but if it isn't you may need to get support. Consult the plugin documentation to find out how to get the support, since it might vary depending on the plugin. It's usually a good idea to install, enable, and test one plugin at a time, since some plugins might not go well with the used system setup or other installed plugins.

Creating a plugin

For information about how to code plugins, see the the SquirrelMail Developer's Manual.

7.2 Site customizations

There are configuration options dealing with customizing SquirrelMail to your site available in the configuration tool under "1. Organization Preferences". For those who prefer manual configuration the same configuration options are available under the /*** Organization preferences ***/ headline.

There's also information about embedding the login form in other web pages to be found at the wiki page about embedding the login form.

TODO: Custom login page. Site control with the vlogin plugin.

7.3 Themes and Styles

TODO: This section has to rewritten with the changes, such as templates, in 1.5.2 when that version is released.

SquirrelMail users are able to customize the look of the interface by selecting a custom theme and the font style. The configuration options dealing with customizing SquirrelMail themes and styles available in the configuration tool under "5. Themes". For those who prefer manual configuration the same configuration options are available under * Themes.

SquirrelMail themes define interface colors. Each theme is a set of 17 or more colors.

Creating your own theme is very simple. Just go into the themes/ directory and create a file called yourtheme_theme.php. You then need to create an array with 17 elements (0-16). Below is a theme template followed by a description of what the different entries are for. Replace each "xxxxxx" with whatever HTML hex color code that you want for that element.

<?php

/**
 * My Theme
 *
 * Author: My name
 * Date:   Today's date
 *
 * Optional description
 */

global $color;
$color[0]   = '#xxxxxx';
$color[1]   = '#xxxxxx';
$color[2]   = '#xxxxxx';
$color[3]   = '#xxxxxx';
$color[4]   = '#xxxxxx';
$color[5]   = '#xxxxxx';
$color[6]   = '#xxxxxx';
$color[7]   = '#xxxxxx';
$color[8]   = '#xxxxxx';
$color[9]   = '#xxxxxx';
$color[10]  = '#xxxxxx';
$color[11]  = '#xxxxxx';
$color[12]  = '#xxxxxx';
$color[13]  = '#xxxxxx';
$color[14]  = '#xxxxxx';
$color[15]  = '#xxxxxx';
$color[16]  = '#xxxxxx';

Here are descriptions of what the different entries in the array are colors of. The letter after the number denotes "B" for background and "F" for foreground colors.

Next all you have to do is run SquirrelMail configuration utility and add the theme to the list of themes available to you.

It's also possible to provide a style sheet to be included on every page. That's useful for specifying a site-wide font or other characteristics. More information about this is available at the wiki page about style sheets.

7.4 Internationalization

SquirrelMail interface can be used with different languages. Default language can be set in SquirrelMail configuration utility. User can select other language in Options > Display Preferences. In SquirrelMail 1.4.5/1.5.1 or later administrator can set default language to empty string. Then interface will try to detect preferred translation from browser's preferred language setting.

SquirrelMail implements translations with gettext functions. Interface can use PHP gettext extension or internal gettext implementation. If PHP gettext extension is used, it might require a special web server setup. On Linux gettext functions work only when appropriate system locales are available. On BSD you should be able to set LC_ALL environment variable in PHP script. There are some differences between GNU Gettext and Solaris Gettext implementations.

Supported character sets

SquirrelMail displays interface in character set that depends on selected translation. If SquirrelMail has to display email written in other charset, interface uses special decoding functions that convert email to html codes that can display foreign symbols in selected character set.

Stock SquirrelMail installation supports following charset decoding functions:

• cp1250 (windows-1250) - since 1.4.3 and 1.5.0
• cp1251 (windows-1251)
• cp1252 (windows-1252) - since 1.4.3 and 1.5.0
• cp1253 (windows-1253)
• cp1254 (windows-1254)
• cp1255 (windows-1255) - since 1.4.3 and 1.5.0
• cp1256 (windows-1256) - since 1.4.3 and 1.5.0
• cp1257 (windows-1257)
• cp1258 (windows-1258) - since 1.4.3 and 1.5.0
• cp855 (ibm855) - since 1.4.3 and 1.5.0
• cp866 (ibm866) - since 1.4.3 and 1.5.0
• iso-8859-1
• iso-8859-2
• iso-8859-3 - since 1.4.3 and 1.5.0
• iso-8859-4
• iso-8859-5
• iso-8859-6 - since 1.4.3 and 1.5.0
• iso-8859-7
• iso-8859-8 - since 1.4.3 and 1.5.0
• iso-8859-9
• iso-8859-10 - since 1.4.3 and 1.5.0
• iso-8859-11 - since 1.4.3 and 1.5.0
• iso-8859-13
• iso-8859-14 - since 1.4.3 and 1.5.0
• iso-8859-15
• iso-8859-16 - since 1.4.3 and 1.5.0
• iso-ir-111 - since 1.4.3 and 1.5.0
• koi8-r
• koi8-u - since 1.4.1 and 1.5.0
• ns-4551_1
• tis-620 - since 1.4.3 and 1.5.0
• us-ascii - since 1.4.4
• utf-8 - two and three byte characters are supported since 1.4.0. Four byte characters are supported since 1.4.4 and 1.5.1. Five and six byte character decoding is available since 1.4.4 and 1.5.1, but not enabled by default.

Decoding functions might break in some SquirrelMail versions, if PHP mbstring.func_overload setting is enabled.

big-5, euc-kr and gb2312 characters can be displayed by Chinese and Korean translations that use those character sets. Japanese translation can display iso-2022-jp, euc-jp and shiftjis character sets. Other Eastern characters will be displayed correctly only when character codes match big-5, euc-kr or gb2312 character sets.

Other character sets can be decoded with extra decoding library functions. These functions are loaded automatically since 1.4.4 and 1.5.1, if appropriate files are present in functions/decode directory.

Message composition

SquirrelMail can create emails that use character set defined in user's translation. Composed email must use symbols that are supported by selected charset. If unsupported symbols are used, browser might use different character set or html entities instead of entered characters.

Different character set can be used only with US English translation. Administrator can set that character set in SquirrelMail 1.4.5/1.5.1 configuration utility. Users can also select different character set, if the Custom Charset plugin is installed.

7.5 Personal and shared address books

SquirrelMail supports multiple address book backends. Backends can be configured to provide access to address books that store entries visible to one user or to group of users or to all users that use the same SquirrelMail installation.

SquirrelMail comes with support for address books in its own flat file format, any database supported by the PHP PDO or Pear DB abstraction layers, as well as LDAP.

LDAP address books are read-only in SquirrelMail versions until 1.5.2. In version 1.5.2 and up, you can configure a writeable LDAP address book. The listing of addresses in a LDAP directory is available only when users search for addresses unless the listing configuration attribute is set for the LDAP server in SquirrelMail 1.5.2 and above or you add the following to the config/config_local.php file in SquirrelMail versions 1.4.23 to (but not including) 1.5.0:

$ldap_abook_allow_listing = TRUE;

In earlier versions, you'd need to make a small change to the functions/abook_ldap_server.php file in the list_addr() function near the bottom of the file (see instructions in the comments for that function). NOTE: you should exercise caution enabling the listing of large or public LDAP address book backends. Also note that the maxrows configuration setting for the LDAP server will limit the number of entries that are returned when listing it.

Global address book is address book that can be shared between users. Global address books can be configured in SquirrelMail since 1.4.4 version. Before than admin had to modify functions/addressbook.php file. There is a typo in 1.4.4 code and if you want to have writeable global address books, you should apply patch or use newer SquirrelMail version. See http://squirrelmail.org/wiki/KnownBugs

If admin wants to use different backend for address book storage (IMSP, personal LDAP address books, sticky notes attached to server), SquirrelMail 1.4.5 and 1.5.1 provide hooks that allow plugins to attach their own functions during address book initiation and admin needs only a plugin that can interact with used data storage system. Older SquirrelMail versions need two extra hooks in functions/addressbook.php. Current backend implementation is limited to standard SquirrelMail address book format.

How to use shared file based address book in SquirrelMail.

1. Get SquirrelMail 1.4.4, 1.5.1, or any later version.

2. If you want to use a writable address book in 1.4.4, get a patch that fixes the address book form.

3. Create address book file. SquirrelMail address book uses CSV format with | symbol as delimiter.

first field is nickname second field - name third field - surname forth field - email fifth field - additional information

for example:

test|Testname|Testsurname|[email protected]|testinfo

4. If you want a writable address book, the file must be writable by the user that the web server runs as.

5. After you have created address book file, go to SquirrelMail configuration utility, select 6. Address Books option and configure address book in 3. Global file address book.

If you enter only address book file name, system assumes that address book is in data directory. For example: global_abook. If you use data directory to store global address book, remember that personal address books use .abook suffix. You should not use global address book file with same suffix, unless you understand what you are doing.

If you enter full path, system uses full path. For example: /var/lib/squirrelmail/global_abook

If your configuration option contains slashes, but does not look like full path, system assumes path relative to SquirrelMail top directory.

If you want to use global file based address book in older SquirrelMail versions, take a look at functions/addressbook.php file. It contains some comments that explain how to do that without configuration utility.

Also see the address book format.