WWW::AdventCalendar - a calendar for a month of articles (on the web)
version 1.113
This is a library for producing Advent calendar websites. In other words, it makes four things:
a page saying "first door opens in X days" the calendar starts
a calendar page on and after the calendar starts
a page for each day in the month with an article
an Atom feed
This library was originally written just for RJBS's Perl Advent Calendar, so it assumed you'd always be publishing from Dec 1 to Dec 24 or so. It has recently been retooled to work across arbitrary ranges, as long as they're within one month. This feature isn't well tested. Neither is the rest of the code, to be perfectly honest, though...
To build an Advent calendar:
create an advent.ini configuration file
write articles and put them in a directory
schedule advcal to run nightly
advent.ini is easy to produce. Here's the one used for the original RJBS Advent Calendar:
title = RJBS Advent Calendar year = 2009 uri = http://advent.rjbs.manxome.org/ editor = Ricardo Signes category = Perl category = RJBS article_dir = rjbs/articles share_dir = share
These should all be self-explanatory. Only category can be provided more than once, and is used for the category listing in the Atom feed.
category
These settings all correspond to "ATTRIBUTES" in calendar attributes described below. A few settings below are not given above.
Articles are easy, too. They're just files in the article_dir. They begin with an email-like set of headers, followed by a body written in Pod. For example, here's the beginning of the first article in the original calendar:
article_dir
Title: Built in Our Workshop, Delivered in Your Package Topic: Sub::Exporter =head1 Exporting In Perl, we organize our subroutines (and other stuff) into namespaces called packages. This makes it easy to avoid having to think of unique names for
The two headers seen above, title and topic, are the only headers required, and correspond to those attributes in the WWW::AdventCalendar::Article object created from the article file.
Finally, running advcal is easy, too. Here is its usage:
advcal [-aot] [long options...] -c --config the ini file to read for configuration -a --article-dir the root of articles --share-dir the root of shared files -o --output-dir output directory --today the day we treat as "today"; default to today -y --year-links place year links at the bottom of the page
Options given on the command line override those loaded form configuration. By running this program every day, we cause the calendar to be rebuilt, adding any new articles that have become available.
This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.)
Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.
$calendar->build;
This method does all the work: it reads in the articles, decides how many to show, writes out the rendered pages, the index, and the atom feed.
my $article = $calendar->read_articles;
This method reads in all the articles for the calendar and returns a hashref. The keys are dates (in the format YYYY-MM-DD) and the values are WWW::AdventCalendar::Article objects.
YYYY-MM-DD
The title of the calendar, to be used in headers, the feed, and so on.
A tagline for the calendar, used in some templates. Optional.
The base URI of the calendar, including trailing slash.
The name of the calendar's editor, used in the feed.
The name of the calendar's default author, used for articles that provide none.
The calendar year. Optional, if you provide start_date and end_date.
start_date
end_date
The start of the article-containing period. Defaults to Dec 1 of the year.
The end of the article-containing period. Defaults to Dec 24 of the year.
An arrayref of category names for use in the feed.
The directory in which articles can be found, with names like YYYY-MM-DD.html.
The directory for templates, stylesheets, and other static content.
The directory into which output files will be written.
The date to treat as "today" when deciding how much of the calendar to publish.
Ricardo SIGNES <cpan@semiotic.systems>
Len Jaffe <lenjaffe@jaffesystems.com>
Ricardo Signes <rjbs@semiotic.systems>
Shoichi Kaji <skaji@cpan.org>
This software is copyright (c) 2022 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install WWW::AdventCalendar, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::AdventCalendar
CPAN shell
perl -MCPAN -e shell install WWW::AdventCalendar
For more information on module installation, please visit the detailed CPAN module installation guide.