doc/todo/calendar_--_archive_browsing_via_a_calendar_frontend.mdwn

   1 I am serving notice that I am starting work on a calendar plugin inspired by Blosxom's calendar plugin. The current plan is to create a plugin that looks through all the source files matching a certain pagespec, and optionally spit out a month view for the specified month (default to current), or spit out a year view for a given year (defaulting to the current year), of a list  of year with posts in them. The output would be a table, with the same CSS directives that the Blosxom plugin used to use (so that I can just reuse my css file).  The links would be created to a $config{archivedir}/$year or $config{archivedir}/$year-$month file, which can just have
   2
   3      \[[!inline pages="blog/* and !*/Discussion and creation_year($year) and creation_month($month)" rss="no" atom="no" show="0"]]
   4
   5 or some thing to generate a archive of postings.
   6
   7 Roland Mas suggested a separate cron job to generate these archive indices automatically, but that is another thread.
   8
   9 ManojSrivastava
  10
  11 This plugin is inspired by the calendar plugin for Blosxom, but derivesno 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. To invoke the calendar, just use the preprocessor directive:
  12
  13      \[[!calendar ]]
  14
  15 or
  16
  17       \[[!calendar type="month" pages="blog/* and !*/Discussion"]]
  18
  19 or
  20
  21        \[[!calendar type="year"  year="2005" pages="blog/* and !*/Discussion"]]
  22
  23
  24 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, archivebase. archivebase defaults to "archives".  Links are created to pages "$archivebase/$year" and "$archivebase/$year/$month". The idea is to create annual and monthly indices, for example, by using something like this sample from my archives/2006/01.mdwn
  25
  26           \[[!meta title="Archives for 2006/01"]]
  27           \[[!inline rootpage="blog" atom="no" rss="no" show="0" pages="blog/* and !*/Discussion and creation_year(2006) and creation_month(01)" ]]
  28
  29 I'll send in the patch via email.
  30
  31 ManojSrivastava
  32
  33 ------
  34
  35 Since this is a little bit er, stalled, I'll post here the stuff Manoj
  36 mailed me, and my response to it. --[[Joey]]
  37
  38 > > I'm sending in an updated package, and have removed the older version you had here.--ManojSrivastava
  39
  40
  41 [[!tag patch]]
  42
  43 ----
  44
  45 've been looking over the calendar plugin. Some items:
  46
  47 * Why did you need to use a two-stage generation with a format hook?
  48   That approach should only be needed if adding something to a page that
  49   would be removed by the htmlscrubber, and as far as I can tell, the
  50   calendars don't involve anything that would be a problem. It seems
  51   that emitting the whole calendar in the preprocess hook would simplify
  52   things and you'd not need to save state about calendars.
  53
  54 > I am scared of the html scrubber, and have never turned it on,
  55 >        and did not look too deeply into what would be scrubbed out --ManojSrivastava
  56 >> Unless you're using javascript, a few annoyances link <blink>, or inline
  57 >> css, it's unlikly to object to any html you might write. The list of
  58 >> allowed tags and attributes is easy to find near the top of the plugin.
  59
  60 > In case the option that gets the ctime of the pages from the
  61 > SCM itself, %IkiWiki::pagectime  is not populated that early,
  62 > is it? So I waited until the last possible moment to look at
  63 > the time information.
  64 >
  65 >> Actually, since my big rewrite of the rendering path a few months ago,
  66 >> ikiwiki scans and populates almost all page information before starting
  67 >> to render any page. This includes %pagectime, and even %links. So you
  68 >> shouldn't need to worry about running it late.
  69
  70 * The way that it defaults to the current year and current month
  71   is a little bit tricky, because of course the wiki might not get
  72   updated in a particular time period, and even if it is updated, only
  73   iff a page containing a calendar is rebuilt for some other reason will
  74   the calendar get updated, and change what year or month it shows. This
  75   is essentially the same problem described in
  76   [[todo/tagging_with_a_publication_date]],
  77   although I don't think it will affect the calendar plugin very badly.
  78   Still, the docs probably need to be clear about this.
  79
  80 > I use it on the sidebar; and the blog pages are almost always
  81 > rebuilt, which is where the calendar is  looked at most often. Oh,
  82 > and I also cheat, I have ikiwiki  --setup foo as a @daily cronjob, so
  83 > my wiki is always built daily from scratch.
  84 >
  85 > I think it should be mentioned, yes.
  86
  87 * There seems to be something a bit wrong with the year-to-year
  88   navigation in the calendar, based on the example in your blog. If I'm
  89   on the page for 2006, there's an arrow pointing left which takes me to
  90   2005. If I'm on 2005, the arrow points left, but goes to 2006, not
  91   2004.
  92
  93 > I need to look into this.
  94
  95 * AIUI, the archivebase setting makes a directory rooted at the top of
  96   the wiki, so you can have only one set of archives per wiki, in
  97   /archives/. It would be good if it were possible to have multiple
  98   archived for different blogs in the same wiki at multiple locations.
  99   Though since the archives contain calendars, the archive location
 100   can't just be relative to the page with the calendar. But perhaps
 101   archivebase could be a configurable parameter that can be specified in
 102   the directive for the calendar? (It would be fine to keep the global
 103   location as a default.)
 104
 105 > OK, this is simple enough to implement. I'll do that (well,
 106 > perhaps not before Xmas, I have a family dinner to cook) and send in
 107 > another patch.
 108
 109
 110 ----
 111 And that's all I've heard so far. Hoping I didn't miss another patch?
 112
 113 --[[Joey]]
 114
 115 >No, you did not.  But I am back to hacking on this, and I think I have discovered a major problem with my approach. One of the problems with the current plugin is that the goal of a calendar is to create a calendar, either a month >or year based on,  that provides links to blogs for all the days in (for the month calendar), and all the months (in a year calendar) in which there have been blog postings. For the monthly calendar, it needs to know the  previous >and next months where there is a posting, and  for the year calendar, it needs to know  which of the previous (next) years had entries.
 116
 117 >Now, this means that it needs to know about at _all_ pages that meet the pagespec, and stash that information, before it begins generating the calandar in question, in order to calculate how to create the symlinks. And, of >course, all pages that have calendars on them might need to change anytime a page that meets the pagespec is added; and again at midnight, when the current day changes.
 118
 119 >> I think I have solved the ""Need to look at all pages that match the spec"" issue; but the nightly rebuild to handle the current day changing still remain. I use cron. It is now, however, richly documented :)
 120
 121
 122 --ManojSrivastava
 123
 124 > Finally reviewed and applied this. [[done]]! --[[Joey]]