Multilogin plugin for SquirrelMail
==================================
Ver 2.4, 2008/07/06


Copyright (c) 2003 Benoit Bourdin <bennyben@fleming.u-psud.fr>
Copyright (c) 2003-2008 Paul Lesniewski <paul@squirrelmail.org>



Description
===========

This plugin displays a pull-down select box with IMAP
server choices on the login page.  The user will be
logged in using the IMAP server that is chosen.

Any number of SquirrelMail configuration settings may
be changed for each server that is offered to the user, 
including IMAP server details, what plugins are activated, 
and any other settings found in the main SquirrelMail 
configuration file.



License
=======

This plugin is released under the GNU General Public
License (see COPYING for details).



Donations
=========

If you or your company make regular use of this software, please
consider supporting Open Source development by donating to the authors
or inquire about hiring them to consult on other projects.  Donation/
wish list links for the author(s) are as follows:

Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228



Requirements
============

  * SquirrelMail version 1.2.9 or above

  * Compatibility plugin version 2.0.12 or above



Configuration
=============

  * $rememberServer, if set to 1, will place a checkbox on 
    the login page that allows the user to tell SquirrelMail
    to remember her last login server.

  * $IMAPSelections is a listing of IMAP servers you offer 
    and their corresponding server settings to be used when 
    a user logs in using the IMAP pull-down selection menu.  
    Each server is identified by any (user-friendly) label 
    that you deem appropriate (it need not have any technical
    information in it since it is just for display).  The
    servers each have any number of settings associated with
    them; most any setting available in SquirrelMail's 
    config/config.php is allowable such as "org_name", 
    "smtpServerAddress", etc., however, the two you will
    want to make sure are included are "imapServerAddress"
    and "imapPort".

    Note that there are three special settings: 

       'settingsWithEmbeddedPHP'  
           is an array contianing the names of all settings that 
           contain embedded PHP code.  It is possible to embed PHP 
           code in many of the settings in the $IMAPSelections array, 
           but you must specify which ones you have done so with here.
           Note that in order to embed the PHP code, you need to wrap 
           the entire value in single quotes.  See the example for 
           "org_title" in the sample configuration file.  

       'enable_plugins'  
           allows you to turn on specific plugins for a single IMAP 
           server.  The corresponding value must be an array of plugin 
           names (the name of the plugin directory) that you want to
           turn on.  See the sample config.php file for an example.

       'disable_plugins' 
           allows you to turn off specific plugins for a single IMAP 
           server.  The corresponding value must be an array of plugin 
           names (the name of the plugin directory) that you want to 
           turn off.  If the disable_plugins list contains "*", then 
           ALL plugins will be disabled, and only those in the
           enable_plugins list will be enabled.  See the sample 
           config.php file for an example.

    Note: If your usernames do NOT include domain name or some other
          characters that differentiate user logins between the servers
          in your configuration, you should define separate data 
          directories ('data_dir') for each one, otherwise user 
          preference files will be shared across all servers for the 
          same usernames.



Use with the Login Manager (vlogin) Plugin
==========================================

This plugin can be used to facilitate faster session-based
functionality for the Login Manager (vlogin) plugin.  If you 
are using Multilogin in tandem with Vlogin, you only need to 
put Multilogin in the plugins directory and patch the 
SquirrelMail source code(*), but you do not need to edit the 
Multilogin configuration file nor enable it in SquirrelMail.  

* If you use SquirrelMail 1.5.2 or up, you don't even need to 
  patch the source code, either.

If, on the other hand, BOTH plugins are to be activated, best
functionality will be achieved if you place Multilogin BEFORE
Vlogin in the plugins load list in your main SquirrelMail 
configuration file.  In newer versions of SquirrelMail, this
may not be a concrete requirement, but doing so will help
eliminate possible sources of confusion if problems arise.



Help Requests
=============

Before looking for help elsewhere, please try to help yourself:

  * Make sure the plugin is configured correctly by browsing to
    http://your-squirrelmail-location/src/configtest.php

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.

  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal
    address(es), but please be patient with the mailing list.



Change Log
==========

  v2.4  2008/07/06  Paul Lesniewski <paul@squirrelmail.org>
   * Allow configuration file to be stored in main
     SquirrelMail config directory
   * Added patch for SquirrelMail 1.4.15
   * Redesigned some hook behavior to improve performance
     (also improves Login Manager (vlogin) performance)
   * Update for hook name change in SquirrelMail 1.5.2
   * Configtest: test if patch is applied
   * Other trivial updates

  v2.3.4  2007/12/26  Paul Lesniewski <paul@squirrelmail.org>
   * Added patch for SquirrelMail 1.4.12+
   * Miscellaneous cleanup, small internationalization updates
     and fixes
   * Update how cookie is created/destroyed
   * Added configtest test

  v2.3.3  2006/01/14  Paul Lesniewski <paul@squirrelmail.org>
   * Fixed compatibility with changed login_form hook positioning
   * Added ability to turn off ALL plugins in the disable_plugins setting
   * No more patching needed for SquirrelMail versions 1.5.2 and up.
   * Added patches for SquirrelMail versions up to 1.4.9 and 1.5.1.
   * Changed patches to apply from plugin directory
   * Added compatibility with 1.5.2 codebase, including templatized output
   * Minor code cleanup

  v2.3.2  2005/10/19  Paul Lesniewski <paul@squirrelmail.org>
   * Code cleanup
   * Added patch for SquirrelMail 1.4.4.
   * Removed $IMAPServerSelectionText and $rememberServerText
     configuration settings in favor of standardized 
     internationalization.  If you need to change these strings,
     hard code them in functions.php or (better) create a correct
     translation locale file (even English is OK) with your changes.
   * Added "settingsWithEmbeddedPHP" setting for $IMAPSelections
     array that allows any configuration setting's value to
     contain embedded PHP code.  If your configuration file
     previously contained the org_title setting overrides, you
     MUST add this as described in the docs!
   * Added error message when invalid server is specified (Thanks
     to April Lorenzen <outboundindex@gmail.com>)

  v2.3.1  -  Paul Lesniewski <paul@squirrelmail.org>
   * Fix for php errors introduced in v2.3

  v2.3  -  Paul Lesniewski <paul@squirrelmail.org>
   * Fix for enabling plugins that use the same hook as
     Multilogin or Vlogin
   * Updated patch file for recent SquirrelMail releases
   * New background color for server selection portion 
     of screen.

  v2.2  -  Paul Lesniewski <paul@squirrelmail.org>
   * New approach to the "session_recall" functionality; 
     hopefully all config overrides will be loaded more 
     reliably.  The source patch is now limited to one 
     line in one file, instead of a line in almost every 
     source file.  This is a substantial change; upgrade 
     is highly recommended.
   * Added ability to change org_title in browser title bar
   * Added ability to enable and disable individual plugins
     on a per IMAP server basis

  v2.1  -  Paul Lesniewski <paul@squirrelmail.org>
   * Added ability to offer to remember which IMAP 
     server the user last logged into
   * Fix (hopefully?) for usage with PHP v4.3
   * Updated session_recall patches for SquirrelMail 
     versions 1.2.11 and v1.4
   * Minor HTML fix

  v2.0  -  Paul Lesniewski <paul@squirrelmail.org>
   * Now works with SquirrelMail version 1.4.0 (cvs)
   * New setup.php format for better overall SquirralMail
     performance

  v1.0  -  Benoit Bourdin <bennyben@fleming.u-psud.fr> and 
           Paul Lesniewski <paul@squirrelmail.org>
   * Initial release



