The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Daizu-0.3
River stage zero No dependents
1 ++
/ Daizu::Gen::Blog

NAME

Daizu::Gen::Blog - generator for publishing a blog

DESCRIPTION

To publish a blog using Daizu CMS, create a top-level directory for it and set that directory's generator class to this one.

This class is a subclass of Daizu::Gen. The ways in which it differs are described below.

Article URLs

Article URLs are partially date-based. Articles can be stored anywhere inside the blog directory (the one with this generator class), providing their generator isn't overridden. You can use an arbitrary directory structure to organise your articles, but the URL will always be of this format:

    .../YYYY/MM/slug/

where the first two parts are based on the 'published' date of the article. 'slug' is either the base part of its filename (everything but the last file extension) or if it is an '_index' file then the name of its parent directory. Any other directories, which don't directly contain an '_index' file, won't affect URLs at all.

Apart from having slightly different URLs than normal, blog articles are treated like any other articles.

Homepage

The blog directory will generate a homepage listing recent articles. Articles with daizu:fold elements in can be displayed specially, with only the content above the fold shown in the homepage (and date-based archive pages described below), with a 'Read more' link to the full article.

Feeds

XML feeds of the latest articles will be generated, either in Atom or RSS format. See "CONFIGURATION" below for information about how to set these up. There will always be at least one feed generated for each blog.

Archive pages

For each year and month in which at least one article was published (based on the 'published' date) there will be an archive page generated listing those articles.

CONFIGURATION

The configuration file can be used to set up the XML feeds for each blog in various ways. If you don't configure any feeds then you'll get a default one. The default feed will be an Atom 1.0 format one, which will include the content of articles above the 'fold' (or all the content when there is no fold), and will have the URL 'feed.atom' relative to the URL of the blog directory.

The configuration can also change the number of articles shown on the blog homepage. The default is 10.

If you want to change these defaults, for example to add an RSS feed as well as the Atom one, then you'll need to add feed elements to the generator configuration for the blog directory, something like this:

    <generator class="Daizu::Gen::Blog" path="ungwe.org/blog">
     <homepage num-articles="8" />
     <feed format="atom" type="content" />
     <feed format="rss2" type="description" url="qefsblog.rss" />
    </generator>

There can be at most one homepage element, which must have an attribute num-articles containing a number. The minimum value is 1.

Each feed element can have the following attributes:

format

Required. Either atom to generate an Atom 1.0 feed, or rss2 to generate an RSS 2.0 feed. See "FEED FORMATS" in Daizu::Feed for details.

type

The type of content to include with each item in the feed. The default is snippet, which means to include the full content of each article, unless the article contains a 'fold' (a daizu:fold element) in which case only the content above the fold will be included in the feed. A page break (a daizu:page element) will also be counted as a fold if no daizu:fold element is found on the first page. If only part of the article is shown then a link is provided to the URL where the full article can be read.

The alternative types are content which includes the full content of each article regardless of whether it as a fold or page break or not, and description which never includes the full content, but only the description (from the dc:description property) if available. If there is no description, a sample of text from the start of the article will be used instead.

See "FEED TYPES" in Daizu::Feed for details of how this information is encoded in the different feed formats.

url

The URL where the feed will be published, usually a relative path which will be resolved against the URL of the blog directory (homepage).

The default is either feed.atom or feed.rss, depending on the 'format' value.

size

The number of articles which should be included in the feed. The default depends on the 'type' value.

METHODS

Daizu::Gen::Blog->new(%options)

Create a new generator object for a blog. The options are the same as for the Daizu::Gen constructor.

$gen->custom_base_url($file, $base)

See the custom_base_url() method in Daizu::Gen for details. The only differences in behaviour for blogs are that article files (and directories which contain articles called things like _index.html) get special URLs based on the publication date of the article and the 'slug' (file or directory name), based at the URL of the blog directory itself.

Unprocessed files get the same URLs as Daizu::Gen would give them, unless they are inside a directory which 'belongs' to an article. That is, if a directory has a child called _index.html or similar, then all the other non-article files in that directory, including any in subdirectories to any level, will all get URLs which start with the article's URL, followed by their path below the article's directory. So if an article is in a file called blog/foo/_index.html and there is also an image file inside foo then it will get a URL like 2006/05/foo/image.jpg, which means the article can include it with a relative path like image.jpg. These relative URLs will be adjusted as necessary when used in feeds and index pages.

