]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/todo/Set_arbitrary_date_to_be_used_by_calendar_plugin.mdwn
Merge commit 'upstream/master' into pub/master
[git.ikiwiki.info.git] / doc / todo / Set_arbitrary_date_to_be_used_by_calendar_plugin.mdwn
index 26f293b86a500207119e40dd3b284b46355897f6..a2643391927cfe399ad00a119dc5e25250b2f2b4 100644 (file)
-[[tag patch]]
+[[!tag patch]]
 
-Here's a patch to the calendar plugin. If you specify an event preprocessor in a post, such as:
+Here's my next version of the patch - still a work in progress.
 
-    [[event time="2008-06-24"]]
+It provides the following new features. The features are designed to preserve the behavior of the existing plugin by default.
 
-That date will be used instead of the post creation time when displaying the calendar.
+ * If you specify an event preprocessor in a post, such as:
 
-> Thanks for coming up with a patch.. Let me make sure I understand its
-> rationalle.
-> 
-> The meta plugin already allows modifying the page creation time,
-> which is what the calendar plugin uses.
-> 
-> So, it seems to me that the use of this patch is for recording events in
-> the future. You'd not want a page for a future event to claim it was
-> created in the future. I suppose you could also use it for events in the
-> past, if you didn't want to change the creation time for some reason.
-> (Perhaps you're doing a calendar of historical events, for example.)
->
-> Accurate? --[[Joey]]
+    [[!event time="2008-06-24"]]
 
->> Thanks for the feedback. Thinking about what you said ... I suspect my patch 
->> doesn't belong in the calendar plugin, which does a very specific thing 
->> (create a calendar to show when blog posts were created). I'm really angling 
->> toward an event calendar (as mentioned on [[todo/plugin]]). I'd like to preserve 
->> the page creation time - which is useful and important information in its own right 
->> - and be able to generate a calendar with links to particular posts that will show 
->> up on the calendar based on an arbitrary date. Perhaps this should be re-considered 
->> as a separate plugin? --[[Jamie]]
+ That date will be used instead of the post creation time when displaying the calendar.
 
->>> I think it makes sense to have only one calendar, if possible.
->>> I think your event stuff is fine, the only thing we might want to add
->>> is a config option for the calendar, to control whether it looks at the
->>> event date, or the creation date. --[[Joey]]
+ * When specifying a calendar preprocessor, you can now add the following new parameters:
 
->>>> Ok - I can work on that. One question - the existing calendar module has it's own 
->>>> functions for building an html display of a calendar. HTML::CalendarMonth seems to 
->>>> provide that functionality. My instincts are to rip out the code in the calendar plugin
->>>> and use the existing module. On the other hand, that creates added dependencies. 
->>>> Suggestions anyone? --[[Jamie]]
+  * time_src: by default it is set to auto. auto means that when determining the date to use for a given post, take the date given in the event preprocessor directive if it exists and if not, use the creation time of the post. The other option is event which means: take the date given in the event preprocessor directive. If there is not event preprocessor in a post, don't include the post.
+  * detail: by default it is set to 0. If set to 0, display the monthly calendar as a series of days. Each day is a link to the post on that day. If there is more than one post on a day, only one is linked to. If set to 1 - then display the title of each post on the day as a link to the post. Is 0 and 1 the best values here? On/Off? Yes/no?
 
->>>>> I'm all for ripping code out of ikiwiki where CPAN can be used, as
->>>>> long as the resulting code and html are good. --[[Joey]]
+The following changes are in the works:
 
+ * Switch to using HTML::CalendarMonth to create the html output
 
-    --- calendar.pm.orig  2008-06-24 22:36:09.000000000 -0400
-    +++ calendar.pm 2008-06-24 22:51:11.000000000 -0400
-    @@ -23,6 +23,7 @@
-     use IkiWiki 2.00;
-     use Time::Local;
-     use POSIX;
-    +use Date::Parse;
-  
-     my %cache;
-     my %linkcache;
-    @@ -32,6 +33,7 @@
-     sub import { #{{{
-      hook(type => "needsbuild", id => "version", call => \&needsbuild);
-      hook(type => "preprocess", id => "calendar", call => \&preprocess);
-    + hook(type => "preprocess", id => "event", call => \&preprocess_event);
-     } #}}}
-  
-     sub is_leap_year (@) { #{{{
-    @@ -304,6 +306,19 @@
-      return $calendar;
-     } #}}}
-  
-    +sub preprocess_event (@) { #{{{
-    + my %params=@_;
-    + # if now time is given, use now
-    + $params{time} = localtime            unless defined $params{time};
-    +
-    + my $timestamp = str2time($params{time});
-    + if ( defined $timestamp) {
-    +   $pagestate{$params{page}}{event}{mtime}=$timestamp;
-    + }
-    + # remove the event block entirely
-    + return "";
-    +} #}}
-    +
-     sub preprocess (@) { #{{{
-      my %params=@_;
-      $params{pages} = "*"            unless defined $params{pages};
-    @@ -355,7 +370,13 @@
-      if (! defined $cache{$pagespec}) {
-        foreach my $p (keys %pagesources) {
-          next unless pagespec_match($p, $pagespec);
-    -     my $mtime = $IkiWiki::pagectime{$p};
-    +     my $mtime;
-    +     # use time defined by event preprocessor if it's available
-    +     if (defined $pagestate{$p}{event}{mtime}) {
-    +       $mtime = $pagestate{$p}{event}{mtime};
-    +     } else {
-    +       $mtime = $IkiWiki::pagectime{$p};
-    +     }
-          my $src   = $pagesources{$p};
-          my @date  = localtime($mtime);
-          my $mday  = $date[3];
+ * Display the start time when detail is set to 1. 
+
+Longer term plans:
+
+ * Support recurring events
+ * Support for end time on events (including end time that is on a different day than the start time)
+
+ * Convincing the world to switch to base 10 calendar system.
+
+
+               --- calendar.pm.orig    2008-06-24 22:36:09.000000000 -0400
+               +++ calendar.pm 2008-06-28 22:02:15.000000000 -0400
+               @@ -23,6 +23,8 @@
+                use IkiWiki 2.00;
+                use Time::Local;
+                use POSIX;
+               +use Date::Parse;
+               +use Data::Dumper;
+                
+                my %cache;
+                my %linkcache;
+               @@ -32,6 +34,7 @@
+                sub import { #{{{
+                       hook(type => "needsbuild", id => "version", call => \&needsbuild);
+                       hook(type => "preprocess", id => "calendar", call => \&preprocess);
+               +       hook(type => "preprocess", id => "event", call => \&preprocess_event);
+                } #}}}
+                
+                sub is_leap_year (@) { #{{{
+               @@ -58,6 +61,7 @@
+                       my $nmonth   = $params{nmonth};
+                       my $pyear    = $params{pyear};
+                       my $nyear    = $params{nyear};
+               +       my $detail   = $params{detail};
+                
+                       my @list;
+                       my $calendar="\n";
+               @@ -153,33 +157,58 @@
+                               }
+                               
+                               my $tag;
+               +               my $display_day;
+                               my $mtag = sprintf("%02d", $month);
+               -               if (defined $cache{$pagespec}{"$year/$mtag/$day"}) {
+               -                       if ($day == $today) {
+               +               if ($day == $today) {
+                                               $tag='month-calendar-day-this-day';
+               -                       }
+               -                       else {
+               -                               $tag='month-calendar-day-link';
+               -                       }
+               -                       $calendar.=qq{\t\t<td class="$tag $downame{$wday}">};
+               -                       $calendar.=htmllink($params{page}, $params{destpage}, 
+               -                                           pagename($linkcache{"$year/$mtag/$day"}),
+               -                                           "linktext" => "$day");
+               -                       push @list, pagename($linkcache{"$year/$mtag/$day"});
+               -                       $calendar.=qq{</td>\n};
+               +               }
+               +               elsif ($day >= $future_dom) {
+               +                       $tag='month-calendar-day-future';
+               +               }
+               +               elsif($params{detail} == 0 && 
+               +                       !defined $cache{$pagespec}{"$year/$mtag/$day"}) {
+               +                       $tag='month-calendar-day-nolink';
+               +               } 
+               +               elsif($params{detail} == 0 && 
+               +                       defined $cache{$pagespec}{"$year/$mtag/$day"}) {
+               +                       $tag='month-calendar-day-link';
+                               }
+                               else {
+               -                       if ($day == $today) {
+               -                               $tag='month-calendar-day-this-day';
+               -                       }
+               -                       elsif ($day == $future_dom) {
+               -                               $tag='month-calendar-day-future';
+               +                       $tag='month-calendar-day';
+               +               }
+               +
+               +               $calendar.=qq{\t\t<td class="$tag $downame{$wday}">};
+               +               my $day_label = qq{<span class="month-calendar-day-label">$day</span>}; 
+               +               if (defined $cache{$pagespec}{"$year/$mtag/$day"}) {
+               +                       my $srcpage; my $destpage;
+               +                       if($params{detail} == 0) {
+               +                               # pull off the first page
+               +                               (($srcpage,$destpage) = each(%{$linkcache{"$year/$mtag/$day"}}));
+               +                               $calendar.=htmllink($params{page}, $params{destpage}, 
+               +                                           pagename($destpage),
+               +                                           "linktext" => "$day_label");
+               +                               push @list, pagename($linkcache{"$year/$mtag/$day"});
+                                       }
+                                       else {
+               -                               $tag='month-calendar-day-nolink';
+               +                               $calendar.=qq{$day_label\n};
+               +                               while(($srcpage,$destpage) = each(%{$linkcache{"$year/$mtag/$day"}})) {
+               +                                       my $title = IkiWiki::basename(pagename($srcpage));
+               +                                       if (exists $pagestate{$srcpage}{meta}{title} ) {
+               +                                               $title = $pagestate{$srcpage}{meta}{title};
+               +                                       }
+               +                                       $calendar.=qq{\t\t<div class="$tag $downame{$wday}">};
+               +                                       $calendar.=htmllink($params{page}, $params{destpage}, 
+               +                                                                                                                       pagename($destpage),
+               +                                                                                                                       "linktext" => $title);
+               +                                       push @list, pagename($linkcache{"$year/$mtag/$day"}{"$srcpage"});
+               +                                       $calendar.=qq{\t\t</div>};
+               +                               }
+                                       }
+               -                       $calendar.=qq{\t\t<td class="$tag $downame{$wday}">$day</td>\n};
+                               }
+               +               else {
+               +                       $calendar.=qq{$day_label\n};
+               +               }
+               +               $calendar.=qq{</td>\n};
+                       }
+                
+                       # finish off the week
+               @@ -304,6 +333,18 @@
+                       return $calendar;
+                } #}}}
+                
+               +sub preprocess_event (@) { #{{{
+               +       my %params=@_;
+               +       # if now time is given, use now
+               +       $params{begin} = localtime($time)            unless defined $params{begin};
+               +
+               +       my $timestamp = str2time($params{begin});
+               +       if ( defined $timestamp) {
+               +               $pagestate{$params{page}}{event}{begin}=$timestamp;
+               +       }
+               +       return "<!-- $params{begin} -->";
+               +} #}}
+               +
+                sub preprocess (@) { #{{{
+                       my %params=@_;
+                       $params{pages} = "*"            unless defined $params{pages};
+               @@ -311,6 +352,8 @@
+                       $params{month} = sprintf("%02d", $params{month}) if defined  $params{month};
+                       $params{week_start_day} = 0     unless defined $params{week_start_day};
+                       $params{months_per_row} = 3     unless defined $params{months_per_row};
+               +       $params{time_src} = 'auto'      unless defined $params{time_src};
+               +       $params{detail} = 0                                   unless defined $params{detail};
+                
+                       if (! defined $params{year} || ! defined $params{month}) {
+                               # Record that the calendar next changes at midnight.
+               @@ -355,19 +398,29 @@
+                       if (! defined $cache{$pagespec}) {
+                               foreach my $p (keys %pagesources) {
+                                       next unless pagespec_match($p, $pagespec);
+               -                       my $mtime = $IkiWiki::pagectime{$p};
+               -                       my $src   = $pagesources{$p};
+               -                       my @date  = localtime($mtime);
+               -                       my $mday  = $date[3];
+               -                       my $month = $date[4] + 1;
+               -                       my $year  = $date[5] + 1900;
+               -                       my $mtag  = sprintf("%02d", $month);
+               -
+               -                       # Only one posting per day is being linked to.
+               -                       $linkcache{"$year/$mtag/$mday"} = "$src";
+               -                       $cache{$pagespec}{"$year"}++;
+               -                       $cache{$pagespec}{"$year/$mtag"}++;
+               -                       $cache{$pagespec}{"$year/$mtag/$mday"}++;
+               +                       my $begin = '';
+               +                       # use time defined by event preprocessor if it's available
+               +                       if (defined $pagestate{$p}{event}{begin}) {
+               +                               $begin = $pagestate{$p}{event}{begin};
+               +                       # fall back on ctime if time_src is set to auto
+               +                       # set time_src to 'event' to skip posts that don't
+               +                       # have the event preprocessor
+               +                       } elsif ($params{time_src} eq 'auto') {
+               +                               $begin = $IkiWiki::pagectime{$p};
+               +                       }
+               +                       if($begin ne '') {
+               +                               my $dest   = $pagesources{$p};
+               +                               my @date  = localtime($begin);
+               +                               my $mday  = $date[3];
+               +                               my $month = $date[4] + 1;
+               +                               my $year  = $date[5] + 1900;
+               +                               my $mtag  = sprintf("%02d", $month);
+               +
+               +                               $linkcache{"$year/$mtag/$mday"}{$p} = "$dest";
+               +                               $cache{$pagespec}{"$year"}++;
+               +                               $cache{$pagespec}{"$year/$mtag"}++;
+               +                               $cache{$pagespec}{"$year/$mtag/$mday"}++;
+               +                       }
+                               }
+                       }
+