Recent Changes - Search:
Cookbook /

RssImproved

Summary: How to get better RSS compatibility & support; how to create podcasts or audioblogs
Version:
Prerequisites:
Status: Deprecated
Maintainer: Crisses
Categories: Obsolete

Questions

This recipe is deprecated in favor of WebFeeds. Patrick has moved the ability to use podcasting/enclosures into scripts/feeds.php. Please see the indicated page for directions.

At this time, rssenclosures.php is broken.

Follow the instructions to include rssenclosures.php instead of the rss.php that is included with PmWiki. This file improves on the original RSS features of PmWiki, including feed validation, while maintaining compatibility with the rss.php settings in PmWiki distributions. Configuration settings described on the PmWiki page PmWiki.RSS will work with this module. Many options and improvements are described below.

rssenclosures.phpΔ

Notes and Comments | Terms | Installation | Methods | Options | News Feed Usage | Podcast/Enclosure Usage | Suggested Uses & Hints | Known Issues | See Also | Problems & FAQ

Notes and Comments

  • This recipe was last tested on PmWiki version: 2.0 beta 37, and was originally created on 2.0 beta 26
  • This recipe requires at least PmWiki version: 2.0 beta ? In addition, if enclosures are included (any files including audio files, attached to the feed) this module requires uploads enabled before rssenclosures.php is called.
  • This module is based on the scripts/rss.php that is included with the standard PmWiki distribution, is fully backward-compatible, and extends the functions, options and features of rss.php. At some point, this may be moved into the main PmWiki distribution.
  • It is recommended to put this into either cookbook/ or local/ -- do not replace scripts/rss.php or it will be overwritten if you upgrade your PmWiki distribution.
  • Podcasting/enclosure support requires uploads to be enabled and $EnableRssEnclosures = 1; to be set in config.php before calling rssenclosures.php (see usage below).
  • If you are using this module, do not enable rss.php in your config.php. rssenclosures.php is an upgrade and supports all the default behaviors of rss.php. Disable rss.php when using this module, or change "scripts/rss.php" to "cookbook/rssenclosures.php".
  • I put the altered rssenclosures.php in my farm's local dir. It should probably go into cookbook/ I have documented below as if it is in cookbook/.

Terms

Podcast
see Wikipedia:Podcasting
RSS
see Wikipedia:RSS
feed
the entire distribution -- the whole news package. Compare it to a magazine, or an entire book. In the radio world, it's the equivalent of the syndicated show, as opposed to the topic or features of a particular broadcast.
item
one of the "articles" or "episodes" of the feed. Compare it to an article in the magazine, or a chapter in a book. In the radio world, this is the equivallent of an individual broadcast for a show.
enclosure
the file that is attached to an item -- for Podcasts, the enclosure is the audio file.

The best way to understand an RSS feed is to see them in action. Wikipedia can help you there.

Installation

  1. Enable Uploads -- even if you password it so that no one else can use it.
  2. Think about a name and description for your RSS feed &/or podcast that you are going to live with for the life of your feed -- once you apply for directory listings, some directories may never change what you are listed as, and the consistency and forethought will do you good.
  3. Download the rssenclosure.php and place it in your pmwiki cookbook/ directory. (If you choose to put it in local/ be sure to change the instructions below where cookbook/ is mentioned)
  4. Open your local/config.php file for editing
  5. Choose one of the following methods for using RSS. Each includes comments about "options", relating to the addition of variables in the Options section. Make changes to your local/config.php as necessary.
  6. Choose a URL for the feed -- such as http://your.site.here/path/to/pmwiki/Main/AllRecentChanges?action=rss
  7. Test the feed at the RSS Feed Validator
  8. Test the feed in an RSS reader or RSS-enabled web browser, podcast management program, etc.
  9. Tweak options until you are satisfied with how it works, how it looks, and how it behaves.
  10. See the hints below
  11. Announce the feed to the world (list it on a newsgroup, website, or a rss source site or podcast directory service).

Methods

RSS enabled ONLY - entire site -- no enclosures. A typical news-feed with articles attached.

	// load alternate rss.php
	if ($action == 'rss' || $action == 'rdf')
			  include_once("cookbook/rssenclosures.php");

wikifarm use: RSS enabled ONLY - entire site -- no enclosures. A typical news-feed with articles attached. This can be put into a farmconfig.php for enabling rss for all fields, if rssenclosures.php is in the wikifarm's cookbook directory. To enable for selected fields only, put this directive in the field's local/config.php only, with the module in the wikifarm's cookbook directory.

	// load alternate rss.php
	if ($action == 'rss' || $action == 'rdf')
			  include_once("$FarmD/cookbook/rssenclosures.php");

