Shared Calendar plugin for SquirrelMail
=======================================
Ver 2.0.1, 2005/04/21


Copyright (c) 2004-2005 Paul Lesneiwski <pdontthink@angrynerds.com>



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

This plugin implements calendaring functionality for SquirrelMail.

Multiple calendars may be created, where each calendar can be made
public, private, or shared between custom-defined groups of users.
User access to public and shared calendars may be given as read-only
or read/write.

Calendar administrators can be defined as "limited", so that they
may only manage their own calendars, or as super-adminstrators,
who have access to all calendars on your system.  Note that all
administrative functionality is accessed through the "Calendar 
Administration" selection on the Options page.

Calendar events may be defined as one-time or recurring.  Currently,
the input mechanism (GUI) for recurring events is a limiting factor, 
whereas the recurrence engine is fully iCalendar/RFC 2445-compliant 
and is capable of rendering very complex recursion rules.  

See the INSTALL file for setup instructions.



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

Please see the configuration file included in the data directory;
copy and edit it as instructed in the INSTALL file.  There are 
extensive descriptions of each configuration option in the 
configuration file itself.

If you are having problems getting your administrative users set
up correctly, please turn on the $cal_debug setting and click
on the main "Options" link in the SquirrelMail interface to see
printed information about your username and how it matches up 
to the usernames in the configuration file (although note that
it only tests for exact matches and does not weigh in wildcards).



Calendar Backends
=================

The backend that provides data storage for user calendar data is
to be installed as a separate plugin.  You must download and install
at least one calendar backend in order for this plugin to work.



Performance Issues
==================

"Heavy" calendars (primarily ones with large numbers of recurring 
events) can possibly cause noticable performance lags.  Calendars
are cached in session, so this should only happen the first time
such a calendar is parsed, which can be either when you click on
the "Calendar" link or when you first log in if you have the Small
Calendar turned on.  Aside from some very clever and very detailed
tweaks (or a complete rebuild) of the recurrence engine, there is
little that can be done about this.  Keep in mind, this is PHP,
not C.  A TODO item is to add a cross-session caching system, which
might fix this problem for good, but it is not currently top priority.

Also, if a user has chosen to link to an external calendar, it is
typically only read once during login.  If the remote server is slow
or not responding, this can cause the user's login to seem abnormally
slow.



Upgrading Old SquirrelMail Calendar Files
=========================================

You have two ways of upgrading old calendar data:

  - Turn on the $migrateOldCalendarData setting in the configuration
    file.  Note that this requires special permissions on the 
    scripts/convert_cal_to_ical.pl file in order for your 
    web server to execute it.  Please see the configuration file for 
    more details.

  - Run the convert_cal_data.sh file contained herein, giving it
    the path to your SquirrelMail data directory, and all old calendar
    files will be converted to iCal format and dumped to the screen.
    You will want to distribute the results to your users and have 
    them save each one as a file on their own computer and use the new 
    calendar interface to upload and merge the events within into the
    appropriate calendar.  Thanks to Ryan <ryanshea@gmail.com> for most
    of this code.



Upgrading From Version 2.0
==========================

There are a few incompatibility issues when upgrading from version
2.0 of this plugin to newer versions.  One-day-long all-day events 
created with version 2.0 of the plugin will cause errors unless you 
delete them or manually change the DTEND property for such events 
to the following day.  Also, users will likely see two personal
calendars; any events in the removable calendar should be exported,
the calendar then removed, after which the events should be uploaded
and merged with the remaining personal calendar.  If errors occur
when uploading, it is helpful to edit the exported iCal file and
either remove X-WR-RELCALID and X-SQ-CALID or change them to match
the correct calendar ID (which can be seen by turning on $debug
mode in the configuration file).



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

Help requests are welcome at my personal email address, but I
request that you first post to the SquirrelMail Plugins mailing
list, where you'll get faster help from more people and other
people with the same problem will be able to see how your issue
was resolved.  If you don't get good answers that way, you may
try emailing me directly.

Info about the SquirrelMail Plugins mailing list can be found
on the SquirrelMail web site.  It is currently located at:

http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
squirrelmail-plugins@lists.sourceforge.net



License
=======

This plugin is released under the GNU General Public
License (see COPYING for details).



TODO
====

 * see TODO file



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

  v2.0.1 2005/04/21
    * Fixed incorrect date format for all day events
    * Added $useDomainInCalID; lets admin turn off usage 
      of domain name in calendar IDs; see config file for 
      details.  If you turn off the use of domain name in 
      calendar IDs, you may see anomalous personal calendars 
      appear.  Export any events you need from them and then 
      delete them and move the events to the correct 
      "Personal" calendar.
    * Reenabled validateFields() for event validation
    * Fixed broken personal calendar exports
    * Removed $twentyFourHourTime in favor of SquirrelMail's 
      $hour_format (see Options->Folder Preferences)
    * Internationalization fixes
    * Uploaded calendar events are now editable
    * Events scheduled on days past end of month are moved
      to last day of month (Feb 31 --> Feb 28)
    * Added ability for admin to turn off all small calendar
      functionality 
    * Added ability of users to create more than one personal
      calendar
    * Added ability to show event times in non-context
      sensitive fashion
    * Added ability to go directly to event view by clicking
      on event in month view
    * Fix: public calendar events were not viewable by regular users
    * Added delete button to event edit screen
    * Fixed problem where events being uploaded in one calendar
      without event IDs (such as those created with conversion
      script) would all get the same ID (thanks to Andy 
      Brook <ducky0@gmail.com>
    * Removed begin time from events on all but their first day
      on month view.
    * Added Microsoft-compatible exports checkbox (grrr)
    * Added automated conversion functionality of old calendar data
      to new iCal format (thanks to Andy Brook <ducky0@gmail.com>)
    * "Today" link above small calendar correctly goes to *today*
      (day view) no matter what month small calendar is displaying.
    * Removed duplicate DTSTAMP entries in exported calendars
    * Added correct date type to all-day event exports (MS Outlook
      imports now work correctly for these events)
    * Added BYMONTHDAY to montly recurring events to make MS Outlook
      happy.

  v2.0 25/02/05
    * Official release of 2.0
    * Added converstion script for old SquirrelMail calendars
      (Thanks to Ryan <ryanshea@gmail.com>)
    * Major upgrade to event cache system; response time for
      "heavy" calendars is now fairly reasonable.

  v2.0 RC 1 02/02/05
    * Added recurrence day inputs when creating/editing events
    * Fixed broken BYDAY for WEEKLY events
    * Minor fix of iCal formatting of RRULEs (no escaping needed)
    * Several interface enhancements; see calendar options page
    * Internationalized all output
    * Removed personal calendar ID construction from backend

  v2.0 beta 3 13/01/05
    * Exporting iCal now functional
    * Fixed missing include of url_parser.php for broken day view
    * Fixed incompatibility with JavaScript and calendar IDs: need
      to run fix_calIDs.sh on your calendar data directory if you
      had an earlier beta of v2.0

  v2.0 beta 2 11/11/04 (or thereabouts)
    * Import iCal files now functional
    * Link to external calendars now functional
    * Massive speed improvements in recursion engine
    * Several bug fixes in recursion engine
    * Other small fixes/improvements

  v2.0 beta 1 29/09/04
    * Bugs squashed in recursion engine
    * Fixed problem with invisible personal calendars
    * Bug fix faulty file formats: need to run fix_rrules.sh
      on your calendar data directory if you had an earlier
      alpha of v2.0

  v2.0 alpha 10/09/04
    * Extensive re-write... this is a whole new plugin
    * Note that PHP 4.1.0 is required due to use of date('W')

  v1.1.2 11/09/03
    * Tool tips show event time
    * Events on year/month view sorted by event time
    * Fixed anomalous broken save functionality 
    * Year view now positions itself at current month
    * Replaced ereg functions with faster preg ones

  v1.1.1 25/07/03
    * Fix for bug preventing creation of public calendars

  v1.1 18/07/03
    * Added ability to specify "limited" administrative users
      who can create shared calendars but not see anyone else's
      shared calendars.
    * Added year view! (Complements Mary Hunter <mhunter@jfku.edu>)
    * Added creator and last editor to event edit and delete pages
    * Fixed problem where some people couldn't create shared calendars
    * Fixed problems administering shared calendars and users
      under non-English languages
    * Fixed some more E_ALL warnings
    * Fixed color clash where events would seem to disappear under
      certain themes
    * Events at midnight (hour zero) now work correctly

  v1.0.1 19/04/03
    * Added event creator and last edited by fields for shared
      calendars
    * Fix for shared calendars not being shared when using
      a Directory Hash Level greater than zero.

  v1.0  05/04/03
    * Updated to work with SquirrelMail 1.4.0

  v0.5.7 24/04/03
    * Added creator and last editor to event edit and delete pages
    * Fixed problem where some people couldn't create shared calendars
    * Fixed problems administering shared calendars and users
      under non-English languages
    * Fixed some more E_ALL warnings
    * Events at midnight (hour zero) now work correctly

  v0.5.6 19/04/03
    * Added event creator and last edited by fields for shared
      calendars
    * Fix for shared calendars not being shared when using
      a Directory Hash Level greater than zero.

  v0.5.5  06/04/03
    * Hovering mouse on events on month view pops up text of event
    * Fix bug when selecting "No" from event update confirmation.

  v0.5  28/03/03
    * Added admin ability to specify wildcards (* or ?) in usernames 
      when assigning users' calendar permissions (saves a lot of 
      typing and manual maintenance when, for example, all users in
      one domain should have access to a single shared calendar!)
    * New users default to no permissions on any calendars
    * Day view defaults to the first of the month when not viewing
      current month
    * Added calendar switching mechanism at bottom of month view
    * Fixed problems displaying <br> tags in event text
    * Updated to be in synch with calendar from SquirrelMail 1.2.11
    * Internationalized all shared calendar text output
    * Updated for compatibility with Plugin Updates plugin

