Changeset 8063

Timestamp:

07/07/10 15:44:23 (23 months ago)

Author:

CrawfordCurrie

Message:

Item8421: add redefined output formats to better support FullCalendarPlugin and other calendering apps (e.g. by generating JSON for client-side)

Location:

trunk/CalDAVPlugin

Files:

• data/System/CalDAVPlugin.txt (modified) (3 diffs)
• lib/Foswiki/Plugins/CalDAVPlugin.pm (modified) (2 diffs)
• lib/Foswiki/Plugins/CalDAVPlugin/Config.spec (modified) (1 diff)
• lib/Foswiki/Plugins/CalDAVPlugin/Core.pm (modified) (7 diffs)

trunk/CalDAVPlugin/data/System/CalDAVPlugin.txt

@@ -8 +8 @@
 [[http://en.wikipedia.org/wiki/CalDAV][CalDAV]] server and the
 CalendarPlugin. !CalDAV is a protocol used by many calendaring applications,
-the most notable being iCal on Apple products.
+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 uses.
+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. The
-CalendarPlugin will automatically pick up the events from it.
+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.
 
-| *Parameter* | *Meaning* |
-| ="calendar"= | The name of a declared calendar |
-| =url= | The url of a remote calendar you want to view |
-| =user= | Username used to access the remote calendar |
-| =pass= | Password for the user used to access the remote calendar |
-| =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"= (the default) will prevent any recurrence generating more than 50 events, or any events more than 365 days from now. |
+*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= |
 
-For obvious security reasons, you are recommended to use the ="calendar"= method to specify the calendar to retrieve.
+*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.
 
-Note that the !CalendarPlugin does not support a wide range of recurrences,
-and the !CalDAVPlugin will generate individual events for recurrences that
-it can't map to the !CalendarPlugin. The limits for the number of events
-generated for each recurrence can be configured using the plugin parameters.
+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
@@ -38 +78 @@
 %$INSTALL_INSTRUCTIONS%
 
-Use =configure= to set up the calendars you want to access.
+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.
+   * Apple, Inc.
 
 |  Author(s): | Crawford Currie http://c-dot.co.uk |
@@ -50 +110 @@
 |  Version: | %$VERSION% |
 |  Change History: | <!-- versions below in reverse order -->&nbsp; |
+|  1.000 (7 Jul 2010) | Initial release |
 |  Dependencies: | %$DEPENDENCIES% |
 |  Home page: | http://foswiki.org/bin/view/Extensions/CalDAVPlugin |

trunk/CalDAVPlugin/lib/Foswiki/Plugins/CalDAVPlugin.pm

@@ -5 +5 @@
 
 ---+ package Foswiki::Plugins::CalDAVPlugin
-
-When developing a plugin it is important to remember that
-Foswiki is tolerant of plugins that do not compile. In this case,
-the failure will be silent but the plugin will not be available.
-See %SYSTEMWEB%.InstalledPlugins for error messages.
-
-__NOTE:__ Foswiki:Development.StepByStepRenderingOrder helps you decide which
-rendering handler to use. When writing handlers, keep in mind that these may
-be invoked on included topics. For example, if a plugin generates links to the
-current topic, these need to be generated before the =afterCommonTagsHandler=
-is run. After that point in the rendering loop we have lost the information
-that the text had been included from another topic.
-
-__NOTE:__ Not all handlers (and not all parameters passed to handlers) are
-available with all versions of Foswiki. Where a handler has been added
-(or deprecated) the POD comment will indicate this with a "Since" line
-e.g. *Since:* Foswiki::Plugins::VERSION 1.1
-
-See http://foswiki.org/Download/ReleaseDates for a breakdown of release
-versions.
 
 =cut
@@ -34 +14 @@
 
 our $VERSION = '$Rev: 7888 $';
-our $RELEASE = '1.1.1';
+our $RELEASE = '1.000';
 our $SHORTDESCRIPTION = 'Extract a list of events from a CalDAV (iCal) server';
 our $NO_PREFS_IN_TOPIC = 1;
 
 sub initPlugin {
-    my ( $topic, $web, $user, $installWeb ) = @_;
-
+    # my ( $topic, $web, $user, $installWeb ) = @_;
     Foswiki::Func::registerTagHandler( 'CALDAV', \&_CALDAV );
-
     return 1;
 }
 
 sub _CALDAV {
-    my($session, $params, $theTopic, $theWeb) = @_;
+    # my($session, $params, $topic, $web) = @_;
 
     require Foswiki::Plugins::CalDAVPlugin::Core;

trunk/CalDAVPlugin/lib/Foswiki/Plugins/CalDAVPlugin/Config.spec

@@ -2 +2 @@
 #---++ CalDAVPlugin
 # **PERL**
-# Set of calendars that can be accessed using shortcuts frm the CALDAV macro.
+# Set of calendars that can be accessed using shortcuts form the CALDAV macro.
 # Each calendar specification must include a user, password and url.
 $Foswiki::cfg{Plugins}{CalDAVPlugin}{Calendars} = {
-   home => {
-      url => 'http://simian:x@192.168.1.12/caldav.php/simian/home/Home.ics',
-      user => 'simian',
-      pass => 'x'
+   example => {
+      url => 'http://example.com/caldav.php/example',
+      user => 'example',
+      pass => 'example'
    },
 };

trunk/CalDAVPlugin/lib/Foswiki/Plugins/CalDAVPlugin/Core.pm

@@ -1 +1 @@
 # See bottom of file for license and copyright information
 package Foswiki::Plugins::CalDAVPlugin::Core;
+
+use strict;
+use warnings;
 
 use Cal::DAV;
@@ -6 +9 @@
 use DateTime::Format::ICal;
 
-# Target formats
-# dd MMM yyyy - description
-#   * 09 Dec 2002 - Expo
-# dd MMM yyyy - dd MMM yyyy - description
-#   * 02 Feb 2002 - 04 Feb 2002 - Vacation
-# dd MMM - description
-#   * 05 Jun - Every 5th of June
-# w DDD MMM - description
-#   * 2 Tue Mar - Every 2nd Tuesday of March
-# rrule: FREQ=MONTHLY
-# L DDD MMM - description
-#   * L Mon May - The last Monday of May
-# rrule: FREQ=MONTHLY
-# A dd MMM yyyy - description
-#   * A 20 Jul 1969 - First moon landing
-# FREQ=YEARLY
-# w DDD - description
-#   * 1 Fri - Every 1st Friday of the month
-# FREQ=MONTHLY,BYDAY=FR
-# L DDD - description
-#   * L Mon - The last Monday of each month
-# dd - description      
-#   * 14 - The 14th of every month
-# E DDD - description
-#   * E Wed - Every Wednesday
-# E DDD dd MMM yyyy - description
-#   * E Wed 27 Jan 2005 - Every Wednesday Starting 27 Jan 2005
-# E DDD dd MMM yyyy - dd MMM yyyy - description
-#   * E Wed 1 Jan 2005 - 27 Jan 2005 - Every Wednesday from 1 Jan 2005 through 27 Jan 2005 (inclusive)
-# En dd MMM yyyy - description
-#   * E3 02 Dec 2002 - Every three days starting 02 Dec 2002
-# En dd MMM yyyy - dd MMM yyyy - description
-#   * E3 12 Apr 2005 - 31 Dec 2005 - Every three days from 12 Apr 2005 through 31 Dec 2005 (inclusive) 
+my %formats = (
+    calendar => {
+        event => '   * $day $month $year - $summary',
+        range => '   * $day $month $year - $eday $emonth $eyear - $summary',
+    },
+    holidaylist => {
+        event => '   * $day $month $year - $name - $summary - $icon',
+        range => '   * $day $month $year - $eday $emonth $eyear - $name - $summary',
+    },
+   );
+
+use constant TRACE => 1;
+
+=begin TML
+
+---++ StaticMethod CALDAV($session, $params, $topic, $web)
+
+Macro handler, indirected via CalDAVPlugin.pm
+
+Read CalDAV data from a remote server and generate output in a format
+suitable for use by different plugins.
+
+You can define an output format (using the 'target' parameter), or
+select from a range of predefined formats. 'header', 'footer' and
+'separator' have conventional interpretations, and all standard formatting
+tokens are supported.
+
+=cut
 
 sub CALDAV {
@@ -67 +65 @@
     my $cal;
     eval {
-       $cal = Cal::DAV->new( user => $user, pass => $pass, url => $url);
+        $cal = Cal::DAV->new( user => $user, pass => $pass, url => $url);
     };
     unless ($cal) {
@@ -73 +71 @@
         return "<span class='foswikiAlert'>Calendar could not be opened</span>";
     }
+
+    $params->{name} = $calendar unless defined $params->{name};
+    $params->{name} = $params->{url} unless defined $params->{name};
+    $params->{separator} = '$n()' unless defined $params->{separator};
 
     my $stop = $params->{stop};
@@ -92 +94 @@
                 $event{start} =
                   DateTime::Format::ICal->parse_datetime($p->value);
-                push(@events, "# dtstart ".$event{start});
+                push(@events, " dtstart ".$event{start}) if (TRACE);
             } elsif ($k eq 'dtend') {
                 $event{end} =
                   DateTime::Format::ICal->parse_datetime($p->value);
-                push(@events, "# dtend ".$event{end});
+                push(@events, " dtend ".$event{end}) if (TRACE);
             } elsif ($k eq 'summary') {
+                $event{summary} = $p->{value};
+                push(@events, " summary ".$event{summary}) if (TRACE);
+            } elsif ($k eq 'description') {
                 $event{description} = $p->{value};
-                $event{description} =~ s/\n/<br>/gs;
             } elsif ($k eq 'rrule') {
-                push(@events, "# rrule $p->{value}");
+                push(@events, " rrule $p->{value}") if (TRACE);
                 $event{recurrence} = $p->{value};
             }
@@ -113 +117 @@
                 recurrence => $event{recurrence},
                 dtstart => $event{start});
-            # Limit to the request range *or* $stopDays *or* $stopCount repeats
+            # Limit to the request range *or* $stopDays *or*
+            # $stopCount repeats
             my $span = DateTime::Span->from_datetimes(
                 start => $event{start} ||
@@ -122 +127 @@
             $event{count} = $stopCount if ($event{count} > $stopCount);
 
-            push(@events, "   * ".Foswiki::Time::formatTime(
-                Foswiki::Time::parseTime($event{start}))
-                   . ' - '.$event{description});
+            my $s = Foswiki::Time::parseTime($event{start});
+            push(@events,
+                 {
+                     start => $s,
+                     summary => $event{summary},
+                     description => $event{description},
+                 });
             $event{count}--;
             my $iter = $recur->iterator(span => $span);
             while ( $event{count} && (my $dt = $iter->next) ) {
-                push(@events, "   * " . Foswiki::Time::formatTime(
-                    Foswiki::Time::parseTime($dt))
-                   . ' - '.$event{description});
+                my $d = Foswiki::Time::parseTime($dt);
+                next if $d == $s;
+                push(@events,
+                     {
+                         start => $d,
+                         summary => $event{summary},
+                         description => $event{description},
+                     });
                 $event{count}--;
             }
         } else {
-            my $evs = Foswiki::Time::formatTime(
-                    Foswiki::Time::parseTime($event{start}));
-            if (defined $event{end}) {
-                $evs .= ' - '.Foswiki::Time::formatTime(
-                    Foswiki::Time::parseTime($event{end}));
-            }
-            $evs .= ' - '.$event{description};
-            push(@events, "   * $evs");
+            push(@events,
+                 {
+                     start => Foswiki::Time::parseTime($event{start}),
+                     end => (defined $event{end}) ?
+                       Foswiki::Time::parseTime($event{end}) : undef,
+                     summary => $event{summary},
+                     description => $event{description},
+                 });
         }
     }
-    return "\n".join("\n", @events)."\n";
+    return _formatEvents(\@events, $params);
+}
+
+sub _formatEvents {
+    my ($events, $params) = @_;
+
+    my $format;
+    my $target = $params->{target} || 'calendar';
+    if ($target) {
+        $format = $formats{$target} || $formats{calendar};
+    }
+    my $es = $params->{event};
+    $es = $format->{event} unless defined $es;
+    my $rs = $params->{range};
+    $rs = $format->{range} unless defined $rs;
+    my @r = map { _formatEvent($_, $params, $es, $rs) } @$events;
+    return Foswiki::Func::decodeFormatTokens(join($params->{separator}, @r));
+}
+
+sub _formatEvent {
+    my ($event, $params, $es, $rs) = @_;
+    return $event unless ref($event);
+    my $s = (defined $event->{end}) ? $rs : $es;
+    $s = Foswiki::Time::formatTime($event->{start}, $s);
+    if (defined $event->{end}) {
+        $s =~ s/\$e(seco?n?d?s?|minu?t?e?s?|hour?s?|day|w(eek|day)|dow
+                |mo(?:nt?h?)?|ye(?:ar)?)(\(\)|(?=\W|$))/\$$1/gx;
+        $s = Foswiki::Time::formatTime($event->{end}, $s);
+    }
+    foreach my $f (keys %$event) {
+        $s =~ s/\$$f(\(\)|(?=\W|$))/$event->{$f}/;
+    }
+    foreach my $f (keys %$params) {
+        next if $f =~ /^_/;
+        $s =~ s/\$$f(\(\)|(?=\W|$))/$params->{$f}/;
+    }
+    return $s;
 }