Select Range plugin for SquirrelMail
====================================
Ver 3.7.1, 2008/08/22


Copyright (c) 2003-2005 Kurt Yoder <kylist@shcorp.com>
Copyright (c) 2006 MrC <lists-squirrelmail@cappella.us>
Copyright (c) 2008 Paul Lesniewski <paul@squirrelmail.org>



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

This plugin allows users to quickly select many items from a
list, such as the message list or the address book list.  It
can be useful, for example, when the user needs to delete,
move, or modify the status of several messages at once, such
as when handling high-volume mailing lists.  JavaScript is
required in the client browser in order for this plugin to
function.

By default, the plugin provides a "Select Range" link above
and below the message list/display.  This allows the user to
select two items from the list, click "Select Range", and all
items between the two become selected.  "Toggle All" and
"Select Range" links are also added to the address book page.

Multiple ranges are fully supported, that is, if the first
and fifth messages are selected and "Select Range" is clicked,
messages two, three and four are auto-selected (in total,
messages one through five).  Then, if messages eight and twelve
are checked manually, after which "Select Range" is clicked
again, messages nine, ten and eleven are auto-selected (in
total, messages eight through twelve).  All together, messages
1-5 *and* 8-12 would be selected.

A preferences/configuration section for this plugin is added
to the Options->Display Preferences page, where, if allowed
by the administrator (via the configuration file), users can
adjust the plugin's behavior to suit their needs.

All of these features are available with a normal installation,
however, if using SquirrelMail 1.5.2 or better or the
SquirrelMail (1.4.x) source code is patched, a few additional
features are available:  the placement of the "Select Range"
link is changed to a more aesthetically appropriate location
and shift-clicking can be added as a shortcut (instead of
clicking on the "Select Range" link).  When shift-clicking is
enabled, the "Select Range" link can be removed altogether,
reducing on-screen clutter.



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
links for the author(s) are as follows:

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



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


  * SquirrelMail version 1.4.4 or above (although some
    functionalities are reported to be broken when used
    with versions of SquirrelMail earlier than 1.4.14)
    Address book page support is only guaranteed under
    1.4.14 and up.  Will not work at all with
    SquirrelMail 1.5.0 or 1.5.1.

  * Compatibility plugin version 2.0.7 or above, unless
    using SquirrelMail 1.5.2 or better.



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

  * If shift-clicking does not work, make sure you are watching
    for JavaScript errors in the client browser.  Verify that,
    unless using SquirrelMail 1.5.2 or better, the needed patch
    applied successfully.

  * If changes to the configuration file don't seem to be showing
    in the user interface, first check that you have not overridden
    the configuration settings with user preference settings that
    are shown on the Options->Display Preferences page.  Otherwise,
    ensure that there are not two Select Range configuration files,
    one in the select_range directory and one in the main
    SquirrelMail config directory (named "config_select_range.php").
    The one in the main SquirrelMail config directory will always
    override the one in the select_range 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