RSS enabled site-wide, with podcasts only in a specific group

This enables normal RSS for the entire site except the MyPodcasts group, which has RSS with the addition of uploads and the enclosures necessary for podcasting. (This is how I have mine set up.) 

        // Put any RSS feed options that you want for the whole site here

	// Begin podcasting setup only for group MyPodcasts       
		if (preg_match('/^MyPodcasts\//',$pagename)){
			$EnableUpload = 1;
			$DefaultPasswords['upload'] = crypt('mysecretandyoucanthaveit');
			$EnableRssEnclosures = 1;
                       // Any other options added here apply to only feeds within this group
                          // a good opportunity to give the feed a different title, etc.
		}

	// load alternate rss.php -- see notes above about wikifarm usage
	if ($action == 'rss' || $action == 'rdf')
			  include_once("cookbook/rssenclosures.php");

To enable RSS (text only) for the MyNewscasts group -- the rest of the site does NOT have RSS-enabled

	// Enable RSS with podcasting only for the specified group e.g. MyNewscasts       
		if (preg_match('/^MyNewscasts\//',$pagename)){
                          // options added here apply to all RSS feeds in this group

         	          // load alternate rss.php -- see notes above about wikifarm usage
	                  if ($action == 'rss' || $action == 'rdf')
         			  include_once("cookbook/rssenclosures.php");
		}

To enable RSS & enclosures only for the MyPodcasts group -- the rest of the site does NOT have RSS-enabled

	// Enable RSS with podcasting only for the specified group e.g. MyPodcasts       
		if (preg_match('/^MyPodcasts\//',$pagename)){
			$EnableUpload = 1;
			$DefaultPasswords['upload'] = crypt('mysecretandyoucanthaveit');
			$EnableRssEnclosures = 1;
                        // Any other options added here apply to all RSS feeds/podcasts in this group

         	          // load alternate rss.php -- see notes above about wikifarm usage
	                  if ($action == 'rss' || $action == 'rdf')
         			  include_once("cookbook/rssenclosures.php");
		}

To enable podcasting or enclosures for all groups (a whole site full of podcasts):

		$EnableUpload = 1;
		$DefaultPasswords['upload'] = crypt('mysecretandyoucanthaveit');
		$EnableRssEnclosures = 1;
                // Any other options added here apply to all RSS feeds/podcasts on the site

         	          // load alternate rss.php -- see notes above about wikifarm usage
	                  if ($action == 'rss' || $action == 'rdf')
         			  include_once("cookbook/rssenclosures.php");

Options

While it is not 100% necessary -- you can and should probably define some of the following optional variables:

Feed email address

This is a contact email address for the entire feed, used in conjunction with every author's name. In the future may be replaced with something more dynamic, but for now this allows the feed to validate with an Author field. 

                 $RssEmailAddress = "rssfeed@mysite.tla";

Items in the Feed

This defines how many articles/items are in the feed. Podcasts usually don't have more than 10. Default is 20, which is a lot when there are files to download with them. 

                 $RssMaxItems = 20;

Source Size (descriptions)

How much text is read from a page to build descriptions from -- before tags and invisibles are removed. Keep this much larger than Description Size below. Default 400. 

                 $RssSourceSize = 400;

Description Size (descriptions)

How many characters of text are used to build descriptions. Default 200. 

                 $RssDescSize = 200;

Enable Enclosures

This is shown in use above in the Methods section. Default is "off" or 0. Changing it to 1 turns the feature on. 

                $EnableRssEnclosures = 0;

Enclosure File Type

optional -- 'mp3' is the default. Change to 'ogg' .... for other formats. 

                $RssEnclosureTLA = 'mp3';

Note: this may break using other formats if PmWiki does not have metatag information for the filetype/extension. I use the metatag information built in to PmWiki. Note 2: When using the Attach: directive (see Podcast Usage below) the filename should end in the proper filetype extension that you specify here, NOT in "mp3". The behavior in Podcast Usage reflects the default filename extension, and using this option changes that default behavior.

Feed Title

