Catalyst::Model::XML::Feed - Use RSS/Atom feeds as a Catalyst Model

Catalyst-Model-XML-Feed documentation Contained in the Catalyst-Model-XML-Feed distribution.

Index

Code Index:

NAME

Top

Catalyst::Model::XML::Feed - Use RSS/Atom feeds as a Catalyst Model

VERSION

Top

Version 0.04

SYNOPSIS

Top

In your own model:

     package MyApp::Model::Feeds;
     use base qw(Catalyst::Model::XML::Feed);

Then from elsewhere in your application:

     $c->model('Feeds')->register('delicious', 'http://del.icio.us/rss');
     $c->model('Feeds')->register('http://blog.jrock.us/');

     my @feeds     = $c->model('Feeds')->get_all_feeds;
     my $delicious = $c->model('Feeds')->get('delicious');

You can also pre-register feeds from your config file:

     ---
     Model::Feeds:
       feeds:
         - uri: http://blog.jrock.us/
         - uri: http://search.cpan.org/
         - title: delicious
           uri: http://del.icio.us/rss/

See CONFIGURATION below for details.

DESCRIPTION

Top

Catalyst::Model::XML::Feed allows you to use XML feeds in your Catalyst application. To use a feed, you need to register it with the register method.

Once a feed is registered, it's automatically cached for you.

CONFIGURATION

Top

Configuration is accepted via the standard Catalyst method:

    $c->config->{Model::Feeds}->{key} = $value;

Valid keys include:

ttl

Time To Live, in seconds, for each feed. If a feed is older than this value, it is refreshed from its source. Defaults to 3600 seconds, 1 hour.

feeds

An arrayref of hashes containing feeds to preload. The hash is required to contain a key called "uri" or "location", specifing the URL of the feed to load. It may optinally contain "name" or "title", if you wish to override the feed's own title.

Example config in MyApp.yml (assuming you call your feed model Feeds):

     Model::Feeds:
       feeds:
         - uri: http://blog.jrock.us/
         - title: delicious
           location: http://del.icio.us/rss/
       ttl: 1337

METHODS

Top

new

Creates a new instance. Called for you by Catalyst. If your config file contains invalid feeds the feed will be refetched when the feed content is accessed. This allows your Catalyst app to start even in the case of an external outage of an RSS feed.

register($uri_of_feed)

Registers a feed with the Model. If $uri_of_feed points to a feed, the feed is added under its own name. If $$uri_of_feed points to an HTML or XHTML document containing <link> tags pointing to feeds, all feeds are added by using their URIs as their names.

Returns a list of the names of the feeds that were added.

Warns if the $uri_of_feeds doesn't contain a feed or links to feeds, or it cannot be fetched.

register($name, $uri_of_feed)

Registers a feed with the Model. If $name is already registered, the old feed at $name is forgotten and replaced with the new feed at $uri_of_feed. The title of the feed is replaced with $name.

Warns if $uri_of_feed isn't an XML feed (or doesn't contain a link to one).

Throws an exception if the $uri_of_feed links to multiple feeds.

names

Returns the names of all registered feeds.

get_all_feeds

Returns a list of all registered feeds. The elements are XML::Feed objects.

get($name)

Returns the XML::Feed object that corresponds to $name. Throws an exception if there is no feed that's named $name.

refresh([$name])

Forces the feed $name to be refreshed from the source. If $name is omitted, refreshes all registered feeds.

DIAGNOSTICS

Top

%s does not reference any feeds

The URI you passed to register was not a feed, or did not link to any feeds.

%s points to too many feeds

The URI you passed to register referenced more than one feed. If you want to register all the feeds, use the one argument form of register instead of the two argument form.

No feed named %s

The feed that you requested does not exist. Try registering it first.

AUTHOR

Top

Jonathan Rockway, <jrockway at cpan.org>

BUGS

Top

Please report any bugs or feature requests to bug-catalyst-model-xml-feed at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Model-XML-Feed. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Top

You can find documentation for this module with the perldoc command.

    perldoc Catalyst::Model::XML::Feed

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Catalyst-Model-XML-Feed

* CPAN Ratings

http://cpanratings.perl.org/d/Catalyst-Model-XML-Feed

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Model-XML-Feed

* Search CPAN

http://search.cpan.org/dist/Catalyst-Model-XML-Feed

SEE ALSO

Top

XML::Feed and XML::Feed::Entry

ACKNOWLEDGEMENTS

Top

COPYRIGHT & LICENSE