====

  * Add support for shift-clicking (and Select Range link?) in
    dictionary

  * Get shift-clicking working in all checkbox lists 
    (what other lists are there?)

  * Add an explanation of what this plugin does to the help file

  * Add support for search form; right now it is *really* messy
    to do so; apparently the search form code is also undergoing
    revision for 1.5 that should make select_range work better
    within it



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

  v3.7.1  2008/08/22  Paul Lesniewski <paul@squirrelmail.org>
    * Broken link fix that prevented range selection in some
      browsers
    * Added ability to store configuration file in main SquirrelMail
      config directory
    * Minor spacing fix (Thanks Roberto Piola)

  v3.7  2008/05/01  Paul Lesniewski <paul@squirrelmail.org>
    * Added compatibility with SquirrelMail 1.5.2
    * General code cleanup and redesign
    * Address book support is only guaranteed under SquirrelMail
      1.4.14 or better
    * Patches updated and changed; if upgrading, remove old
      patches and reapply.  The 1.4.14 patch should apply
      to most relevant versions; if the functions/forms.php
      patch fails on any version before 1.4.14, this can be
      ignored, as it relates to shift-click functionality in
      the address book that is not supported before SquirrelMail
      1.4.14 anyway.
    * Moved translation files to SquirrelMail core; translations
      have changed - please send new ones to the SquirrelMail i18n
      mailing list
    * Moved all administrator configuration to the configuration file
    * Allow all configuration items to be overrridden by users
      if the administrator allows (per configuration file)
    * Removed/added some user preferences; plugin may seem to
      "forget" old user preferences until they have been re-saved
      by users.
    * Will not work with SquirrelMail 1.5.0 or 1.5.1

  v3.6  2006/12/12  MrC <lists-squirrelmail@cappella.us>
    * Updated patch for SquirrelMail 1.4.9a
     
  v3.5  2005/03/13  Kurt Yoder <kylist@shcorp.com>
    * Added additional intelligence for range selection; supports
      groups of ranges
    * Added additional intelligence to shift-click for range
      selection, beyond what you get from clicking the "Select
      Range" link
    * Added additional configuration option to control the new
      "groups of ranges" behavior; the configuration defaults
      to the old behavior (eg, everything between first and last
      selected message is also selected)

  v3.01  2005/03/10  Kurt Yoder <kylist@shcorp.com>
    * Fixed bug where "Toggle All" link did not appear in
      address book unless "Select Range" link was also
      visible (reported by Alan in Toronto)

  v3.0  2005/01/26  Kurt Yoder <kylist@shcorp.com>
    * Added new "shift-click" functionality: hold down shift
      while selecting the second message, and get the same
      functionality as pressing the "Select Range" link
      (if you want to use this, you must patch)
    * Added mbox.diff and abook.diff for Squirrelmail 1.4.4;
      thanks to Shadow2531
    * New Norwegian translation from Ola Ketil Siqveland
    * Some translations updated
    * Removed patch files from before 3.0, since our patches
      have changed

  v2.8.2  2004/06/12  Kurt Yoder <kylist@shcorp.com>
    * Added mbox.diff and abook.diff for Squirrelmail 1.4.3a;
      thanks to Shadow2531 and Simon Matter for their help
    * Revised patching instructions
    * Removed extraneous strings from Spanish translation

  v2.8.1  2004/06/05  Kurt Yoder <kylist@shcorp.com>
    * Added simplified Chinese (zh_cn) and traditional Chinese
      (zh_tw) translations by Frankie Wong
    * Added partial Spanish translation by Elizabeth Vazquez;
      there are some extra strings in here, but I don't have
      msgfmt available right now, so I can't remove them
    * Removed errant .swp file in tl_PH directory (thanks to
      Fredrik Jervfors)
    * Updated INSTALL instructions to match current version
     (thanks to Fredrik Jervfors)
    * Changed config_default.php to config.php.sample to conform
      to http://www.squirrelmail.org/wiki/en_US/PluginStandards
      (thanks to Fredrik Jervfors)
    * Added index.php to every directory, also to conform to
      plugin standards

  v2.8  2004/04/01  Kurt Yoder <kylist@shcorp.com>
    * German translation permissions borked; fixed (thanks to
      Fredrik Jervfors for pointing it out)
    * Documentation updates
    * Code revisions suggested by Tomas Kuliavas; these require
      significant i18n strings changes; also thanks to Fredrik
      Jervfors for his help debugging some of these changes
    * Removed multi-line preferences string and 0/-1 option;
      now there is a dropdown html select list taking the place
      of this functionality
    * Removed "plugin_" from start of select_range preferences;
      this will re-set peoples' prefs, but now was a good time to
      do it since the prefs structure was changing anyway
    * Removed "best guess" translations on the advice of Tomas Kuliavas
    * Modified translation template and renamed to select_range.pot
    * Added "separator string" override in overrides.php;
      requested by Fredrik Jervfors
    * Fredrik Jervfors updated Swedish translation
    * Ísak Ben updated Icelandic translation (Hörður Már Gestsson 
      also sent one, but I already had Ísak's)
    * Kosaku Nagasaka updated Japanese translation
    * Simon Matter updated German translation
    * Renamed overrides.php to config.php to be more "standard";
      defaults are now kept in config.php.sample
    * Minor bug fixes
    * Added Indonesian translation by Arief S Fitrianto
    * Tomas Kuliavas updated Lithuanian translation

  v2.7  2004/03/17  Kurt Yoder <kylist@shcorp.com>
    * Changed default "show when x messages" link to 4 from 3
      (requested by Nils)
    * Changed options behavior: number of messages, only show
      the second and third lines of the description if they are
      non-blank.  This allows the local admin to override the
      strings in the locale file so that this string becomes
      whatever the admin wants *without* extra unwanted line
      breaks (requested by Nils)
    * Added en_US locale so English text strings can be
      overridden by site admins
    * Changed layout/text of options; this adds an extra
      i18n string
    * Added Icelandic translation by Ísak Ben
    * Added Polish translation by Martin Saini
    * Added range/toggle links to address book, though these
      require a patch (suggested by "Alan in Toronto"); also
      requires extra i18n strings

  v2.6a  2004/03/15  Kurt Yoder <kylist@shcorp.com>
    * Fixed Swedish translation

  v2.6  2004/03/11  Kurt Yoder <kylist@shcorp.com>
    * Minor documentation changes
    * Lithuanian translation from Tomas Kuliavas
    * Added Swedish translation modifications by Fredrik Jervfors
    * Changed patch to add a new hook instead of adding logic to
      mailbox_display.php; this simplifies patching and makes
      it "pretty"
    * Minor code cleanup
    * I think I'm supporting the version number API now?

  v2.5  2003/01/04  Kurt Yoder <kylist@shcorp.com>
    * Documentation revisions
    * Swedish translation from Fredrik Nilsson (Fredrik
      Jervfors gets credit for the first translation, but
      it only had one translated string, so I ended up using
      Fredrik Nilsson's)
    * Disabled patch link in search form (bug reported by
      Fredrik Jervfors)
    * Native German translation from Simon Matter; Kuehn
      Markus also sent a translation, but I already had
      Simon's (sorry Kuehn)
    * Patch was breaking searches for some people; switched
      to "include_once" to fix (thanks to Simon Matter who
      pointed this out)

  v2.4  2002/04/18  Kurt Yoder <kylist@shcorp.com>
    * Fixed the sample select_range.po file
    * I included a horrible German translation that I generated.
      Have fun laughing all you germans, then send me a better one.
    * Moved sample select_range.po into locale directory
    * Included Tagalog/Filipino translation from my wife Mary
      Ann; this does not appear to be a supported Squirrelmail
      language yet (Tomas Kuliavas says it's supported in
      Squirrelmail 1.5)
    * Moved hardcoded threshold to a constant so it can be changed
    * Fixed threshold comparison; previously was comparing to
      total number of messages in mailbox as opposed to total
      number of *displayed* messages in mailbox

  v2.3  2004/02/17  Kurt Yoder <kylist@shcorp.com>
    * Code cleanup
    * Patch now uses plugin's code, so there is only one piece
      of code to maintain
    * Patch now also uses translation files from plugin directory
    * Only displays link if more than a certain number of messages
      in mailbox (saves a bit of bandwidth); this can also be
      disabled by admin sitewide
    * Displays i18n'ized javascript notices if user doesn't select
      any messages first or only selects two messages right next
      to each other; this can also be disabled by admin sitewide
    * Patch compacted to minimize extra code
    * JavaScript function displayed only once (saves bandwidth)
    * Added "overrides.php" to allow admins to enable/disable
      various features
    * Added two preferences to allow user to control features
      (display errors and hide "Select Range" link for fewer
      messages) these are overridden by anything admin specifies
      in overrides.php
    * Added enable/disable option; set threshold to -1 to
      disable (requested by Ferdie Ferdsen)

  v2.2  2005/01/26  Kurt Yoder <kylist@shcorp.com>
    * Added i18n/l10n with Japanese language (patches from
      Kosaku Nagasaka)
    * Moved functions out of setup.php (suggested by Paul Lesniewski)
    * Simplified patching and updated instructions (thanks
      to Paul Lesniewski)

  v2.1  2005/01/26  Kurt Yoder <kylist@shcorp.com>
    * Updated with patch for 1.4.2
    * Added To-do list
    * Added "Plugin updates" compatibility (suggested
      by Robert V. MacQuarrie)

  v2.0  2003/07/15  Kurt Yoder <kylist@shcorp.com>
    * Initial public release of plugin version
    * Style fixes to pre-patched mailbox_display.php version 1.4.1
    * Revised patch README

  v1.1  2005/07/08  Kurt Yoder <kylist@shcorp.com>
    * Added mailbox_display.php version 1.4.1

  v1.0  2005/04/21  Kurt Yoder <kylist@shcorp.com>
    * Added mailbox_display.php version 1.4.0
    * Revised README

  v0.11  2003/04/01  Kurt Yoder <kylist@shcorp.com>
    * Added mailbox_display.php versions 1.4.0-rc2 and 1.2.9
    * Modified README file

  v0.1  2003/03/27  Kurt Yoder <kylist@shcorp.com>
    * Initial public release (patch only)