Server Settings plugin for SquirrelMail
=======================================
Ver 2.0, 2010/06/13


Copyright (c) 2008-2010 Paul Lesniewski <paul@squirrelmail.org>



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

This plugin provides a front end to the configuration options
for any system running outside of SquirrelMail.  This can
include anti-spam software such as SpamAssassin, or even ANY
unrelated software that users should be able to configure using
the SquirrelMail interface.  It is tightly coupled with the
Server Settings Backend plugin so that it can offer user control
over settings that are stored in a variety of backends.  Settings
stored inside the SquirrelMail user preference mechanism are also
supported, however, another plugin will have to make use of such
settings.  This plugin also has a small API that provides other
plugins (for example, the Spam Buttons plugin) the ability to
access and use the settings that are configured herein.



License
=======

This plugin is released under the GNU General Public
License (see the file 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://squirrelmail.org/donate_paul_lesniewski.php



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

  * SquirrelMail version 1.4.0 or above

  * If not using SquirrelMail 1.4.10+ or 1.5.2+,
    Compatibility plugin version 2.0.7 or above



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

The configuration file is used to define one or more SquirrelMail
options pages that will allow users to configure various parts of
your backend systems.  Each one is defined in an array that
consists of the following elements (as the corresponding array keys):

   TITLE          This text will be shown both on the SquirrelMail
                  Options page (where all other options pages are
                  listed) as well as at the top of the actual page
                  you are creating.

   DESCRIPTION    This text will be shown on the SquirrelMail
                  Options page (where all other options pages are
                  listed), and should give a short (one or two
                  sentence) explanation of the settings that are
                  controlled on the page you are creating.

   NO_OPTION_PAGE If present (filled with any non-empty value),
                  this indicates that no link on the SquirrelMail
                  Options page for this group of settings.  This
                  is most commonly used in conjunction with the
                  "MENU_LINK" element.  Please ensure that this
                  element *does not* exist when an option link
                  is to be shown for this group of settings.

   MENU_LINK      When present, this is the text of a link that
                  will be added to the menu that is shown across
                  the top of all SquirrelMail content pages
                  (the menu that typically starts with "Compose",
                  "Addresses", "Folders", etc.).  The link will
                  take the user to the options page for this
                  settings group.

   RETURN_TO_SELF When present (filled with any non-empty value),
                  the option page will simply reload when the user
                  clicks the submit button (instead of returning
                  to the SquirrelMail main Options page).

   WIDGETS        This is an array of the controls/settings that
                  will be contained in the options page.  This
                  array should contain all the typical elements
                  that help define option widgets per the normal
                  SquirrelMail options API explained here (NAME,
                  CAPTION, TYPE, etc.):

                     http://squirrelmail.org/docs/devel/devel-4.html#ss4.7

                  Additionally, you may specify three more special
                  elements in the widget's configuration:

                     SECTION        This defines the subsection on
                                    the options page under which this
                                    widget should be placed.  It is
                                    optional, and if not given, the
                                    widget will be grouped in a generic
                                    unlabelled section.

                     SETUP_LOCATION This indicates where the initial
                                    value for the widget should be
                                    placed in the widget information
                                    array.  This is NOT a required
                                    element, and if not given, the
                                    value will be placed in
                                    "initial_value".  Sometimes this
                                    needs to be changed, such as for
                                    options of type SM_OPT_EDIT_LIST,
                                    which need to be set as "posvals".

                     MULTIPLE_VALUE_UPDATES_SEPERATELY
                                    If present (filled with any non-empty
                                    value), this indicates that when saving
                                    widgets consisting of multiple values,
                                    adds and removals should be done
                                    seperately (as opposed to reconstructing
                                    the whole list and re-saving it all at
                                    once).  This is useful for backends
                                    such as SQL where unchanged items in the
                                    list should be left as is.

                  If the setting should be stored by SquirrelMail
                  in the normal user preferences, then this is all
                  that is needed, however, if the setting corresponds
                  to a configuration value stored elsewhere on the
                  server, you must also define elements here that
                  indicate how to retrieve and set the value:

                     STORAGE  This is a subarray of information explaining
                              how to look up the setting's value and put
                              a new value in its place.  The elements herein
                              and their possible values are defined in the
                              Server Settings Backend plugin (see the
                              Configuration section in its README file).

Please see the configuration file for some examples.



Plugin Authors' Usage Guide
===========================

There are a few points of entry to this plugin for use by other
plugins that want to work with the settings that are configured
herein.  Other plugins can retrieve a setting value, test a
setting's value, and save a value.  We start with how to retrieve
a setting:

   $quiet = FALSE;
   include_once(SM_PATH . 'plugins/server_settings/functions.php');
   $setting = server_settings_retrieve_value($setting_name, $title,
                                             $section, $quiet);

This will return the desired setting value.  Both $title and $section
are optional and if not specified (empty), the first widget in the
Server Settings configuration that matches the $setting_name will be
used.  If there are identically named widgets on different options
pages in the Server Settings configuration, use $title and/or $section
to uniquely identify the desired setting.  Normally, you'll want to
leave $quiet set to FALSE, since any errors encountered are usually
configuration errors that you will want to see and debug.  If $quiet
is TRUE, then any errors are silently ignored and NULL is returned.
If the setting value consists of multiple values, it will be returned
in an array, unless there is a configuration problem.

   $quiet = FALSE;
   include_once(SM_PATH . 'plugins/server_settings/functions.php');
   $result = server_settings_test_value($setting_name, $test_value,
                                        $title, $section, $quiet);

This function will test if the setting contains the given test
value.  If the setting is comprised of multiple values, it is
considered a match if one of the values therein matches the test
value, whereas if the setting is scalar, its value must match the
test value exactly to produce an affirmative return value.  The
returned value is boolean, indicating if the test matched or not.
Both $title and $section are optional and if not specified (empty),
the first widget in the Server Settings configuration that matches
the $setting_name will be used.  If there are identically named
widgets on different options pages in the Server Settings
configuration, use $title and/or $section to uniquely identify the
desired setting.  Normally, you'll want to leave $quiet set to
FALSE, since any errors encountered are usually configuration
errors that you will want to see and debug.  If $quiet is TRUE,
then any errors are silently ignored and NULL is returned.

   $quiet = FALSE;
   include_once(SM_PATH . 'plugins/server_settings/functions.php');
   $result = server_settings_update_value($setting_name, $new_value, $title,
                                          $section, $add, $remove, $quiet);

This will return TRUE when the setting was saved normally.  Here, too,
the $setting_name is used to find the first like-named widget in
the Server Settings configuration, or you may specify $title and/or
$section to uniquely identify the desired setting if there are
identically named widgets on different options pages.  When $add is
TRUE, it indicates that a single value is to be added on to a multi-
value setting.  This allows the caller to push an additional value
into the setting without needing to worry about retrieving and re-
saving all the other values it contains.  Similarly, if $remove is
TRUE, this indicates that the given value is to be removed from a
multi-value setting.  This function will return TRUE when the setting
was saved normally.  Typically, you'll want to leave $quiet set to
FALSE, since any errors encountered are usually configuration errors
that you will want to see and debug.  If $quiet is TRUE, then any
errors are silently ignored and NULL is returned.



Troubleshooting
===============

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

  * If using settings accessed via the Server Settings Backend
    plugin, please also refer to its Troubleshooting information
    in its README file

  * If changes to the configuration file don't seem to be having
    any effect, ensure that there are not two Server Settings
    configuration files, one in the server_settings directory
    and one in the main SquirrelMail config directory (named
    "config_server_settings.php").  The one in the main SquirrelMail
    config directory will always override the one in the
    server_settings directory.



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

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

  * Read the Troubleshooting section herein.

  * 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.



TODO
====

  * When removing a value from cross-updating widgets on the same page,
    a bug seems to be causing the secondary save table to be hit with
    the following query:
    DELETE FROM blacklist WHERE username = 'user@example.com' AND sender = 'a:1:{i:2;s:14:"spamer@sco.com";}'
    This query may also be executed more than once under some
    circumstances.  Due to the serialized nature of the information,
    the query should fail in any environment it is used in, so I am
    not prioritizing this bug.

  * Pages using RETURN_TO_SELF seem to go back to the options page when
    the user clicks the submit button not having made any changes.  For
    now, this is considered a feature.  :-)

  * Ideas?



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

  v2.0  2010/06/13  Paul Lesniewski <paul@squirrelmail.org>
    * Added configuration examples for using Server Settings Backend
      Local File backend
    * Minor documentation updates

  v1.0  2009/01/01  Paul Lesniewski <paul@squirrelmail.org>
    * Initial release