Top

Copyright 2006 Jonathan Rockway, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Catalyst-Model-XML-Feed documentation Contained in the Catalyst-Model-XML-Feed distribution. 
package Catalyst::Model::XML::Feed;

use warnings;
use strict;

use base qw(Catalyst::Model Class::Accessor);
use Carp;
use XML::Feed;
use MRO::Compat;
use URI;
use Catalyst::Model::XML::Feed::Item;

__PACKAGE__->mk_accessors(qw|ttl feeds|);


our $VERSION = '0.04';


sub new {
    my $self = shift;
    $self = $self->next::method(@_);
    my @in_feeds = eval { @{$self->feeds} };
    $self->feeds({});

    $self->ttl($self->ttl || 3600);
    foreach my $feed (@in_feeds) {
        my $name = $feed->{name} || $feed->{title};
        my $uri  = $feed->{uri}  || $feed->{location};
        #my $c = $_[0];
        if($name){
            #$c->log->debug("registering XML feed $uri as $name") if $c;
            $self->register($name, $uri);
        }
        else {
            #$c->log->debug("registering XML feed $uri") if $c;
            my @names = $self->register($uri);
            my $name = join q{,},@names;
            #$c->log->debug("feed(s) at $uri created as $name") if $c;
        }
    }

    return $self;
}


sub register {
    my $self = shift;
    my ($arg1, $arg2) = @_;

    my $name;
    my $uri;

    if($arg2){
        # get only one feed
        $name = $arg1;
        $uri  = URI->new($arg2);
        my $feed;
        eval {
            $feed = XML::Feed->parse($uri)
                or die XML::Feed->errstr;
        };
        if($@){
            my @feeds = XML::Feed->find_feeds($arg2);
            if(@feeds > 1){
                croak "$arg2 points to too many feeds";
            }
            if(!@feeds){
                carp "$arg2 does not reference any feeds";
		# register $uri as it is, but without the feed, in hope that it comes online later.
            } else {
		$uri = shift @feeds;
	    }
        }

        return $self->_add_uri($uri, $name);
    }
    else {
        $uri = URI->new($arg1);
        my @feed_uris = XML::Feed->find_feeds($uri);
        croak "$arg1 does not reference any feeds" if !@feed_uris;

        my @added;
        foreach my $uri (@feed_uris){
            $uri = URI->new($uri);
            my $name = $self->_add_uri($uri);
            push @added, $name if $name;
        }
        return @added;
    }
}

sub _add_uri {
    my $self = shift;
    my $uri  = shift;
    my $name = shift;
    my $feed;

    eval {
        $feed = XML::Feed->parse($uri)
            or die XML::Feed->errstr;
    };
    if (my $err = $@) {
        carp "Failed to parse feed $uri: $@";
	my $key = $name || $uri;
	# Create feed item without the parsed content then
	$self->feeds->{$key} = Catalyst::Model::XML::Feed::Item->new(undef, $uri);
	return $key;
    }
    $feed->title($name) if $name;
    my $obj  = Catalyst::Model::XML::Feed::Item->new($feed, $uri);
    $name ||= $uri;

    $self->feeds->{$name} = $obj;
    return $name;
}


sub names {
    return keys %{$_[0]->feeds};
}


sub get_all_feeds {
    my $self  = shift;
    my @names = $self->names;
    my @feeds;
    foreach my $name (@names){
        my $feed = $self->get($name);
        push @feeds, $feed;
    }
    return @feeds;
}


sub get {
    my $self = shift;
    my $name = shift;
    my $feed = $self->feeds->{$name};
    croak "No feed named $name" if !ref $feed;

    # refresh the feed if it's too old or if previous fetch failed
    if((time - $feed->updated > $self->ttl) or !defined($feed->feed)) {
        $self->_refresh($name);
	# must update the ref after the refresh for this run of the sub to return the fresh info.
	$feed = $self->feeds->{$name};
    }

    return $feed->feed;
}


sub refresh {
    my $self = shift;
    my $name = shift;

    if($name){
        $self->_refresh($name);
    }
    else {
        foreach my $name (keys %{$self->feeds}){
            $self->_refresh($name);
        }
    }

    return;
}

sub _refresh {
    my $self = shift;
    my $name = shift;
    my $feed = $self->feeds->{$name};
    croak "No feed named $name" if !ref $feed;

    my $uri  = $feed->uri;
    return $self->_add_uri($uri, $name);
}


1; # End of Catalyst::Model::XML::Feed