FeedPlugin

Syndication feed parser

This is a new plugin to render RSS and ATOM feeds from internet sites. It actually is a rework of the old HeadlinesPlugin now much leaner and more robust, i.e. facing unicode website feeds. Instead of implementing a RSS parser by its own FeedPlugin hands off duties to CPAN:XML::Feeed and only takes care of caching and integrating results on a Foswiki page.

Examples

List headlines at http://blog.foswiki.org; auto-discover news feed:

%STARTSECTION{"example1"}%
%FEED{
   "https://blog.foswiki.org" 
   discover="on"
   header="<div class='alt'>$n"
   footer="$n</div>"
}%
%ENDSECTION{"example1"}%

Format the most recent posting on the Foswiki Blog:

%STARTSECTION{"example2"}%
%FEED{
   "https://blog.foswiki.org/Blog/WebRss"
   limit="1"
   header="<div class='alt'>$n"
   format="---+!! <div class='foswikiGrayText foswikiRight foswikiNormal'>$date</div> [[$link][$title]]
           $content"
   footer="$n</div>"
}%
%ENDSECTION{"example2"}%

Syntax

Parameter	Description	Default
"..." or href="..."	source url; this can either be a direct link to the RSS/ATOM feed or to the website serving the feed in which case you need to enable discover
expire="..." or refresh="..."	refresh rate for caching the feed; this can be specified using an expiry term such as 1 d for one day or 1 h for one hour etc	specified in $Foswiki::cfg{FeedPlugin}{CacheExpire}, defaults to 1 d
limit="..."	maximum items to show	0 (no limit)
skip="..."	number of items in the feed to skip showing the rest	0
header="..."	format string to be prepended to the list of items in the feed
format="..."	format string for each item on a feed	* [[$link][$title]]
footer="..."	format string to be appended to the list of items in the feed
separator="..."	format string to separte items in the feed
discover="on/off"	switch on feed discovery starting at the source url	off
decode="on/off"	switch on entity decoding of the feed before parsing it	off
exclude="..."	regular expression of items not to be included
include="..."	regular expression of items to be included
since="..."	return entries in feed newer than the given time

An empty result will be returned when no items have been found in the feed (or all items have been skipped).

The format parameter may contain the following variables expanding to respective properties of a feed item:

• $author
• $base
• $category
• $content
• $id
• $index
• $issued, $issued(<date-format>)
• $date, $date(<date-format>)
• $link
• $modified, $modified($lt;date-format>)
• $summary
• $tags
• $title

In addition the header, format, separator and footer format strings may contain:

• $feed_author
• $feed_base
• $feed_copyright
• $feed_format
• $feed_generator
• $feed_language
• $feed_link
• $feed_modified, $feed_modified($lt;date-format>)
• $feed_tagline
• $feed_title

… as well as the standard escapes:

• $percnt
• $dollar
• $n

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Contrib::CacheContrib	>=0	Required
XML::Feed	>=0.53	Required
HTML::Entities	>=0	required

Change History

29 Apr 2024	rework of internal api for better integration in upcoming MastodonPlugin
28 Apr 2022	added parameter to decode html entities; added include and exclude parameters
20 Oct 2020	use Foswiki:Extensions/CacheContrib instead of local caching code
28 May 2018	support $date as a synonym for $issued, added expire parameter (basically an alias for refresh but more intuitive); supports Foswiki's standard proxy/noproxy settings
24 Apr 2016	fixed docu; fixed discover mode; added support for non-unicode Foswiki engines
18 Mar 2016	be more robust on feeds not publishing proper dates
16 Mar 2016	initial release