Adding a feed to your application

Now that you have written a nice application with Dancer, you want to add a RSS feed to publish your articles. For this task, you can use the plugin Dancer::Plugin::Feed.

The goal of this module is to provide an easy way to generate a feed in Atom or RSS. For this tutorial, we will see how we use it in the Advent Calendar application.

Adding a simple feed

In the advent calendar application, each article is stored in a POD file stored on disk. Each day, a new article will be visible, and should be added to the feed. We will see how to do that.

First, we load the plugin in the application.

use Dancer;
use Dancer::Plugin::Feed;

Now we need a function that will, for each day, return the list of articles, with, for each articles, if it should be visible:

sub _articles {
    my $year = shift;
    my @days = qw/1..24/;
    my @articles;

    foreach my $day (@days) {
        if (_article_is_visible($year, $day) {
            push @articles, _article( $year, $day );
        }
    }
    @articles = sort { $a->{day} <=> $b->{day} } @articles;
    return \@articles;
}

sub _article_is_visible {
    # decide if this article should be visible at this date
}

And of course, we need to build each article from POD, set the date of the publication, the title, the permalink, etc.

sub _article {
     my ( $year, $day ) = @_;
     ...
     # skip if not visible
     return {
         title   => $title,
         content => $content,
         link    => $permalink,
         issued  => DateTime->new( year => $year, month => 12, day => $day ),
     };
 }

And to finish, our route to return the content of the RSS feed. This route gets the year as an argument, and returns the list of articles for this year:

get '/feed/:year/rss' => sub {
    my $articles = _articles( params->{year} );
    create_feed(
        format  => 'RSS',
        entries => $articles,
        title   => 'my awesome RSS feed',
    );
};

That's it. The important part here is the create_feed method. This method take a list of parameters that will be used to build the feed.

How to let the user choose the format

In the previous example, we've seen how to create a RSS feed. But maybe some of your users would have preferred an Atom feed, so we will let the decide what format they prefer. We only need to update our previous route for this:

get '/feed/:year/:format' => sub {
  my $format = params->{format};
  my $articles = _articles(params->{year});
  create_feed(
    format => $format,
    ...
  );
};

Now, they can use e.g. /2010/atom.

Setting default values in your configuration

You can of course configure the default values for your feed in the configuration. We can create this configuration:

plugins:
  Feed:
    title: PerlDancer Advent Calendar
    copyright: PerlDancer
    tagline: PerlDancer advent calendar, a community effort
    description: this is a description for our calendar

Aliases methods

Dancer::Plugin::Feed export another two methods: create_rss_feed and create_atom_feed. Those method set the format argument for you.

get '/feed/atom' => sub {
    create_atom_feed(...);
};

get '/feed/rss' => sub {
    create_rss_feed(...);
};

See also

Under the hood, Dancer::Plugin::Feed uses XML::Feed.

Author

This article has been written by Franck Cuny for the Perl Dancer Advent Calendar 2010.

Copyright

Copyright (C) 2010 by Franck Cuny <franck@lumberjaph.net>