view release on metacpan or  search on metacpan

lib/Daizu/Feed.pm  view on Meta::CPAN

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

Specification: L<http://atompub.org/rfc4287.html>

=item rss2

S<RSS 2.0>.  Provided for compatability with older feed consuming software.

Specification: L<http://www.rssboard.org/rss-specification>

=back

=head1 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 C<dc:description> property)
is always included in the feed if present.  In Atom feeds it will be
provided in an C<atom:summary> element, which will only appear if the
article has a description.  In RSS feeds the C<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 C<content:encoded> element, which the
feed validator recommends against
(L<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 (L<http://wordpress.org/>) does.

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

=over

=item 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 C<atom:content> element is omitted.

For RSS feeds: the C<content:encoded> element is omitted.

=item snippet

If the article's content contains a 'fold' (indicated with a C<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 C<content> type feeds described below.

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

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

=item content

The full content of the article is included in the feed, even if the article
has page breaks.  Any C<daizu:fold> elements or C<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
C<atom:content> element.

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

=back

=head1 METHODS

=over

=item Daizu::Feed-E<gt>new($cms, $file, $url, $format, $type)

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

=cut

sub new
{
    my ($class, $cms, $file, $url, $format, $type) = @_;
    croak "unknown feed format '$format'"
        unless $format eq 'atom' || $format eq 'rss2';
    croak "unknown feed type '$type'"
        unless $type eq 'content' || $type eq 'snippet' ||
               $type eq 'description';

    my $feed_title = $file->title;
    croak "no title available for feed, or any of its ancestors"
        unless defined $feed_title;

    my $homepage_url = $file->generator->base_url($file);
    croak "blog homepage doesn't seem to have a URL"
        unless defined $homepage_url;

    my $doc = XML::LibXML::Document->new('1.0', 'UTF-8');
    my $feed;
    my $entry_parent;
    my $updated_elem;
    if ($format eq 'atom') {    # Atom 1.0
        $feed = $doc->createElementNS($ATOM_NS, 'feed');
        $entry_parent = $feed;

        add_xml_elem($feed, title => $feed_title);
        # TODO - description should be decoded from utf-8 at some point
        add_xml_elem($feed, subtitle => $file->{description})
            if defined $file->{description};
        add_xml_elem($feed, id => $file->guid_uri);
        add_xml_elem($feed, generator => 'Daizu CMS',
            uri => 'http://www.daizucms.org/',
            version => $Daizu::VERSION,
        );
        add_xml_elem($feed, link => undef,
            rel => 'self',