TIP ICalPlugin is not installed on Foswiki.org.


Access ical data in wikiapps


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.


An example is provided in the ICalHolidayListDemo.



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.


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
I Attachment Action Size Date Who Comment
ICalPlugin.md5md5 ICalPlugin.md5 manage 153 bytes 26 Oct 2020 - 07:49 MichaelDaum  
ICalPlugin.sha1sha1 ICalPlugin.sha1 manage 177 bytes 26 Oct 2020 - 07:50 MichaelDaum  
ICalPlugin.tgztgz ICalPlugin.tgz manage 18 K 26 Oct 2020 - 07:49 MichaelDaum  
ICalPlugin.zipzip ICalPlugin.zip manage 25 K 26 Oct 2020 - 07:49 MichaelDaum  
ICalPlugin_installerEXT ICalPlugin_installer manage 5 K 26 Oct 2020 - 07:49 MichaelDaum  
Topic revision: r11 - 26 Oct 2020, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy