NAME

Daizu::Feed - class for creating Atom and RSS feeds

DESCRIPTION

A class for creating feeds in Atom and RSS formats. Currently it is only possible to use this for feeds where the entries are Daizu articles.

To use this, first create an object, indicating what kind of feed you want, and then call the add_entry() method for each article you want to include. Then you can call the xml() method to get the output.

FEED FORMATS

The format of a feed determines how the information is encoded, but should not affect what information is provided. The currently supported feed formats are:

atom

Atom 1.0, as described in RFC 4287.

This format is used for the default blog configuration because of its technical advantages over RSS.

Specification: http://atompub.org/rfc4287.html

rss2

RSS 2.0. Provided for compatability with older feed consuming software.

Specification: http://www.rssboard.org/rss-specification

FEED TYPES

The type of feed determines what information is provided for each article. This is more a matter of editorial policy than the choice of feed format.

The description for an article (from the dc:description property) is always included in the feed if present. In Atom feeds it will be provided in an atom:summary element, which will only appear if the article has a description. In RSS feeds the description element will have this value, but if there is no description then it will still appear (since some consumers may rely on it being present), and will instead carry a short extract of the text from the start of the article.

Note that in RSS feeds the actual content of articles, if it's included, is put in a content:encoded element, which the feed validator recommends against (http://feedvalidator.org/docs/warning/DuplicateDescriptionSemantics.html). There's no right answer for this, and I might change my mind about it in the future, but for now I'm copying what Wordpress (http://wordpress.org/) does.

The actual content of an article may appear, depending on the type of feed you ask for. The options are:

description

No extra information about the article is provided, beyond the title, description (as described above), a link to the article's URL, and the its publication and update times.

For Atom feeds: the atom:content element is omitted.

For RSS feeds: the content:encoded element is omitted.

snippet

If the article's content contains a 'fold' (indicated with a daizu:fold element) or a page break, then only the content before the fold or first page break is included in the feed. If there is any more content in the full article then a text link to the article's URL is included after the extract to make it more obvious that only part of the article is shown. If there is no fold or page break then the full article is included in the feed, as for the content type feeds described below.

For Atom feeds: the extract of the article content is provided as raw XHTML in an atom:content element.

For RSS feeds: the extract of the article content is provided in a content:encoded element. The description element will still carry the description or extract as described above.

content

The full content of the article is included in the feed, even if the article has page breaks. Any daizu:fold elements or daizu:page elements in the article's content will be ignored (and will not appear in the feed).

For Atom feeds: the article content is provided as raw XHTML in an atom:content element.

For RSS feeds: the article content is provided in a content:encoded element. The description element will still carry the description or extract as described above.

METHODS

Daizu::Feed->new($cms, $file, $url, $format, $type)

Return a new Daizu::Feed object and set up the basic outline of the XML feed. $file should be a Daizu::File object representing the 'homepage' of this feed. $url should be a string containing the URL of the feed file itself once it has been output. $format should be either 'atom' (for Atom 1.0 feeds) or 'rss2' (for RSS 2.0 feeds). $type can be one of the feed types mentioned above ('description', 'snippet', or 'content').

$feed->xml()

Returns the XML::LibXML::Document object for the feed, which you can use to write it out to a file. Call this after you've addded all the entries.

Before the XML is returned, the feed's 'updated' timestamp is set to the update time of the most recently updated article, or the current time (if there are no articles or if the most recently updated one was updated in the future). Because of this, if you add any more articles after calling this function, you should call it again to get an updated version of the feed XML.

$feed->add_entry($file)

Add an entry to the feed, for $file, which should be a Daizu::File object. The file must be an article, and must have a title.

It is the responsibility of the caller to ensure that the file has been published under it's expected URL, otherwise the feed will include a broken link.

COPYRIGHT

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

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