NAME

OpenInteract2::Action::RSS - OpenInteract2 action type for displaying RSS feeds

SYNOPSIS

 # Define the action type in your server configuration
 
 # In '$WEBSITE/conf/server.ini' (do this once per site)
 
 [action_types]
 ...
 rss = OpenInteract2::Action::RSS
 
 # Define the action that will use a RSS feed
 
 # In your package's 'conf/action.ini'
 
 [myaction]
 action_type  = rss
 feed_url     = http://somesite/rss.xml
 title        = My Feed
 template     = mypackage::myfeed
 cache_expire = 180m
 
 # Another example of an action:
 # Pull from a local file, grab the 'title' from the feed, use the
 # default template, and don't do any caching (NOT RECOMMENDED)
 
 [myaction]
 action_type = rss
 feed_url    = file:///home/httpd/mysite/html/feeds/rss.xml
 
 # Sample Template Toolkit Template displaying the feed
 
 <h3>[% title %]</h3>
 [% FOREACH entry = feed.entries -%]
 - [% OI.date_format( entry.issued, '%b %d, %r' ) %]:
     <a href="[% entry.link %]">[% entry.title %]</a><br />
 [% END -%]

DESCRIPTION

This module defines an OpenInteract2 action type. An action type is a class that can generally be instantiated through configuration only -- in this case we can define a component that fetches and displays an RSS feed without writing any code. (See OpenInteract2::Action for details on action types.)

Executing the action will ask XML::Feed to retrieve the RSS/Atom feed for us and parse it into an object. That object is passed to your template as 'feed' and you can then iterate over the items in the feed (with the entries() method). See the XML::Feed docs for more.

Note that the 'cache_expire' property (STRONGLY recommended) applies to the generated content.

Usage method: fetch feed separately

It doesn't seem that we can give XML::Feed a timeout value, so you may find it a good idea to decouple fetching the feed from parsing the feed:

• Assume we start with the following action (which specifies a box):

   [delicious_links]
   action_type  = rss
   feed_url     = http://del.icio.us/rss/cwinters/
   title        = Recent Links
   cache_expire = 180m
   template     = my_custom::delicious
   url_none     = yes
   weight       = 2
   num_display  = 8

• Using cron to fetch the RSS/Atom feed using wget; the following quietly retrieves the feed every 30 minutes:

   $ crontab -l
   
   # DO NOT EDIT THIS FILE - edit the master and reinstall.
   # (/tmp/crontab.XXXXQmyjPY installed on Wed Dec  8 08:46:34 2004)
   # (Cron version V5.0 -- $Id: crontab.c,v 1.12 2004/01/23 18:56:42 vixie Exp $)
   */30 * * * * /usr/bin/wget -q -O /tmp/delicious-cwinters.xml http://del.icio.us/rss/cwinters

  Adjust the time to whatever's appropriate for your feed source.

• Modify your action to reference the file:

   [delicious_links]
   action_type = rss
   feed_url    = file:///tmp/delicious-cwinters.xml
   ...

• Restart the server; you're good to go.

OBJECT METHODS

process()

Retrieve the feed from the given location, parse it and send it to a template. The parameters you can use to control this are:

feed_url (required)

URL from which we fetch the RSS/Atom. If you are fetching the feed using other means and want to retrieve it locally you can use a 'file://' URL as well.

template (optional)

Template to which we send feed data to generate the content. If you do not specify we use a default (listed below).

title (optional)

Title to use for feed in template. If you do not specify this or 'title_key' we pull the title from the feed.

title_key (optional)

Message key to use for the title. (See OpenInteract2::I18N.)

num_display (optional)

Number of entries to display. Defaults to displaying all.

Default template

Here is the default TT template we use:

 [%- rss_display_cap = OI.action_param( 'num_display' ) || feed.entries.size;
     count = 0; -%]
 <h3>[% title %]</h3>
 [% FOREACH entry = feed.entries;
        IF count < rss_display_cap; -%]
  - [% OI.date_format( entry.issued, '%b %d, %r' ) %]:
    <a href="[% entry.link %]">[% entry.title %]</a><br />
 [%     END;
        count = count + 1;
    END -%]

To use your own specify a 'template' parameter in the action. This template name should be in the normal 'package::template' format.

SUBCLASSING

If you want to modify how this action does some of its job you can subclass it and override some parts of process(). Here are the hooks available to you:

_get_feed_url()

Should return the URL for this feed. By default we use the value of the action parameter 'feed_url'.

If you cannot determine a feed URL you should die with an appropriate message.

_get_template_name()

Should return the fully-qualified name of a template. The default implementation looks in the 'template' parameter and if that's empty will use a default template.

If you cannot return a template name you should die with an appropriate message.

_get_title()

Return the feed title; if none returned we use the title from the XML::Feed object.

_modify_template_params( \%params )

Gives you a chance to modify the parameters passed to the template. The hashref \%params will contain the keys 'feed' (with an XML::Feed object) and 'title' (with the feed title). You can add new parameters, modify the feed or title, whatever you want.

_load_feed( $url )

Should return an XML::Feed object. Note that the implementation in this class takes care of 'file://' URL references as well as caching, so you might not want to override.

If you cannot return an XML::Feed object you should die with an appropriate message.

SEE ALSO

XML::Feed

COPYRIGHT

Copyright (c) 2004-5 Chris Winters. All rights reserved.

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

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::Action::RSS

perl -MCPAN -e shell
install OpenInteract2::Action::RSS