Difference: CalDAVPlugin (r2 vs. r1)

r2 - 26 Jan 2011 - 12:55 - AdminUser r1 - 26 Jan 2011 - 12:55 - AdminUser

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.

On this page:

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`

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`

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`

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.

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'

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'

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'
};

$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.

Apple, Inc.

Author(s):

Crawford Currie http://c-dot.co.uk

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