Main title of the RSS/Podcast feed -- applies for the whole feed. Like the title of the show, the book, the magazine. I consider redefining this as absolutely essential, otherwise it defaults to the website title, group title and page title that the feed points to (default: "MyWiki | Main / AllRecentChanges"). Change this to the second option below and this can also be defined by the (:title:) tags on the main feed page. 

                $RssFeedTitle = 'My Whopping Great Podcast!';
                $RssFeedTitle = '$Title';

Feed Description

Description for the RSS/Podcast feed -- applies for the whole site. This is used by directory listing services, and some readers or feed browsers. A good place to summarize the feed. Defaults to the first 200 characters or so of the page. 

                $RssFeedDesc = 'This is a podcast to end all podcasts.  In it you will hear lots of incessant
                   babble and inside-jokes that ony we understand.  It's our hopes that you will listen long
                   enough to become an insider so you can get our lame humor as well.';

Feed Description Markup - Upcoming Feature!! not enabled in the code yet

Allows pages to use the format (:description I have the best podcast in the world!:) on the main feed webpage to create both the description for the feed and the metatag for the HTML web page. Default is off. 

                $RssFeedDescFromMetadata = 1;

Item Description Markup - Upcoming Feature!! not enabled in the code yet

Allows pages to use the format (:description This particular article is about rabbits.:) on individual pages to create the description for the article/item and the metatag for the HTML web page. Default is off. 

                $RssItemDescFromMetadata = 1;

Item Title Only

Default is for items to be listed as "GroupName / TitleOfPage" -- this changes the behavior to only the title of the page. To customize the title of the page, use the wiki markup (:title This is a Great Page:) on each page in the feed. 

                $RssItemTitleOnly = 1;

Feed Options -- Advanced!

Allows adding optional tags to the RSS feed ex. contact email address for the feed, copyright info for the entire broadcast -- note that these must comply to RSS markup standards. Content between the tags will be static unless you program PmWiki to provide dynamic content in your tags. 

                $RssFeedOptions = '<xmltag>Info for whole feed</xmltag>';

Item Options -- Advanced!

Allows adding optional tags to the RSS items -- note that these must comply to RSS markup standards. Content between the tags will be static unless you program PmWiki to provide dynamic content in your tags. 

                $RssItemOptions = '<xmltag>Info for each item</xmltag>';

News Feed Usage

  1. Create wiki pages
  2. Create a wiki trail or use the Group/RecentChanges or Main.AllRecentChanges pages, which automatically do so for you.
    1. Optional: add (:title Text Here :) and/or (:description Text Here :) tags to refine how the items will look in a news aggregator/reader
  3. Add the link http//.../Main/AllRecentChanges?action=rss (or other similar page with "?action=rss" appended to the URL) to a news reader or RSS-enabled browser to see the fruits of your labors
  4. Tweak as necessary

To add additional articles to the news feed, create another page, and add it to the trail. If customizing your own trail, add the newest items to the TOP of the trail.

Podcast/Enclosure Usage

  1. On MyPodcasts/IndexPage (choose your own name for the group. A dedicated group is suggested.) create a bullet item for a page like MyPodcasts/PageName 
 * PageName
  1. edit PageName
  2. Write a small blurb and "Attach:PageName.mp3" (make sure you use the exact same name as the page with ".mp3" on the end!)

example:
replace 

 edit PageName here:

with 

 Here is my first podcast!  Yay!
 Attach:PageName.mp3
then click "save" to save the page
  1. Click the attach link and upload your mp3
  2. go to http://feedvalidator.org/ and enter the URL for your MyPodcasts/IndexPage?action=rss page -- click Validate. This will validate the feed format for the page as being valid. (if you have problems with validation, read some of the options in this page, such as having a feed email address. If you can't figure out what is wrong, contact Crisses on the PmWiki user list for help, or add questions and comments to the bottom of this page.)
  3. Add the link http//.../MyPodcasts/IndexPage?action=rss to the appropriate podcast retrieval software (see Wikipedia link below)) and it should download the mp3 file
  4. Tweak as necessary
Note: to add additional audio blog files, start over at #1 (i.e. create a new bulleted link on IndexPage). Add newest items to the top of the trail.

