diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/patchqueue/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn | 636 |
1 files changed, 635 insertions, 1 deletions
diff --git a/doc/patchqueue/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn b/doc/patchqueue/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn index 7074ef6de..0abe2c901 100644 --- a/doc/patchqueue/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn +++ b/doc/patchqueue/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn @@ -19,4 +19,638 @@ The year and month entities in the out put have links to archive index pages, wh I'll send in the patch via email. -ManojSrivastava
\ No newline at end of file +ManojSrivastava + +------ + +Since this is a little bit er, stalled, I'll post here the stuff Manoj +mailed me, and my response to it. --[[Joey]] + +<pre> +#! /usr/bin/perl +# -*- Mode: Cperl -*- +# calendar.pm --- +# Author : Manoj Srivastava ( srivasta@glaurung.internal.golden-gryphon.com ) +# Created On : Fri Dec 8 16:05:48 2006 +# Created On Node : glaurung.internal.golden-gryphon.com +# Last Modified By : Manoj Srivastava +# Last Modified On : Sun Dec 10 01:53:22 2006 +# Last Machine Used: glaurung.internal.golden-gryphon.com +# Update Count : 139 +# Status : Unknown, Use with caution! +# HISTORY : +# Description : +# +# arch-tag: 2aa737c7-3d62-4918-aaeb-fd85b4b1384c +# +# Copyright (c) 2006 Manoj Srivastava <srivasta@debian.org> +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +# + +require 5.002; +package IkiWiki::Plugin::calendar; + +use warnings; +use strict; +use IkiWiki '1.00'; +use Time::Local; + +our $VERSION = "0.1"; +my $file = __FILE__; + +my %calpages; +my %cache; +my %linkcache; + +my $index=1; +my @now=localtime(); + +=head1 NAME + +calendar - Add links for the current month's, current year's, and older archived postings + +=cut + +=head1 SYNOPSIS + +To invoke the calendar, just use the preprocessor directive (options +and variations are detailed below): + + [[calendar ]] + +or + + [[calendar type="month" pages="blog/* and !*/Discussion"]] + +or + + [[calendar type="year" year="2005" pages="blog/* and !*/Discussion"]] + +=cut + + +=head1 DESCRIPTION + +This plugin is inspired by the calendar plugin for Blosxom, but +derives no code from it. This plugin is essentially a fancy front end +to archives of previous pages, usually used for blogs. It can produce +a calendar for a given month, or a list of months for a given year. + +The year and month entities in the out put have links to archive index +pages, which are supposed to exist already. The idea is to create an +archives hierarchy, rooted in the subdirectory specified in the +site wide customization variable, I<archivebase>. I<archivebase> +defaults to C<archives>. Links are created to pages +C<$archivebase/$year> and C<$archivebase/$year/$month>. If one creates +annual and monthly indices, for example, by using something like this +sample from my I<archives/2006/01.mdwn> (warning: line split for +readability): + + [[meta title="Archives for 2006/01"]] + [[inline rootpage="blog" atom="no" rss="no" show="0" + pages="blog/* and !*/Discussion and creation_year(2006) + and creation_month(01)" + ]] + +=cut + +=head1 OPTIONS + +=over + +=item B<type> + +Used to specify the type of calendar wanted. Can be one of C<month> or +C<year>. The default is a month view calendar. + +=item B<pages> + +Specifies the C<pagespec> used to get pages to match for +linking. Usually this should be something like C<blog/* and !*/Discussion>. +Defaults to C<*>. + +=item B<year> + +The year for which the calendar is requested. Defaults to the current year. + +=item B<month> + +The numeric month for which the calendar is requested, in the range +1..12. Used only for the month view calendar, and defaults to the +current month. + +=item B<week_start_day> + +A number, in the range 0..6, which represents the day of the week that +the month calendar starts with. 0 is Sunday, 1 is Monday, and so +on. Defaults to 0, which is Sunday. + +=item B<months_per_row> + +In the annual calendar, number of months to place in each row. Defaults to 3. + +=back + +=cut + +=head1 Classes for CSS control + +The output is liberally sprinkled with classes, for fine grained CSS +customization. + +=over + +=item C<month-calendar> + +The month calendar as a whole + +=item C<month-calendar-head> + +The head of the month calendar (ie,"March"), localized to the environment. + +=item C<month-calendar-day-head> + +A column head in the month calendar (ie, a day-of-week abbreviation), +localized. + +=item C<month-calendar-day-noday>, C<month-calendar-day-link>, + C<month-calendar-day-nolink>, C<month-calendar-day-future>, + C<month-calendar-day-this-day> + +The day squares on the month calendar, for days that don't exist +(before or after the month itself), that don't have stories, that do +have stories, that are in the future, or are that currently selected, +respectively (today). + +=item Day-of-week-name + +Each day square is also given a class matching its day of week, this +can be used to high light weekends. This is also localized. + +=item C<year-calendar> + +The year calendar as a whole + +=item C<year-calendar-head> + +The head of the year calendar (ie, "2006") + +=item C<year-calendar-subhead> + +For example, "Months" + +=item C<year-calendar-month-link>, C<year-calendar-month-nolink>, + C<year-calendar-month-future>, C<year-calendar-this-month> + +The month squares on the year calendar, for months with stories, +without, in the future, and currently selected, respectively. + +=back + +=cut + + +sub import { + hook(type => "preprocess", id => "calendar", call => \&preprocess); + hook(type => "format", id => "calendar", call => \&format); +} + +sub preprocess (@) { + my %params=@_; + $params{pages} = "*" unless defined $params{pages}; + $params{type} = "month" unless defined $params{type}; + $params{year} = 1900 + $now[5] unless defined $params{year}; + $params{month} = sprintf("%02d", $params{month}) if defined $params{month}; + $params{month} = 1 + $now[4] unless 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}; + + # Store parameters (could be multiple calls per page) + $calpages{$params{destpage}}{$index} = \%params; + + return "\n<div class=\"calendar\">" . $index++ . "</div><!-- calendar -->\n"; +} + +sub is_leap_year (@) { + my %params=@_; + return ($params{year} % 4 == 0 && (($params{year} % 100 != 0) || $params{year} % 400 ==0)) ; +} + + +sub month_days { + my %params=@_; + my $days_in_month = (31,28,31,30,31,30,31,31,30,31,30,31)[$params{month}-1]; + if ($params{month} == 2 && is_leap_year(%params)) { + $days_in_month++; + } + return $days_in_month; +} + + +sub format_month (@) { + my %params=@_; + my $pagespec = $params{pages}; + my $year = $params{year}; + my $month = $params{month}; + + my $calendar="\n"; + + # When did this month start? + my @monthstart = localtime(timelocal(0,0,0,1,$month-1,$year-1900)); + + my $future_dom = 0; + my $today = 0; + $future_dom = $now[3]+1 if ($year == $now[5]+1900 && $month == $now[4]+1); + $today = $now[3] if ($year == $now[5]+1900 && $month == $now[4]+1); + + # Calculate month names for next month, and previous months + my $pmonth = $month - 1; + my $nmonth = $month + 1; + my $pyear = $year; + my $nyear = $year; + + # Adjust for January and December + if ($month == 1) { $pmonth = 12; $pyear--; } + if ($month == 12) { $nmonth = 1; $nyear++; } + + # Find out month names for this, next, and previous months + my $monthname=POSIX::strftime("%B", @monthstart); + my $pmonthname= + POSIX::strftime("%B", localtime(timelocal(0,0,0,1,$pmonth-1,$pyear-1900))); + my $nmonthname= + POSIX::strftime("%B", localtime(timelocal(0,0,0,1,$nmonth-1,$nyear-1900))); + + # Calculate URL's for monthly archives, and article counts + my $archivebase = 'archives'; + $archivebase = $config{archivebase} if defined $config{archivebase}; + + my ($url, $purl, $nurl)=("$monthname",'',''); + my ($count, $pcount, $ncount) = (0,0,0); + + if (exists $cache{$pagespec}{"$year/$month"}) { + $url = htmllink($params{page}, $params{destpage}, + "$archivebase/$year/" . sprintf("%02d", $month), + 0,0," $monthname "); + } + + if (exists $cache{$pagespec}{"$pyear/$pmonth"}) { + $purl = htmllink($params{page}, $params{destpage}, + "$archivebase/$pyear/" . sprintf("%02d", $pmonth), + 0,0," $pmonthname "); + } + if (exists $cache{$pagespec}{"$nyear/$nmonth"}) { + $nurl = htmllink($params{page}, $params{destpage}, + "$archivebase/$nyear/" . sprintf("%02d", $nmonth), + 0,0," $nmonthname "); + } + + # Start producing the month calendar + $calendar=<<EOF; +<table class="month-calendar"> + <caption class="month-calendar-head"> + $purl + $url + $nurl + </caption> + <tr> +EOF + # Suppose we want to start the week with day $week_start_day + # If $monthstart[6] == 1 + my $week_start_day = $params{week_start_day}; + + my $start_day = 1 + (7 - $monthstart[6] + $week_start_day) % 7; + my %downame; + my %dowabbr; + for my $dow ($week_start_day..$week_start_day+6) { + my @day=localtime(timelocal(0,0,0,$start_day++,$month-1,$year-1900)); + my $downame = POSIX::strftime("%A", @day); + my $dowabbr = POSIX::strftime("%a", @day); + $downame{$dow % 7}=$downame; + $dowabbr{$dow % 7}=$dowabbr; + $calendar.= + qq{ <th class="month-calendar-day-head $downame">$dowabbr</th>\n}; + } + + $calendar.=<<EOF; + </tr> +EOF + + my $wday; + # we start with a week_start_day, and skip until we get to the first + for ($wday=$week_start_day; $wday != $monthstart[6]; $wday++, $wday %= 7) { + $calendar.=qq{ <tr>\n} if $wday == $week_start_day; + $calendar.= + qq{ <td class="month-calendar-day-noday $downame{$wday}"> </td>\n}; + } + + # At this point, either the first is a week_start_day, in which case nothing + # has been printed, or else we are in the middle of a row. + for (my $day = 1; $day <= month_days(year => $year, month => $month); + $day++, $wday++, $wday %= 7) { + # At tihs point, on a week_start_day, we close out a row, and start a new + # one -- unless it is week_start_day on the first, where we do not close a + # row -- since none was started. + if ($wday == $week_start_day) { + $calendar.=qq{ </tr>\n} unless $day == 1; + $calendar.=qq{ <tr>\n}; + } + my $tag; + my $mtag = sprintf("%02d", $month); + if (defined $cache{$pagespec}{"$year/$mtag/$day"}) { + if ($day == $today) { $tag='month-calendar-day-this-day'; } + else { $tag='month-calendar-day-link'; } + $calendar.=qq{ <td class="$tag $downame{$wday}">}; + $calendar.= + htmllink($params{page}, $params{destpage}, + pagename($linkcache{"$year/$mtag/$day"}), + 0,0,"$day"); + $calendar.=qq{</td>\n}; + } + else { + if ($day == $today) { $tag='month-calendar-day-this-day'; } + elsif ($day == $future_dom) { $tag='month-calendar-day-future'; } + else { $tag='month-calendar-day-nolink'; } + $calendar.=qq{ <td class="$tag $downame{$wday}">$day</td>\n}; + } + } + # finish off the week + for (; $wday != $week_start_day; $wday++, $wday %= 7) { + $calendar.=qq{ <td class="month-calendar-day-noday $downame{$wday}"> </td>\n}; + } + $calendar.=<<EOF; + </tr> +</table> +EOF + + return $calendar; +} + +sub format_year (@) { + my %params=@_; + my $pagespec = $params{pages}; + my $year = $params{year}; + my $month = $params{month}; + my $calendar="\n"; + my $pyear = $year - 1; + my $nyear = $year + 1; + my $future_month = 0; + $future_month = $now[4]+1 if ($year == $now[5]+1900); + + # calculate URL's for previous and next years + my $archivebase = 'archives'; + $archivebase = $config{archivebase} if defined $config{archivebase}; + my ($url, $purl, $nurl)=("$year",'',''); + if (exists $cache{$pagespec}{"$year"}) { + $url = htmllink($params{page}, $params{destpage}, + "$archivebase/$year", + 0,0,"$year"); + } + + if (exists $cache{$pagespec}{"$pyear"}) { + $purl = htmllink($params{page}, $params{destpage}, + "$archivebase/$pyear", + 0,0,"\←"); + } + if (exists $cache{$pagespec}{"$nyear"}) { + $nurl = htmllink($params{page}, $params{destpage}, + "$archivebase/$nyear", + 0,0,"\→"); + } + # Start producing the year calendar + $calendar=<<EOF; +<table class="year-calendar"> + <caption class="year-calendar-head"> + $purl + $url + $nurl + </caption> + <tr> + <th class="year-calendar-subhead" colspan="$params{months_per_row}">Months</th> + </tr> +EOF + + for ($month = 1; $month <= 12; $month++) { + my @day=localtime(timelocal(0,0,0,15,$month-1,$year-1900)); + my $murl; + my $monthname = POSIX::strftime("%B", @day); + my $monthabbr = POSIX::strftime("%b", @day); + $calendar.=qq{ <tr>\n} if ($month % $params{months_per_row} == 1); + my $tag; + my $mtag=sprintf("%02d", $month); + if ($month == $params{month}) { + if ($cache{$pagespec}{"$year/$mtag"}) {$tag = 'this_month_link'} + else {$tag = 'this_month_nolink'} + } + elsif ($cache{$pagespec}{"$year/$mtag"}) {$tag = 'month_link'} + elsif ($future_month && $month >=$future_month){$tag = 'month_future'} + else {$tag = 'month_nolink'} + if ($cache{$pagespec}{"$year/$mtag"}) { + $murl = htmllink($params{page}, $params{destpage}, + "$archivebase/$year/$mtag", + 0,0,"$monthabbr"); + $calendar.=qq{ <td class="$tag">}; + $calendar.=$murl; + $calendar.=qq{</td>\n}; + } + else { + $calendar.=qq{ <td class="$tag">$monthabbr</td>\n}; + } + $calendar.=qq{ </tr>\n} if ($month % $params{months_per_row} == 0); + } + $calendar.=<<EOF; +</table> +EOF + + return $calendar; +} + + +sub format (@) { + my %params=@_; + my $content=$params{content}; + return $content unless exists $calpages{$params{page}}; + + # Restore parameters for each invocation + foreach my $index (keys %{$calpages{$params{page}}}) { + my $calendar="\n"; + my %saved = %{$calpages{$params{page}}{$index}}; + my $pagespec=$saved{pages}; + + if (! defined $cache{$pagespec}) { + for my $page (sort keys %pagesources) { + next unless pagespec_match($page,$pagespec); + my $mtime; + my $src = $pagesources{$page}; + if (! exists $IkiWiki::pagectime{$page}) { + $mtime=(stat(srcfile($src)))[9]; + } + else { + $mtime=$IkiWiki::pagectime{$page} + } + my @date = localtime($mtime); + my $mday = $date[3]; + my $month = $date[4] + 1; + my $year = $date[5] + 1900; + my $mtag = sprintf("%02d", $month); + $linkcache{"$year/$mtag/$mday"} = "$src"; + $cache{$pagespec}{"$year"}++; + $cache{$pagespec}{"$year/$mtag"}++; + $cache{$pagespec}{"$year/$mtag/$mday"}++; + } + } + # So, we have cached data for the current pagespec at this point + if ($saved{type} =~ /month/i) { + $calendar=format_month(%saved); + } + elsif ($saved{type} =~ /year/i) { + $calendar=format_year(%saved); + } + $content =~ s/(<div class=\"calendar\">\s*.?\s*$index\b)/<div class=\"calendar\">$calendar/ms; + } + return $content; +} + + + +=head1 CAVEATS + +In the month calendar, for days in which there is more than one +posting, the link created randomly selects one of them. Since there is +no easy way in B<IkiWiki> to automatically generate index pages, and +pregenerating daily index pages seems too much of an overhead, we have +to live with this. All postings can still be viewed in the monthly or +annual indices, of course. This can be an issue for very prolific +scriveners. + +=cut + +=head1 BUGS + +None Known so far. + +=head1 BUGS + +Since B<IkiWiki> eval's the configuration file, the values have to all +on a single physical line. This is the reason we need to use strings +and eval, instead of just passing in real anonymous sub references, +since the eval pass converts the coderef into a string of the form +"(CODE 12de345657)" which can't be dereferenced. + +=cut + +=head1 AUTHOR + +Manoj Srivastava <srivasta@debian.org> + +=head1 COPYRIGHT AND LICENSE + +This script is a part of the Devotee package, and is + +Copyright (c) 2002 Manoj Srivastava <srivasta@debian.org> + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +=cut + +1; + +__END__ +</pre> + +------ + +I've been looking over the calendar plugin. Some items: + +* Why did you need to use a two-stage generation with a format hook? + That approach should only be needed if adding something to a page that + would be removed by the htmlscrubber, and as far as I can tell, the + calendars don't involve anything that would be a problem. It seems + that emitting the whole calendar in the preprocess hook would simplify + things and you'd not need to save state about calendars. + +> A) I am scared of the html scrubber, and have never turned it on, +> and did not look too deeply into what would be scrubbed out --ManojSrivastava +>> Unless you're using javascript, a few annoyances link <blink>, or inline +>> css, it's unlikly to object to any html you might write. The list of +>> allowed tags and attributes is easy to find near the top of the plugin. + +> B) In case the option that gets the ctime of the pages from the +> SCM itself, %IkiWiki::pagectime is not populated that early, +> is it? So I waited until the last possible moment to look at +> the time information. +> +>> Actually, since my big rewrite of the rendering path a few months ago, +>> ikiwiki scans and populates almost all page information before starting +>> to render any page. This includes %pagectime, and even %links. So you +>> shouldn't need to worry about running it late. + +* The way that it defaults to the current year and current month + is a little bit tricky, because of course the wiki might not get + updated in a particular time period, and even if it is updated, only + iff a page containing a calendar is rebuilt for some other reason will + the calendar get updated, and change what year or month it shows. This + is essentially the same problem described in + [[todo/tagging_with_a_publication_date]], + although I don't think it will affect the calendar plugin very badly. + Still, the docs probably need to be clear about this. + +> I use it on the sidebar; and the blog pages are almost always +> rebuilt, which is where the calendar is looked at most often. Oh, +> and I also cheat, I have ikiwiki --setup foo as a @daily cronjob, so +> my wiki is always built daily from scratch. +> +> I think it should be mentioned, yes. + +* There seems to be something a bit wrong with the year-to-year + navigation in the calendar, based on the example in your blog. If I'm + on the page for 2006, there's an arrow pointing left which takes me to + 2005. If I'm on 2005, the arrow points left, but goes to 2006, not + 2004. + +> I need to look into this. + +* AIUI, the archivebase setting makes a directory rooted at the top of + the wiki, so you can have only one set of archives per wiki, in + /archives/. It would be good if it were possible to have multiple + archived for different blogs in the same wiki at multiple locations. + Though since the archives contain calendars, the archive location + can't just be relative to the page with the calendar. But perhaps + archivebase could be a configurable parameter that can be specified in + the directive for the calendar? (It would be fine to keep the global + location as a default.) + +> OK, this is simple enough to implement. I'll do that (well, +> perhaps not before Xmas, I have a family dinner to cook) and send in +> another patch. + + +---- + +And that's all I've heard so far. Hoping I didn't miss another patch? + +--[[Joey]] |