$gen->root_dir_urls_info($file)

Return the URLs generated by $file (a Daizu::File object), which will be the blog directory itself. This overrides the root_dir_urls_info() method in Daizu::Gen, although it also calls that version in case the blog directory is home to a Google sitemap. It adds URLs with the following methods:

homepage

Exactly one of these, with no argument.

feed

One for each configured feed. There is always at least one of these, and there can be as many as you want. The argument will consist of the feed format, the feed type, and the number of entries to include, each separated by a space.

year_archive

URLs like '2006/', with the year number as the argument.

month_archive

URLs like '2006/05/' with the year and month numbers, separated by a space, as the argument. In the argument the month to two digits (with leading zeroes added if necessary) because some of the code relies on the month archive argument values sorting in the right order.

$gen->article_template_variables($file, $url_info)

This method is overridden to provide extra links to be output in the head/meta.tt template. It always returns a head_links value containing a link to the blogs first feed, and for articles it also returns links to the previous and next articles.

$gen->article_template_overrides($file, $url_info)

This method is overridden to adjust the display of article metadata for blogs, since blog articles should display their author and publication time.

$gen->url_updates_for_file_change($wc_id, $guid_id, $file_id, $status, $changes)

See the baseclass documentation for details.

This implementation causes the blog directory to be updated if there are any changes which might mean different URLs are produced for things like archive pages. It also update URLs for articles inside a directory belonging to the file if its generator is changed, which in some circumstances might mean they get a different URL.

$gen->publishing_for_file_change($wc_id, $guid_id, $file_id, $status, $changes)

See the baseclass documentation for details.

This implementation republishes archive pages to include new articles, and the blog homepage and feed if necessary. It also republishes articles which might include a previous/next article link which would be affected by the changes.

$gen->publishing_for_url_change($wc_id, $status, $old_url_info, $new_url_info)

See the baseclass documentation for details.

This implementation causes all the archive pages, the homepage, and all the articles to be republished if there are any URL changes which would affect the navigation menu. This will normally happen at most once per month when a new month (and possibly year) entry needs to appear in the menu.

$gen->homepage($file, $urls)

Generate the output for the homepage, which will be an index page listing recent articles.

$gen->feed($file, $url)

Generate output for a blog feed, in the appropriate format.

$gen->year_archive($file, $urls)

Generate a yearly archive page, listing all files published during a given year.

$gen->year_archive_title($url, $year)

Return a title for a year archive page. Override this to change the kind of titles used. $url is the URL of the archive page for $year, as a URI object.

This default implementation returns something like 'Articles for 2006'.

$gen->year_archive_short_title($url, $year)

Return an abbreviated title for a year archive page. Override this to change the kind of titles used in the navigation menu. $url is the URL of the archive page for $year, as a URI object.

This default implementation returns the value of $year.

$gen->month_archive($file, $urls)

Generate a monthly archive page, listing the articles published during a given year and month.

$gen->month_archive_title($url, $year, $month)

Return a title for a month archive page. Override this to change the kind of titles used. $url is the URL of the archive page for $year, as a URI object.

This default implementation returns something like 'Articles for October 2006', with a non-breaking space between the month name and year.

$gen->month_archive_short_title($url, $year, $month)

Return an abbreviated title for a month archive page. Override this to change the kind of titles used in the navigation menu. $url is the URL of the archive page for $year, as a URI object.

This default implementation returns the full name of the month in English.

$gen->navigation_menu($file, $url)

Returns a navigation menu for the page with the URL info $url, for the file $file. See the subclass method for details of what it does.

This implementation provides a menu of the archive pages, with a link for each year in which an article was published. The most recent years have submenus for months. After a certain number of months the menu just shows years. Each year either has all its months shown (or at least the ones with articles in), or none at all.

COPYRIGHT

This software is copyright 2006 Geoff Richards <geoff@laxan.com>. For licensing information see this page:

http://www.daizucms.org/license/