Suggested uses & hints:

  • If you are going to audioblog on a regular basis, choose a consistent naming scheme for new pages (since this will also affect the attachment names you use). Try something like MyPodcasts-date or MyInitials-serialnumber. These files are going to end up in someone's music library -- they need to both be easy to locate, and easy to sort in order. Be consistent. I have ManyMinds001-credentials.mp3 and the page is thus ManyMinds/ManyMinds001-credentials in my wiki. If someone sorts their mp3 library, all my podcasts will be in the same place, in the correct order, and include a little hint for what the podcast is about in the title, so the listener can find them by theme or search for it. You can give the page a pretty title by using the (:title My Much Nicer Looking Title broadcast #001 :) markup.
  • Add the newest bullet item to the TOP of the wiki trail lists. RSS feeds often only take the first few lines ($RssMaxItems defaults to 20 but people can choose less in their news/podcast software), newest items are always at the top of the page, and you won't want to re-shuffle it later.
  • You can use the GroupName/RecentChanges?action=rss page instead of creating a new page in the group for the wiki trail/feed. -- you may want to password the edit function on the page to keep wikivandals from editing it. If you use this method and change a page from a former newscast/podcast it will shuffle to the top. For podcasts, keep in mind that this may re-download the mp3 for the end-users of the feed, which may not be desirable.
  • Put a short blurb/summary at the top of the feed page saying what it is about -- it is included as a description of the article or audio episode. (length determined by $RssSourceSize (default 400) and $RssDescSize (default 200)). Hopefully the metatag-as-description option will be put into use soon, so that (:description This is a really great article contributed by the masses to this site! :) will come out as the description of the article, rather than having to put it explicitly on the webpage.
  • When doing enclosures or podcasts, put the attach: enclosure markup tags UNDER the article/episode description. Everything will come out prettier in the end.

Known Issues

  • FIXED: There is currently a bug in the program: The RSS tags for an enclosure will be processed even if there is no enclosed file. This can't be enabled for the whole site if there are sections that do not have mp3 files; it will produce an error or an invalid enclosure tag. Update: the enclosure filename is checked. If the filename does not exist, the enclosure tags are deleted from the items in the feed. This means you can now mix text-only announcements and enclosure-based feeds into the same broadcast.
  • FIXED: This page needs anchor markup badly ;)
  • FIXED: For some reason my blocklist page is showing up in the feed. The fact that it has a read restriction is not stopping it. I have it set up with restrictions on both the config level and on the wiki attr level. But it shows up in the RSS feed anyway. Oh -- the reason it was showing up was because I was validated to view the page. This would only be a problem if RSS pages were cached. That would need to be addressed.
  • FIXED: Problems with the feed description not showing up.
  • FIXED: Problem with the enclosures not passing the fileexists() check -- forgot to include a global variable. Big oops.
  • FIXED: PubDate format is not validating for RSS 2.0 -- format needs updating to "Sat, 07 Sep 2002 00:00:01 GMT" format.
  • FIXED: Optional item "contributor" element does not exist in RSS 2.0 -- change to "author". This field still does not validate -- supposed to include an email address. Added $RssEmailAddress field for the setup, can optionally add an email address for the entire feed, which will show up as the contact email address for every author in the feed. Fiddled with this until it created a valid email address field according to RSS standards.

See Also

Wikipedia:Podcasting
PmWiki.RSS
http://blogs.law.harvard.edu/tech/rss - specifications for RSS 2.0

Contributors

Crisses XES

Problems & FAQ

please add your questions & comments below:

  • never tried rss until I tried this. Great for checking for updates. However it does not pick up when comments are added to page with commentbox. Any ideas?
    • found the answer. There are multiple groups so the alternate link for rss has to point to AllRecentChanges rather than just RecentChanges

$HTMLHeaderFmt['rss'] = 

      "<link rel='alternate' title='\$WikiTitle RSS'
        href='\$ScriptUrl/\$Group/AllRecentChanges?action=rss' 
        type='text/xml' />";
  • I can't retrieve my feeds when a read password is set on the wiki. Is there a way to fix this?
    • The same for me. The feed only works if before the user has entered the password directly on the wiki... so that the feed is not of much interest.
    Technically this problem can't be fixed unless you want anyone able to read those pages via RSS. I don't think you can "log in" via RSS feeds -- they're publicly accessible. If you want email updates when things change on the site, see the NotifyPosts information elsewhere.
    XES
  • The enclosure tag does not include the URL for the file. This can be corrected by change RssItemEnclosureUrl to $RssItemEnclosureUrl in the rssimproved.php file. Is this a bug?
    ate2 -> mailto:ate2 [snail] cornell [period] edu
  • When I try to validate my feed, I get this message:

line 20, column 10: url attribute of enclosure must be a full URL [help] 

              <enclosure url="RssItemEnclosureUrl" length="26275099" type="audio ...
alessia -> mailto:alexandrasourisseau [snail] gmail [period] com