visitors (intermediate)
Web feeds are a convenient mechanism to let visitors be notified of changes to a site. Instead of repeatedly checking RecentChanges every day to see what is new, a visitor can use a news aggregator to quickly see what pages of interest have changed on a site. Web feeds are commonly recognized by terms such as RSS, Atom, and web syndication. They are also the foundation for podcasting.
In its simplest form, web feeds in PmWiki are built on WikiTrails. Using a feed action such as ?action=rss or ?action=atom on a trail generates a web feed (often called a "channel") where each page on the trail is an item in the feed. Since the RecentChanges and Site.AllRecentChanges pages are effectively trails, one can easily get an RSS feed for a group or site by simply adding ?action=rss to the url for a RecentChanges page. For example, to get the site feed for pmwiki.org, one would use
http://www.pmwiki.org/wiki/Site/AllRecentChanges?action=rss
Authors can also create custom feeds by simply creating a wiki trail of the pages they want included in the feed. Feeds can also be generated from groups, categories, and backlinks, and the order and number of items in the feed can be changed using options in the feed url. Thus, one can obtain a feed for the Skins category (sorted with most recent items first) by using
http://www.pmwiki.org/wiki/Category/Skins?action=rss&order=-time
PmWiki is able to generate feeds in many formats, including RSS 2.0 (?action=rss), Atom 1.0 (?action=atom), and RSS 1.0 (?action=rdf). In addition, although it is not normally considered a web feed, PmWiki can generate metadata information using the Dublin Core Metadata extensions (?action=dc).
How to read a PmWiki syndicated feed
- You'll need a news aggregator, which is a piece of software designed to read news feeds. Many different news aggregators are available. Some run on your own computer, either on their own or as plugins for email clients, web browsers, or newsreaders. Others are web applications that you can use from any Internet-connected computer. Some are in between (technically web applications, but ones designed to run on your computer, not some remote server). Get one that you like.
- Subscribe to the WikiTrail you desire by supplying the feed url to the aggregator. The feed url will be the name of a trail page with
?action=rss or ?action=atom added to the end of the url.
Feed options
Add any of the following options to the end of a PmWiki web feed url to change its output (basically any pagelist option is available for web feeds):
- ?count=n
- Limit feed to n items
- ?order=-time
- Display most recently changed items first
- ?trail=page
- Obtain items from trail on page
- ?group=group
- Limit feed to pages in group
- ?name=name
- Limit feed to pages with specific name
- ?link=page
- Create feed from pages linked to page
- ?list=normal
- Exclude things like RecentChanges, AllRecentChanges, etc.
authors (intermediate)
Configure PmWiki for feeds
This section describes how to syndicate portions of a wiki to appear in a web feed. It does not describe how to display a web feed within a wiki page -- for that, see Cookbook:RssFeedDisplay.
To enable web feed generation for a site, add one or more of the following to a local customization file:
if ($action == 'rss') include_once('scripts/feeds.php');
if ($action == 'atom') include_once('scripts/feeds.php');
if ($action == 'rdf') include_once('scripts/feeds.php');
if ($action == 'dc') include_once('scripts/feeds.php');
or you can combine multiple feeds into a single expression using "||" to separate each feed type. For example, if you want to enable RSS and Atom feeds you would use
if ($action == 'rss' ||
$action == 'atom' ||
$action == 'rdf' ||
$action == 'dc') include_once("$FarmD/scripts/feeds.php");
Configure feed content
Web feeds are highly configurable, new elements can be easily added to feeds via the $FeedFmt array. Elements in $FeedFmt look like
$FeedFmt['atom']['feed']['rights'] = 'All Rights Reserved';
where the first index corresponds to the action (?action=atom), the second index indicates a per-feed or per-item element, and
the third index is the name of the element being generated. The above setting would therefore generate a "<rights>All Rights Reserved</rights>" in the feed for ?action=atom. If the value of an entry begins with a '<', then feeds.php doesn't automatically add the tag around it. Elements can also be callable functions which are called to generate the appropriate output.
See Also
<< Notify | Documentation Index | RefCount >>
How can I use the RSS <enclosure> tag for podcasting?
For podcasting of mp3 files, simply attach an mp3 file to the page
with the same name as the page (i.e., for a page named Podcast.Episode4,
one would attach to that page a file named "Episode4.mp3"). The
file is automatically picked up by ?action=rss and used as an
enclosure.
The set of potential enclosures is given by the $RSSEnclosureFmt
array, thus
$RSSEnclosureFmt = array('{$Name}.mp3', '{$Name}.wma', '{$Name}.ogg');
allows podcasting in mp3, wma, and ogg formats.
How to add "summary" to the title in a rss feed (ie. with ?action=rss)?
Add this line in you local/config.php
$FeedFmt['rss']['item']['title'] = '{$Group} / {$Title} : $LastModifiedSummary';
How to add feed image?
Add the following to local/config.php (this example is for ?action=rss):
$FeedFmt['rss']['feed']['image'] =
"<title>Logo title</title>
<link>http://www.example.com/</link>
<url>http://www.example.com/images/logo.gif</url>
<width>120</width>
<height>60</height>";
How do I insert RSS news feeds into PmWiki pages?
See Cookbook:RssFeedDisplay.
How can I specify default feed options in a configuration file instead of always placing them in the url?
For example, if you want ?action=rss to default to ?action=rss&group=News&order=-time&count=10, try the following in a local customization file:
if ($action == 'rss')
SDVA($_REQUEST, array(
'group' => 'News',
'order' => '-time',
'count' => 10));
