Address Book Grouping and Pagination plugin for SquirrelMail
============================================================
Ver 1.0, 2008/05/01


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



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

This plugin adds pagination to the address listing page and,
if allowed per the configuration file, adds address book
grouping functionality to SquirrelMail.  Users may define any
number of groups to which addresses can be added (and addresses
may be added to more than one group).  The address listing page
is then adorned with a filtering selector that lets the listing
be filtered by one or more groups.

Grouping is backend-agnostic.  That is, no matter what address
book backends are in use, this plugin will work the same, and
there are NO changes required whatsoever to begin using
grouping functionality.  It is important, however, to note that
because grouping information is kept independently from the
address book store(s), if there are any changes made with
address book backends, such as removing one or rearranging
their order, the grouping information for all users may become
corrupted.  If care is taken to keep the backends in the same
order, or not otherwise replace one backend with a different
unrelated one, no problems should arise.

Also note that for the same reason - grouping information is
kept apart from the address store(s), addresses cannot be
imported or exported with group information attached to them.
This may change in the future if those functionalities are
enhanced to work with this plugin.

It is also possible for address book backends to implement
either pagination or grouping on their own (since it may be
more efficient to, for example, retrieve only a subset of
address records from a database rather than the entire
contents of the address book for later pagination and group
filtering by this plugin).  In this configuration, this
plugin then only serves to place pagination and/or group
filter controls in the interface.



Usage
=====

Address book groups are defined by each user under Options -->
Display Preferences --> Address Book.  Once some groups are
created there, they can be populated by clicking on the
"Addresses" link next to the "Compose" link at the top of the
main SquirrelMail window.

When address grouping functionality is enabled, a list of
the user's address groups is shown in the upper right-hand
portion of the address list table.  To add new addresses to
a group, highlight the group, then click the checkboxes of
the addresses to be added and press the "Add" button.
Addresses may be added to more than one group at a time by
highlighting more than one group name during this process.

To remove addresses from one or more groups, highlight the
group(s) and click the checkboxes for the addresses to be
removed and press the "Remove" button.

To filter the list of addresses being viewed so that only
one (or more) group(s) is shown, highlight the group name(s)
and press the "Go" button (under SquirrelMail 1.5.2+, press
the "Change" button instead).  For user convenience, the
group filter is automatically applied after an "Add" or
"Remove" action is performed.



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.4.9 (although it is highly
    recommended to use at least 1.4.14 for best security
    and compatibility).  This plugin may also work with
    earlier SquirrelMail versions if you can make the
    needed patches, but this is not officially supported.

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



Integration Instructions (Address Book Backend Authors' Guide)
==============================================================

Note that address book backends can paginate on their own
(which is much more efficient if the backend can gather
just the address entries for the needed page) instead of
letting this plugin take the *entire* address book contents
and paginate them.  If a backend does so, it should put a
"paginated" entry in each of the addresses in the list it
returns, where the value for that entry is equivalent to
boolean TRUE.  That will indicate to this plugin that the
pagination has already been accomplished, and this plugin
only needs to display the page selectors in the interface.

In order to know what page to retrieve, the backend should
look for the page number in the GET or POST arguments as
"backend_page_number_x" where "x" is the backend number.
There is also an OPTIONAL override of the page size that
might show up in the GET/POST called "backend_page_size_x".

The backend also needs to populate a "total_addresses"
entry in each of the addresses in the list it returns,
which must contain the total (unpaginated) number of
addresses in the backend (used for generating pagination
links).

Similarly, address book backends can retrieve address lists
by group on their own (which is more efficient for the same
reasons explained above).  If a backend does so, it should
put a "grouped" entry in each of the addresses in the list
it returns, where the value for that entry is equivalent to
boolean TRUE.  That will indicate to this plugin that the
group filtering has already been accomplished, and this
plugin only needs to display the group filter controls in
the interface.

In order to know what group(s) to retrieve, the backend
should look for the group names in the GET or POST
arguments as "abook_groups_x", where "x" is the backend
number.  The value for it will be an array containing the
selected group names.

The backend would also need to detect and act upon the
actions this plugin generates for adding and removing
addresses to/from group(s).  It should add any addresses
it finds that are appropriate in the page request variable
called "sel" when there is a page request variable present
called "abook_groupadd_x", where "x" is the backend number.
Likewise, removals should be processed using "sel" and
"abook_groupdel_x".  The groups to be added to or removed
from are in the same "abook_groups_x" explained above.



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

  * If pagination or grouping do not show up after clicking
    the "Addresses" link next to "Compose" on the top "menu
    bar" in the main SquirrelMail window, check that the
    configuration file has those functionalities turned on
    and if so, check the user preferences under Options -->
    Display Preferences --> Address Book

  * 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 you are editing the correct configuration file.
    If one is located in the main SquirrelMail config directory
    (named "config_abook_group_pagination.php"), it will always be
    used.  Otherwise, "config.php" in the abook_group_pagination
    plugin directory will be used.



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 pagination and filtering to the address book screens (both the
    popup JavaScript one and the in-window one) that you get to when
    clicking to add addresses via the button on the compose screen.

  * Possibly add a way to add and remove addresses to/from groups on
    the display options page.  This would take a lot of screen real
    estate for people with large lists, so if this is attempted, at
    least the SMOPT_EDIT_LIST_LAYOUT_SELECT layout_type of the
    SMOPT_TYPE_EDIT_LIST should be used.

  * Possibly add "show all" link next to pagination links

  * Possibly add "next" and "previous" links next to pagination links

  * Possibly add a drop-down ("compact") paginator... optionally it
    could show the first nickname on each page, although this would
    not be very "compact", but note that this would not be possible
    if the backend provides its own pagination)

  * Implement group data information in address book import/export
    functionalities.  This may prove to be difficult and is not
    currently high priority.



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

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

