(r6) ICalPlugin < Extensions

You are here: Foswiki>Extensions Web>ICalPlugin (revision 6) (raw view)
<!--
This topic is part of the documentation for ICalPlugin and is
automatically generated from Subversion. You can edit it, but if you do,
please make sure the maintainer of the extension knows about your changes,
otherwise your edits might be lost the next time the topic is uploaded.

If you want to report an error in the topic, please raise a report at
http://foswiki.org/Tasks/ICalPlugin
-->
---+!! %TOPIC%
%SHORTDESCRIPTION%

%TOC%

---++ Description

This plugin allows you to do two things:

   1 read, parse and format ical files attached to a topic
   1 cache event data stored in a System.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:

<verbatim>
    * Set ICALPLUGIN_CALENDAR = MyWeb.MyTopic.calendar.ics
</verbatim>

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

---++ Examples

An example is provided in the Sandbox.ICalHolidayListDemo. 

---++ Syntax

=%<nop>FORMATICAL{...}%=

| *Parameter* | *Description* | *Default* |
| topic | specifies the topic where to read the ical attachment file from | %<nop>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 | |

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

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


---++ Info
<!--
   * Set SHORTDESCRIPTION = Access ical data in wikiapps
-->

|  Author(s): | Michael Daum|
|  Copyright: | &copy; 2011-2012 Michael Daum http://michaeldaumconsulting.com |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Release: | 1.12 |
|  Version: | 14778 (2012-05-08) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  08 May 2012 | fixed processing of weekly recurrences without a <nop>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 |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">DateTime</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><tr><td align="left">Data::ICal</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">DateTime::Set</td><td align="left">&gt;=0</td><td align="left">Required</td></tr><tr><td align="left">Foswiki::Plugins::MetaDataPlugin</td><td align="left">&gt;=1.1</td><td align="left">Optional</td></tr></table> |
|  Home page: | Foswiki:Extensions/%TOPIC% |
|  Support: | Foswiki:Support/%TOPIC% |
PackageForm edit

ExtensionClassification	Data and Files
ExtensionType	PluginPackage
Compatibility
ImageUrl
DemoUrl	http://michaeldaumconsulting.com
SupportUrl	ICalPlugin
DevelopedInSVN	Yes
ModificationPolicy	CoordinateWithAuthor
Topic attachments
I	Attachment	Action	Size	Date	Who
md5	ICalPlugin.md5	manage	0.1 K	08 May 2012 - 15:09	MichaelDaum
sha1	ICalPlugin.sha1	manage	0.2 K	08 May 2012 - 15:09	MichaelDaum
tgz	ICalPlugin.tgz	manage	14.8 K	08 May 2012 - 15:09	MichaelDaum
zip	ICalPlugin.zip	manage	19.0 K	08 May 2012 - 15:09	MichaelDaum
EXT	ICalPlugin_installer	manage	4.5 K	08 May 2012 - 15:09	MichaelDaum
Topic revision: r6 - 08 May 2012, MichaelDaum
Extensions
Quick Links

Tools

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement.