CalDAVPlugin

Extract a list of events from a CalDAV (iCal) server

This plugin provides a link between a remote CalDAV server and the CalendarPlugin. CalDAV is a protocol used by many calendaring applications, two of the most notable being Apple's iCal, and Google calendar.

The plugin works by accessing a calendar on the CalDAV server and generating an event list in the "bulleted event list" format that the CalendarPlugin (and HolidaylistPlugin) can use.

Note that the CalDAVPlugin will generate individual events for recurrences. The limits for the number of events generated for each recurrence can be configured using the stop parameter.

Usage

Put the macro %CALDAV{"calendar"}% anywhere on a topic. This will generate a bulleted list when the macro is expanded. The CalendarPlugin (and HolidaylistPlugin) will automatically pick up the events from this list.

Source parameters

Parameter	Meaning	Default
"calendar"	The name of a pre-declared calendar (see Installation, below)	none; if you don't provide this, you have to specify url, user and pass.
url	The url of a remote calendar you want to view	from calendar
user	Username used to access the remote calendar	from calendar
pass	Password for the user used to access the remote calendar	from calendar

Generator parameters

Parameter	Meaning	Default
stop	Hard stop for recurrences. This takes two values, separated by commas. The first value specifies the maximum number of events generated by a single recurrence, and the second value specifies the maximum number of days to generate events for. For example, stop="50,365" will prevent any recurrence generating more than 50 events, or any events more than 365 days from now.	50,365
target	Name of a predefined target format e.g. calendar for the CalendarPlugin or holidaylist for the HolidayListPlugin.	calendar
event	Format of an individual event. If target is given, this parameter will override the default provided by the target.	target
range	Format of an event range. If target is given, this parameter will override the default provided by the target.	target
separator	String used to separate events in the output	$n

Any other named parameters will be passed on to the output via the corresponding format token.

The output is generated by expanding format tokens in the event and range format parameters as appropriate. The tokens expanded from the event data are:

Token	Meaning
$second (seconds, 00..59) $minute (minutes, 00..59) $hour (hours, 00..23) $day (day of month, 01..31) $month (month, 01..12) $mon (month in text format, Jan..Dec) $year (4 digit year, 1999) $ye (2 digit year, 99) $wd (day of the week, 1 for Sunday, 2 for Monday, etc) $wday (day of the week, Sun..Sat) $weekday (day of the week, Sunday..Saturday) $yearday (day of the year)	Event time (or start time for a range)
As above, but with e at the start of the name e.g. $esecond, $eminute etc.	Range end time
$summary	Event summary
$description	Event (full) description
$param	where param is the name of a parameter to %CALDAV e.g. $icon

All standard format tokens are supported (once all the above format tokens have been expanded).

Tip you can hide the bulleted list that the %CALDAV macro generates by enclosing it in HTML comments e.g.

<!--
%CALDAV{"GeorgeWShrub" target="holidaylist"}%
-->

CalendarPlugin

The events generated when using the target="calendar" format use the following formats:

• event='$day $month $year - $summary'
• range='$day $month $year - $eday $emonth $eyear - $summary'

Example: %CALDAV{"Jean" target="calendar"}%

HolidaylistPlugin

• event='$day $month $year - $name - $summary - $icon'
• range='$day $month $year - $eday $emonth $eyear - $name - $summary - $icon'

$name is the calendar name, or can be overridden by a name parameter. $icon is taken from the parameter of the same name, and is a fragment of TML that generates an icon. It defaults to the empty string.

Example: %CALDAV{"UK" icon="$percntICON{ukflag}$percnt" target="holidaylist"}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Use configure to set up any pre-declared calendars you want to access. Example configuration:

$Foswiki::cfg{Plugins}{CalDAVPlugin}{Calendars} = {
   home => {
      url => 'http://127.0.0.1/caldav.php/simon/home/Home.ics',
      user => 'simon',
      pass => 'xxx'
   },
   office => {
      url => 'http://calendar.corp.com/simple/simon',
      user => 'caladmin',
      pass => 'yyy'
};

This configures two calendars, 'home' and 'office'. The parameters specify the CalDAV server - for more information on what these parameters mean, see the CalDAV module on CPAN

Pre-declaring calendars is obviously important from a perspective of protecting sensitive username and password information. Unfortunately there is no way to limit access to remote calendars based on the logged-in user.

Info

Many thanks to the following sponsors for supporting this work:

• Apple, Inc.

Author(s):	Crawford Currie http://c-dot.co.uk
Copyright:	© 2010 Foswiki Contributors
License:	GPL (Gnu General Public License)
Release:	1.001
Version:	8317 (2010-07-26)
Change History:
1.001 (26 Jul 2010)	Foswiki:Tasks/Item9392: Fix loading of configured calendars
1.000 (7 Jul 2010)	Initial release
Dependencies:	Name Version Description Cal::DAV >=0 Required DateTime::Format::ICal >=0 Required
Home page:	http://foswiki.org/bin/view/Extensions/CalDAVPlugin
Support:	http://foswiki.org/bin/view/Support/CalDAVPlugin