aw schriftzug.png aw logo 60x60.png

ICalPlugin

Access ical data in wikiapps

Description

This plugin allows you to do two things:

  1. read, parse and format ical files attached to a topic
  2. cache event data stored in a DataForms or MetaData into an ical file

ICal is a format for storing calendar information in it. This format is supported by almost all calendar applications and tools. The most obvious way to get started with this plugin is to open your calendar tool of choise, export your calendar data as an ical file, and attach it to some wiki topic. This ical file will now be available as a kind of database holding calendar data and is accessible using the %FORMATICAL macro. This macro comes with a range of options to select specific parts of your ical data and format it to be displayed on the wiki page.

The second function if this plugin is to automatically generate an ical file based on Event information stored in a Foswiki DataForm. This DataForm has to adhere to a certain structure to server as a source for Event information. A minimum example is provided in the EventTopic DataForm definition.

This DataForm holds all the information, including recurrences of different types, to be convert into a VEVENT record to be stored in a given ical file. Whenever a topic with an EventTopic DataForm attached to it is modified or deleted, will the ICalPlugin take care of updating the ical file serving as a cache to all EventTopic information available in the wiki (or part of the wiki).

Note that the EventTopic requires a TopicType formfield which holds the list of types this form fulfills. The tag EventTopic in it is mandatory for the ICalPlugin to know that this DataForm stores VEVENT data. Only then will a DataForm be harvested to update the ical file associated with it.

In addition to normal Foswiki DataForms, the ICalPlugin also supports event data to be stored in %META:EVENT records stored as Foswiki meta data. The format of a %META:EVENT record is exactly the same as defined in the EventTopic. Event more, with the use of the Foswiki:Extensions/MetaDataPlugin, the EventTopic DataForm definition can be extended to your needs and all %META:EVENT records will follow as well. This however is more of a feature of the MetaDataPlugin allowing you to store multiple DataForm records as meta data records attached to one single topic. So instead of storing EventTopic data one per wiki topic, you can also chose to store all of your event records into a single topic in the %META:EVENT format.

Finally, ICalPlugin will update data harvested from DataForms and event MetaData into an ical file attached to some topic. Specify the address of this file using the ICALPLUGIN_CALENDAR preference variable like this:

    * Set ICALPLUGIN_CALENDAR = MyWeb.MyTopic.calendar.ics

This file can then be integrated into your calendar application on your desktop.

Examples

An example is provided in the ICalHolidayListDemo.

Syntax

%FORMATICAL{...}%

Parameter Description Default
url fetch ical data from the given url  
text specifies ical data inline  
topic specifies the topic where to read the ical attachment file from %BASETOPIC%
attachment the name of an ical calendar file attached to the topic specified in the topic parameter calendar.ics
raw if set to on the selected result is returned in raw ical format off
start starting time of the span within which to format ical events; this can be any date format understood by foswiki, e.g. 2012-02-13 or iso date format current time
span time span starting at start for which to format the ical events 1 month
end ending time of the span for which to format ical events; note that the parameters span and end exclude each other with end taking higher precedence  
skip number of items to skip while formating ical events; this parameter is used to implement paging within the selected time span 0
limit maximum number of events to format; if not specified, all events are rendered  
sort sorting criterion of ical events; common values are start (same as on), end or any other property of an ical event record off
format specifies the format string used to render an event within the selected time span  
eventformat format string used for a single event format
rangeformat format string used to render a range event format
header format string prepended to the result when any event data has been found within the specified time span  
footer format string appended to the result when any event data has been found within the specified time span  
separator format string used to separate event records while formating them  

Only one of the sources may be specified in either url, text or topic / attachment (precedence in the given order).

The format string parameters format, eventformat and rangeformat can take a range of variables to refer to properties of the event record about to be rendered. These are:

  • $location
  • $start
  • $end
  • $until
  • $modified
  • $created
  • $description
  • $attendee
  • $organizer
  • $summary

Properties, i.e. those that may return multi-line results such as $description and $summary, may be expanded using $plainify(<key>). This will fetch the value of the given key and "plainify" it in a way that they may be used in TML table markup where cells must not contain multi-line values as that would break table markup.

Create, modified, start and end time properties of an ical event can be formatted in more detail using the following variables within the format strings.

Variables referring to the start date:

  • $sec, $second, $seconds
  • $min, $minute, $minutes
  • $hour, $hours
  • $day
  • $wday
  • $dow
  • $week
  • $mon, $month
  • $mo
  • $year
  • $ye
  • $epoch

Variables referring to the end date are using an e prefix to the variables:

  • $esec, $esecond, $eseconds
  • $emin, $eminute, $eminutes
  • $ehour, $ehours
  • $eday
  • $ewday
  • $edow
  • $eweek
  • $emon, $emonth
  • $emo
  • $eyear
  • $eye
  • $eepoch

Variables referring to the create date of an event are using a c prefix:

  • $csec, $csecond, $cseconds
  • $cmin, $cminute, $cminutes
  • $chour, $chours
  • $cday
  • $cwday
  • $cdow
  • $cweek
  • $cmon, $cmonth
  • $cmo
  • $cyear
  • $cye
  • $cepoch

Variables referring to the modification date of an event use an m prefix:

  • $msec, $msecond, $mseconds
  • $mmin, $mminute, $mminutes
  • $mhour, $mhours
  • $mday
  • $mwday
  • $mdow
  • $mweek
  • $mmon, $mmonth
  • $mmo
  • $myear
  • $mye
  • $mepoch

Finally, the standard foswiki escape variables are expanded:

  • $n
  • $percnt
  • $dollar

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. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

NameVersionDescription
DateTime>=0Required
DateTime::Format::ICal>=0Required
Data::ICal>=0Required
DateTime::Set>=0Required
Foswiki::Plugins::MetaDataPlugin>=4.0Optional
Foswiki::Plugins::TopicTitlePlugin>1.00Required for Foswiki < 2.2

Change History

26 Oct 2020 return infinite values for missing start or end dates … which fixes use of undefined values; convert timezone information to local time; fix multiple memory problems; added parameters url, text and $plainify(); fixed unicode encoding problems reading ics files
11 Jun 2018 internal api rework
28 Aug 2014 depend on MetaDataPlugin >= 4.0
07 Nov 2013 fixed use of deprecated perl syntax in foreach loops
21 Jun 2012 fixed unintended redirect after save when accessing a view restricted data form
08 May 2012 fixed processing of weekly recurrences without a StartDate
07 May 2012 made dependency on Foswiki:Extensions/MetaDataPlugin optional
27 Apr 2012 expand macros in ICALPLUGIN_CALENDAR variable; process all meta data records whose DataForm have a TopicType of "EventTopic"
26 Apr 2012 be more robust against malformed date strings
25 Apr 2012 initial release

PackageForm edit

Author Michael Daum
Version 3.00
Release 26 Oct 2020
Description Access ical data in wikiapps
Repository https://github.com/foswiki/ICalPlugin
Copyright © 2011-2020 Michael Daum
License GPL (Gnu General Public License)
Home Foswiki:Extensions/ICalPlugin
Support Foswiki:Support/ICalPlugin
Topic revision: r1 - 2020-10-26, UnknownUser
This site is powered by FoswikiCopyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Wiki? Send feedback