-ABOUT

This plugin requires javascript and allows you to quickly select many items from
a list, such as the message list or the address book list.  I find it extremely
helpful for handling high-volume mailing lists.

By default, the plugin provides a "select range" link above and below the
"Toggle All" links in the message list/display.  This enables the user to select
two items from the list, click "select range", and all items between the two
become selected.  This is useful if you want to delete or modify message status
of a bunch of messages quickly. 

You can also change your select range preferences to support selecting "multiple
ranges". For example, you select message one, then message five, then click
"select range". You select message eight and message twelve, then click "select
range". You now have messages 1-5 *and* 8-12 selected. This feature becomes
highly useful when you patch to enable shift-clicking (see below).



-FEATURES

There are extra features besides the auto-check-marking. If you check-mark zero
or one list items and then click the "select range" link, you get a javascript
alert asking you to select at least two items. If you check-mark two or more
items but don't leave any un-selected items between them, you get a javascript
alert asking you to leave at least one un-selected item between the first and
last selected items. This should help familiarize new users with the
functionality of this plugin. Also, you can set a minimum number of items in the
current message view before the select range link is shown. All alerts are
disabled when shift-clicking. 

The javascript alerts and the minimum number of list items can be individually
configured by users in the options/display preferences.  If desired, you can
disable javascript alerts and/or list item threshold for everyone sitewide. This
mimics the behavior of pre-2.4 versions of this plugin. See config.php.sample
for information on how to do this.

You can override the text strings if you don't like the default wording. To do
this, edit the language ".po" file in the locale folder for your locale (to
override English, look in locale/en_US). Once you've made your changes, change
to the language directory and run "msgfmt -o select_range.mo select_range.po". 

There are administrative overrides scattered in various places. You
can change the default message threshold value at the top of functions.php. You
can also change the separator string between the "toggle all" and "select range"
links in config.php (copy from config.php.sample to do this).



-ADDITIONAL FEATURES FROM PATCHING

You can display the link next to "toggle all" instead of above and below the
message list (more aesthetically pleasing IMHO). Optionally, you can also show a
"select range" and "toggle all" link in the address book. To do either of these,
you will need to patch. 

Alternatively, you can "shift-click". You check one item, then hold down the
shift button and select another item, and get the range selection behavior as
described in the "ABOUT" section. This should significantly reduce the amount of
required mouse movements. If you hide the "Select range" link, you will also
reduce the number of items on the screen. An additional benefit of
shift-clicking is some extra intelligence built in to the range selection,
beyond what you would get from clicking the "select range" link. Try it and see!
To use shift-click, you will need to patch. Shift-click also works in the
address book if you patch the address book*.

You will find instructions and patch files in the "patch" folder of this plugin.
The select range patch is known to be compatible with the "message flags" plugin
as of Squirrelmail 1.4.4.  To enable any of the select range functionality, you
will still need to enable the plugin.

*Note: there is a bug in the address book where each checkbox element does not
receive a unique name. Shift-click will still work, but will get a bit confused
in unusual circumstances. You will probably not notice a difference though.




-SUPPORT/CONTACT INFORMATION

If you have support questions, you can post to the squirrelmail plugins list. To
join the list, go here:

https://lists.sourceforge.net/lists/listinfo/squirrelmail-plugins

To search archives, you can try the gmane http interface here:

http://news.gmane.org/gmane.mail.squirrelmail.plugins

If you have a patch, translation file, comment, or an amusing anecdote about how
this plugin helped you alleviate the misery of the world, you can email me at
freespirit74@yahoo.com. Note that support questions *must* go to the mailing
list so that others may benefit from discussion of the problem. Support requests
sent to the yahoo address will at best receive a reply requesting that you send
the mail to the plugins list, or at worst be ignored.



-INTERNATIONALIZATION

This plugin supports full i18n, so translations are helpful. Before you do a
translation, please consider subscribing to the i18n list at
http://lists.sourceforge.net/lists/listinfo/squirrelmail-i18N. This will ensure
that your translation is OK with other Squirrelmail users who use your language
and that you are not duplicating someone else's efforts. In case there are two
different versions of a translation for the same language, I will pick the
version that has "official" approval by the i18n list. If neither translation is
"official" I will use the first one that I receive.

