version=pmwiki-2.2.38 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=fix PmWiki.FAQ
name=PmWiki.WebFeeds
rev=80
targets=PmWiki.WikiTrails,Site.AllRecentChanges,Cookbook.Backlinks,PmWiki.WikiGroup,PmWiki.Categories,PmWiki.PageLists,Cookbook.RssFeedDisplay,PmWiki.LocalCustomizations,Cookbook.FeedLinks,Cookbook.PageFeed,Cookbook.CustomRecentChanges,PITS.01161
text=(:Summary:Web feed notification of changes:)%0a(:Audience: visitors (intermediate) :)%0aWeb 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 -> Wikipedia:Aggregator]] to quickly see what pages of interest have changed on a site.  Web feeds are commonly recognized by terms such as [[(Wikipedia:)RSS]], [[(Wikipedia:)Atom(_%2528standard%2529)]], and ''[[Wikipedia:web_syndication | web syndication]]''.  They are also the foundation for podcasting.%0a%0aIn 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 [[{$SiteGroup}.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%0a%0a->http://pmwiki.org/wiki/Site/AllRecentChanges?action=rss%0a%0aAuthors 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 -> WikiGroup]], [[categories]], and %25newwin%25[[Cookbook:Backlinks|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%0a%0a->http://pmwiki.org/wiki/Category/Skins?action=rss&order=-time%0a%0aPmWiki 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@]).%0a%0a!!How to read a PmWiki syndicated feed%0a%0a# You'll need a [[news aggregator -> Wikipedia:List_of_feed_aggregators]], 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.%0a# Subscribe to the [[WikiTrail(s)]] 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.%0a%0a!!Feed options%0a%0aAdd any of the following options to the end of a PmWiki web feed url to change its output (basically any [[pagelist->PageLists]] option is available for web feeds):%0a%0a:?count=''n'': Limit feed to ''n'' items (default 10)%0a:?order=-time : Display most recently changed items first (default: the order of the trail, or by name; in RecentChanges pages the trail is already ordered by -time)%0a:?trail=''page'': Obtain items from trail on ''page'' (default: the trail on the current page)%0a:?group=''group'': Limit feed to pages in ''group''%0a:?name=''name'': Limit feed to pages with specific ''name''%0a:?link=''page'': Create feed from pages linked to ''page''%0a:?list=normal: Exclude things like RecentChanges, AllRecentChanges, etc.%0a%0a%25audience%25 authors (intermediate)%0a!!Configure PmWiki for feeds%0a%0aThis 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.%0a%0aTo enable web feed generation for a site, add one or more of the following to a [[local customization(s)]] file:%0a%0a->[@%0aif ($action == 'rss') include_once("$FarmD/scripts/feeds.php");%0aif ($action == 'atom') include_once("$FarmD/scripts/feeds.php");%0aif ($action == 'rdf') include_once("$FarmD/scripts/feeds.php");%0aif ($action == 'dc') include_once("$FarmD/scripts/feeds.php");%0a@]%0a%0aor 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%0a%0a->[@%0aif ($action == 'rss'  ||%0a    $action == 'atom' ||%0a    $action == 'rdf'  ||%0a    $action == 'dc') include_once("$FarmD/scripts/feeds.php");%0a@]%0a%0a!!Configure feed content%0aWeb feeds are highly configurable, new elements can be easily added to feeds via the $FeedFmt array. Elements in $FeedFmt look like%0a%0a[@$FeedFmt['atom']['feed']['rights'] = 'All Rights Reserved';@]%0a%0awhere the first index corresponds to the action (?action=atom), the second index indicates a per-feed or per-item element, and%0athe third index is the name of the element being generated. The above setting would therefore generate a "%3crights>All Rights Reserved%3c/rights>" in the feed for ?action=atom.%0a%0a[[#pitfall1]]%0aIf the value of an entry begins with a '%3c', 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 [[http://blogs.law.harvard.edu/tech/rss | RSS specification]] or other feed specifications for what feed content you can use.%0a%0aYou can also change an existing element rather than add a new one.  You can use the following lines to ensure that changes made to the wiki will be picked up by  some RSS readers that wouldn't otherwise "notice" a page has been changed:%0a%0a->[@%0a# Change the link URL when an item is edited.%0a$FeedFmt['rss']['item']['link'] = '{$PageUrl}?when=$ItemISOTime';%0a$FeedFmt['atom']['item']['link'] =%0a   "%3clink rel=\"alternate\" href=\"{\$PageUrl}?when=\$ItemISOTime\" />\n";%0a@]%0a%0a%0a!!See Also%0a%0a* [[Cookbook:FeedLinks]] - Add HTML %3chead> links for auto-discovery of your feeds.%0a* [[WikiTrails]]%0a* Wikipedia:Web_feed, Wikipedia:Web_syndication, Wikipedia:RSS_%2528file_format%2529, Wikipedia:Atom_%2528standard%2529%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: How do I include text from the page (whole page, or first X characters) in the feed body?  (note: markup NOT digested)%0a%0a    function MarkupExcerpt($pagename) {%0a      $page = RetrieveAuthPage($pagename, 'read', false);%0a      return substr(@$page['text'], 0, 200);%0a    }%0a%0a    $FmtPV['$MarkupExcerpt'] = 'MarkupExcerpt($pn)';%0a    $FeedFmt['rss']['item']['description'] = '$MarkupExcerpt';%0a%0a%25green%25 Q:Does this mean if I want to include the time in the rss title and "summary" to rss body I call [@$FeedFmt@] twice like so:%0a->[@$FeedFmt['rss']['item']['description'] = '$LastSummary'; %0a$FeedFmt['rss']['item']['title'] = '{$Group} / {$Title} @ $ItemISOTime';@] %25%25%0a%0a---> From mailing list Feb 13,2007, a response by Pm: Yes%0a%0aQ: How can I use the RSS %3cenclosure> tag for podcasting?%0a%0aA: For podcasting of mp3 files, simply attach an mp3 file to the page%0awith the same name as the page (i.e., for a page named Podcast.Episode4,%0aone would attach to that page a file named "Episode4.mp3").  The%0afile is automatically picked up by ?action=rss and used as an%0aenclosure.%0a%0aThe set of potential enclosures is given by the $RSSEnclosureFmt%0aarray, thus%0a%0a->[@$RSSEnclosureFmt = array('{$Name}.mp3', '{$Name}.wma', '{$Name}.ogg');@]%0a%0aallows podcasting in mp3, wma, and ogg formats.%0a%0a%0aQ: [[#AddSummary]] How to add "summary" to the title in a rss feed (ie. with [@?action=rss@])?%0a%0aA: Add this line in you [@local/config.php@]%0a%0a->[@$FeedFmt['rss']['item']['title'] = '{$Group} / {$Title} : $LastModifiedSummary';@]%0a%0a%0aQ: [[#AddDescriptionSummary]] How to add "description" to the title in an rss feed, and summary to the body?%0a%0aA: Add these lines to your [@local/config.php@]%0a%0a->[@$FeedFmt['rss']['item']['title'] = '{$Group} / {$Title} : {$Description}';@]%0a->[@$FeedFmt['rss']['item']['description'] = '$LastModifiedSummary';@]%0a%0a%0a'''NOTES:'''%0a* you need to replicate these lines for each type (atom, rdf, dc) of feed you provide.%0a* the RSS '''[@description@]'''-tag is not equivalent to the pmWiki ''[@$Description@]'' variable, despite the confusing similarity.%0a%0aQ: Some of my password-protected pages aren't appearing in the feed... how do I work around this?%0a%0aA: From a similar question on the newsgroup, Pm's reply:%0a%0aThe last time I checked, RSS and other syndication protocols didn't%0areally have a well-established interface or mechanism for performing%0aaccess control (i.e., authentication).  As far as I know this is%0astill the case.%0a%0aPmWiki's WebFeeds capability is built on top of pagelists, so it%0acould simply be that the $EnablePageListProtect option is preventing%0athe updated pages from appearing in the feed.  You might try%0asetting $EnablePageListProtect=0; and see if the password-protected%0apages start appearing in the RSS feed.%0a%0aThe "downside" to setting $EnablePageListProtect to zero is that%0aanyone doing a search on your site will see the existence of the%0apages in the locked section.  They won't be able to read any of%0athem, but they'll know they are there!%0a%0aYou could also set $EnablePageListProtect to zero only if ?action=rss:%0a%0a    if ($action == 'rss') $EnablePageListProtect = 0;%0a%0aThis limits the ability to see the protected pages to RSS feeds;%0anormal pagelists and searches wouldn't see them.%0a%0aLastly, it's also possible to configure the webfeeds to obtain%0athe authentication information from the url directly, as in:%0a%0a    .../Site/AllRecentChanges?action=rss&authpw=secret%0a%0aThe big downside to this is that the cleartext password will%0aend up traveling across the net with every RSS request, and%0amay end up being recorded in Apache's access logs.%0a%0aQ: How to add feed image?%0a%0aA: Add the following to ''local/config.php'' (this example is for [@?action=rss@]):%0a%0a->[@%0a$FeedFmt['rss']['feed']['image'] =%0a" %3ctitle>Logo title%3c/title>%0a %3clink>http://example.com/%3c/link>%0a %3curl>http://example.com/images/logo.gif%3c/url>%0a %3cwidth>120%3c/width>%0a %3cheight>60%3c/height>";%0a@]%0a%0a-> %25red%25Do not forget NOT to start with a '%3c' as there would be no %3cimage> tag around this...   See [[#pitfall1|here]].%0a%0aQ: How do I insert RSS news feeds into PmWiki pages?%0a%0aA: See [[Cookbook:RssFeedDisplay]].%0a%0aQ: How can I specify default feed options in a configuration file instead of always placing them in the url?%0aA: 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(s)]] file:%0a%0a->[@%0a   if ($action == 'rss')%0a     SDVA($_REQUEST, array(%0a       'group' => 'News',%0a       'order' => '-time',%0a       'count' => 10));%0a@]%0a%0aQ: Are there ways to let people easily subscribe to a feed?%0a%0aA: On some browsers (Mozilla Firefox), the visitor can see an orange RSS icon in the address bar, and subscribe to the feed by clicking on it. To enable the RSS icon, add this to config.php :%0a[@%0a$HTMLHeaderFmt['feedlinks'] = '%3clink rel="alternate" type="application/rss+xml" %0a  title="$WikiTitle" href="$ScriptUrl?n=Site.AllRecentChanges&amp;action=rss" />%0a%3clink rel="alternate" type="application/atom+xml" title="$WikiTitle"%0a  href="$ScriptUrl?n=Site.AllRecentChanges&amp;action=atom" />';@]%0a%0aYou can also add such a link, for example in your SideBar, @@[=[[Site.AllRecentChanges?action=atom | Subscribe to feed]]=]@@. %0a%0aQ: Can I create an RSS feed for individual page histories?%0aA: See Cookbook:PageFeed.%0a%0a%0aQ: How do I create a custom FeedPage similar to RecentChanges or AllRecentChanges, but with only certain groups or pages recorded?%0aA: See Cookbook:CustomRecentChanges. In a nutshell, you'll declare a $RecentChangesFmt variable with your dedicated FeedPage, and then wrap it in a condition of your choice. For example:%0a[@%0a   if (PageVar($pagename, '$Group')!='ForbiddenGroup') {%0a     $RecentChangesFmt['Site.MyFeedPage'] =%0a       '* [[{$FullName}]]  . . . $CurrentTime $[by] $AuthorLink: [=$ChangeSummary=]';%0a   }%0a@]%0a%0aQ: How can I update my RSS feed to show every edit for pages on that feed, not just new pages added to the feed?%0aA: Add unique guid links for each edit to your to congif.php file (see PITS [[PITS:01161|entry]]):%0a[@%0a   $FeedFmt['rss']['item']['guid'] = '{$PageUrl}?guid=$ItemISOTime';%0a@]%0a%0aA: Alternatively, you can create the option for edit monitoring by adding a qualifier for RSS links. This allows the user to choose between default ''new pages'' RSS feeds and ''new edits'' RSS feeds (pmwiki.org has this option enabled).%0a[@%0a   ## For new pages updates: http://example.com/wiki/HomePage?action=rss%0a   ## For edits updates: http://example.com/wiki/HomePage?action=rss&edits=1%0a   if(@$_REQUEST['edits'] && $action == 'rss')%0a     $FeedFmt['rss']['item']['guid'] = '{$PageUrl}?guid=$ItemISOTime';%0a@]
time=1337641611
