Empty Folders plugin for SquirrelMail
=====================================
Ver 2.0.1, 2009/01/01


Copyright (c) 2003-2009 Paul Lesniewski <paul@squirrelmail.org>



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

This plugin places "empty" and/or "purge" links next to any of
the folders in the folder list, or "Purge" and/or "Delete All"
buttons on the mailbox listing page.  These buttons or links
will remove all messages from the associated folder by either
moving them to the trash folder or removing them permanently
from the mail server, depending on the site and/or user
configuration.

If enabled by the administrator, users can control the
appearance and behavior of these links and buttons by
navigating to the "Folders" page in the SquirrelMail
interface.



RPC Interface
=============

This plugin can be used via the SquirrelMail RPC interface (as of
SquirrelMail 1.5.2+).  It handles the following commands:

  empty_folders_purge_trash - removes all messages from the trash
                              folder
  empty_folders_purge_all   - removes all messages permanently from
                              the given folder (specified by the
                              "mailbox" argument in the RPC request)
                              (does NOT copy them to the trash folder)
  empty_folders_delete_all  - removes all messages from the given
                              folder (specified by the "mailbox"
                              argument in the RPC request) and places
                              copies of them in the trash folder)
   
Error codes that may be returned:

  500 - empty_folders_purge_trash failed
  501 - empty_folders_purge_all failed
  502 - empty_folders_delete_all failed



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 1.2 or above

 * Compatibility plugin version 2.0.12 or above



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

  * If the "empty" link is not showing next to some of the folders
    for which it is configured, make sure those folders have one
    or more messages in them (otherwise, the link will not be
    displayed).

  * 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 Folders page.  Otherwise, ensure that you are
    editing the correct configuration file.  If one is located in
    the main SquirrelMail config directory (named
    "config_empty_folders.php"), it will always be used.  Otherwise,
    "config.php" in the empty_folders 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
====

  * When a user chooses to purge a folder that may have received
    an incoming message since they last updated the message count
    shown on screen, new unseen messages may be lost (CAUTION!).
    It would be nice to implement a routine that gets the UIDs
    of all unseen messages only and just purge them.



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

  v2.0.1  2009/01/01  Paul Lesniewski <paul@squirrelmail.org>
   * Correct generation of redirection link URI for purge links
   * Update for slight change in SquirrelMail RPC API

  v2.0  2008/07/08  Paul Lesniewski <paul@squirrelmail.org>
   * Allow configuration file to be stored in main SquirrelMail
     config directory
   * Updated for compatibility with SquirrelMail 1.5.2+
   * Added RPC-enabled call to this plugin (1.5.2+)
   * Added ability to show "purge" or "empty" links on folder list
   * Added ability to show "purge" or "delete all" buttons on
     the mailbox list page, as well as confirmation popups for
     all actions this plugin performs (Thanks to Naveen Gavini)
   * General updates and cleanup
   * Please note that the configuration system for this plugin has
     been rewritten and is incompatible with previous versions.
     Also, any user preferences for previous versions are no longer
     used.

  v1.2.1  2005/12/06  Paul Lesniewski <paul@squirrelmail.org>
   * Fix for systems with DB backend encountering undefined function error.

  v1.2  2005/11/08  Paul Lesniewski <paul@squirrelmail.org>
   * No longer need to create and edit config file when installing
     unless default settings are not desirable
   * Translations now points to main SquirrelMail locale
   * Fixes to work with newest version of Compatibility plugin
   * Some minor code cleanup and documentation changes

  v1.1  22/02/04  Paul Lesniewski <paul@squirrelmail.org>
   * Updated INSTALL procedure, now includes fix for 1.5.0.
     Note that no source patching is required for SquirrelMail
     1.4.1 and up and 1.5.1 and up
   * Full internationalization - send your translations!

  v1.0  20/04/03  Paul Lesniewski <paul@squirrelmail.org>
   * Initial version