Here are the steps to create a translation:

- create a language directory in locale (check Squirrelmail locale directory for
  a list of available languages)
- create a subdirectory LC_MESSAGES
- copy locale/select_range.pot to LC_MESSAGES directory you created
- change to the LC_MESSAGES directory you created
- rename select_range.pot to select_range.po
- edit select_range.po
- modify the information at the top
- add your translations between the quotes after msgstr
- run "msgfmt -o select_range.mo select_range.po"
- compress and tar the language directory you created and send it to me



-UPGRADING PREFERENCES BEFORE 2.8

If you have a bunch of user preferences created and are upgrading to version
2.8, your users' preferences will be lost. This is because the preference key
names were changed between 2.7 and 2.8. You can update your users' preferences
to the new names pretty easily. 

If you are storing your user preferences in MySQL, here is the SQL syntax to
update your users' preferences:

UPDATE userprefs SET prefkey='select_range_threshold' WHERE
  prefkey='plugin_select_range_threshold';
UPDATE userprefs SET prefkey='select_range_display_errors' WHERE
  prefkey='plugin_select_range_display_errors';

If you are storing your user preferences in local files, this command should
update preferences (I haven't tested this very much, so if you encounter errors
and fix them, please send me the working script):

for f in *.pref; do cat $f | sed -e s/^plugin_select_range/select_range/ \
  > abook.tmp; mv abook.tmp $f; done;



-REVISION HISTORY

03/13/05 - ver 3.5
- additional intelligence for range selection; supports groups of ranges
- shift-click has additional intelligence for range selection, beyond what you
  get from clicking the "select range" link
- 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)
- these extra features were requested by WJCarpenter and were added because 1.
  it is an interesting problem, and 2. I am procrastinating on something else I
  should be doing

03/10/05 - ver 3.01
- fixed bug where "toggle all" link did not appear in address book unless
  "select range" link was also visible (reported by Alan in Toronto)

01/26/05 - ver 3.0
- 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

06/12/04 - ver 2.8.2
- 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

06/05/04 - ver 2.8.1
- 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

04/01/04 - ver 2.8
- 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 (Hrur Mr 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

03/17/04 - ver 2.7
- change default "show when x messages" link to 4 from 3 (requested by Nils)
- Under options: 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

03/15/04 - ver 2.6a
- Swedish translation was broken; fixed

03/11/04 - ver 2.6
- minor documentation changes
- Lithuanian translation from Tomas Kuliavas
- 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?

03/01/04 - ver 2.5
- 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)

02/18/04 - ver 2.4
- I messed up the sample select_range.po file; fixed
- 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

02/17/04 - ver 2.3
- 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)

02/12/04 - ver 2.2
- added i18n/l10n with Japanese language (patches from Kosaku Nagasaka)
- moved functions out of setup.php (suggested by pdontthink)
- simplified patching and updated instructions (thanks to pdontthink)

02/05/04 - ver 2.1
- updated with patch for 1.4.2
- added To-do list
- added "Plugin updates" compatibility (suggested by Robert V. MacQuarrie)

07/15/03 - ver 2.0
- initial public release of plugin version
- style fixes to pre-patched mailbox_display.php version 1.4.1
- revised patch README

07/08/03 - (patch only) ver 1.1
- added mailbox_display.php version 1.4.1

04/21/03 - (patch only) ver 1.0
- added mailbox_display.php version 1.4.0
- revised README

04/01/03 - (patch only) ver 0.11
- added mailbox_display.php versions 1.4.0-rc2 and 1.2.9
- modified README file

03/27/03 - (patch only) ver 0.1
- initial public release



-TODO

support shift-clicking (and select range link?) in dictionary

get shift-clicking working in all checkbox lists so we can remove kludge
checking what page we're on before showing javascript

add to help file to say what it does (suggested by Ferdie Ferdsen)

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

set default threshold in config.php instead of at the top of functions.php

hide extra javascript shift-click code if the patch isn't installed; it's getting
big enough for this to be a concern
