(r1) CalDAVPlugin < System

You are here: Foswiki>System Web>CalDAVPlugin~~EditAttach~~
---+!! !CalDAVPlugin
<!--
   * Set SHORTDESCRIPTION = Extract a list of events from a !CalDAV (iCal) server
-->
%SHORTDESCRIPTION%

This plugin provides a link between a remote
[[http://en.wikipedia.org/wiki/CalDAV][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.

%TOC%

---++ Usage
Put the macro =%<nop>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)<br/> =$minute= (minutes, 00..59)<br/> =$hour= (hours, 00..23)<br/> =$day= (day of month, 01..31)<br/> =$month= (month, 01..12)<br/> =$mon= (month in text format, Jan..Dec)<br/> =$year= (4 digit year, 1999)<br/> =$ye= (2 digit year, 99)<br/> =$wd= (day of the week, 1 for Sunday, 2 for Monday, etc)<br/> =$wday= (day of the week, Sun..Sat)<br/> =$weekday= (day of the week, Sunday..Saturday)<br/> =$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 %<nop>CALDAV e.g. =$icon= |

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

__Tip__ you can hide the bulleted list that the %<nop>CALDAV macro generates
by enclosing it in HTML comments e.g.
<verbatim>
<!--
%CALDAV{"GeorgeWShrub" target="holidaylist"}%
-->
</verbatim>

---+++ !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: =%<nop>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: =%<nop>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:
<verbatim>
$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'
};
</verbatim>
This configures two calendars, 'home' and 'office'. The parameters specify
the !CalDAV server - for more information on what these parameters mean, see [[http://search.cpan.org/~simonw/Cal-DAV-0.6/lib/Cal/DAV.pm][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: | &copy; 2010 Foswiki Contributors |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Release: | 1.001 |
|  Version: | 8317 (2010-07-26) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  1.001 (26 Jul 2010) | Foswiki:Tasks/Item9392: Fix loading of configured calendars |
|  1.000 (7 Jul 2010) | Initial release |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Cal::DAV</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">DateTime::Format::ICal</td><td align="left">&gt;=0</td><td align="left">Required</td></tr></table> |
|  Home page: | http://foswiki.org/bin/view/Extensions/CalDAVPlugin |
|  Support: | http://foswiki.org/bin/view/Support/CalDAVPlugin |

<!-- Do _not_ attempt to edit this topic; it is auto-generated. -->
Topic revision: r1 - 26 Jan 2011, AdminUser
System
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback