/ 
Daizu-0.1
River stage zero No dependents
/ 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.

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">
 <feed format="atom" type="content" />
 <feed format="rss2" type="description" url="qefsblog.rss" />
</generator>

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 information to the template blog/head_meta.tt so that it can correctly provide a link element pointing to the first blog feed.

$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. It also provides a rewrite which adds a feed auto-subscription link to the heading of the page.

$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->month_archive($file, $urls)

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

$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/