How-To: Generating RSS with Conversant

Introduction

The goal of this document is to explain the creation of basic RSS document with Conversant, and (wherever it's relevant) to provide suggestions for further exploration. Conversant doesn't have built-in support for generating RSS specifically (i.e. it won't create any RSS documents by default within a conversation), but the tools it provides are quite capable of being configured to do so. This configuration effort is rewarded with a large degree of flexibility, and, of course, once the initial configuration is complete Conversant will automatically update the RSS documents you create.

Two ways of generating RSS will be discussed in this how-to: using a WeblogView Page or an Advanced Query Page.

Prerequisites and Scope

While this how-to attempts to cover as much of the process of configuring Conversant to generate RSS as possible, it does expect you to be generally familiar with creating and editing templates, using the structure editor, and creating queries.

At the moment the scope of this how-to is limited to RSS 0.91, as specified by Netscape Communications and UserLand Software. Suggested revisions to support other versions are particularly welcomed.

RSS Compatibility

Before doing to much work you should make sure that your conversation is RSS compatible. This means, for example, if you include several individual items in a single post to your weblog (rather than posting each in its own message) you will probably not be able to fit this into the RSS title, link, and description model.

Using RSS requires some careful thought about how things are stored in your conversation and how you want that represented in the RSS document. If you want RSS to track activity in your discussion group this shouldn't be too much of a problem because you can build on Conversant's standard, built-in message fields. But, if you have a weblog where you post items with links to their source and a quote or some comments, and you would like your RSS document to link to the original source rather than to the message on your site this will be more difficult. (In this case you will probably have to create a custom message field for the external link URL.) Or, if several items are posted to a weblog within a single message you won't be able to have these items appear separately in your RSS document.

Creating the Templates

Regardless of which page type you've chosen to use you'll need to create a full page template for the common elements of an RSS document. These are the preliminary XML stuff and the tags that provide information about the channel, also called "metadata". The <!--#pageContent--> macro will be replaced by the individual <item> blocks generated with either a WeblogView Page or an Advanced Query Page, which will be explained in the following sections.

In the Templates section of the Conversant Admin for your conversation create a new Full Page template, and save it with the following contents:

<?xml version="1.0"?>
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
	"http://my.netscape.com/publish/formats/rss-0.91.dtd">
<rss version="0.91">
	<channel>
		<title>Being Green</title>
		<link><!--#siteURL--></link>
		<description>Recent updates to your roving reporter's weblog.</description>
		<language>en-us</language> 
		<copyright>Copyright 2001, Kermit the Frog</copyright> 
		<managingEditor>kermit@muppets.com (Kermit the Frog)</managingEditor> 
		<webMaster>professor@muppets.com (Dr. Bunsen Honeydew)</webMaster>
		<!--#pageContent-->
	</channel>
</rss>

Obviously, this should be customized for your own site. Here's some explanation of the different items:

<title>. The name of the channel. If you're creating an RSS document based on your weblog then this should be the same as the title of that weblog. (This can be up to 100 characters long.)

<link>. The URL of the website named in the title. Again, if the channel is from your weblog this should be the URL of your weblog. The <!--#siteURL--> macro is convenient to use here, and if you need this to point to a subpage simply insert the extra path information after the macro. (This can be up to 500 characters long.)

<description>. A short description of the contents of your channel. This might be a tagline for your weblog, or something like that used in the example above. The UserLand specification describes this as the "positioning statement" for the channel. (This can be up to 500 characters long.)

<language>. The principal language for the channel's content. A list of allowable values is available from UserLand. In the example, the language is set as US English.

<copyright>. A copyright notice for the channel. (This can be up to 100 characters long.)

<managingEditor> and <webmaster>. E-mail contacts for the channel. The former is for "editorial" inquiries, and the latter is for technical questions. In many cases these will be identical. The style used in the example is as recommended by the UserLand specification. (These can be up to 100 characters long.)

Folders and MIME Types

You may find it useful to create a specific folder for RSS, especially if there's a chance you might want to create several RSS documents. If you create an RSS folder, then its MIME Type property should be set to text/xml which will then apply to all the pages you create inside it. Normally, Conversant will expand URLs and e-mail addresses into complete HTML links (e.g. "http://www.free-conversant.com/" will become "<a href="http://www.free-conversant.com/">http://www.free-conversant.com/</a>"). This is convenient when creating regular pages, but will cause problems with RSS feeds; setting the MIME Type will prevent this expansion.

The Template property of this folder could also be set to the full page template created earlier. It would then be inherited by any pages inside the folder, but of course this won't prevent using different templates for specific RSS feeds. Different templates would be useful for having different channel description information (title, link, description, language, etc.).

Using a WeblogView Page

The WeblogView method is the easier of the two methods for creating an RSS document but it is less flexible: it can only include full days of items posted to a specific weblog page (either just the most recent day with posts or optionally the most recent plus a number of previous days you specify).

First, you'll need to create a weblogview page in your structure editor. The RSS specification doesn't require the use of any particular file name or extension, but the .rss file extension is commonly used (for example, you might name this page "daily.rss").

On the Basic tab make sure that the Template is set to the full page template created earlier, and the MIME Type is set to text/xml. (If you've created a folder as explained in the section on creating on folders and mime types -- and set these properties there -- then "[use parent folder template]" and "[use parent folder mime type]" are also acceptable settings.)

Then, on the options tab, specify which weblog you want to generate an RSS document from and the number of days to include.

Finally, you need to configure the templates. Using the templates suggested here the "Text to insert between dual carriage returns" property shouldn't have any effect, but for completeness it should be made blank. The Item Template is the one that will generate the individual <item> blocks so the Day Template only needs to have the macro to include them. That is:

<!--#weblogDayText-->

The Day Template should then be something like:

<item>
	<title><!--#subject--></title>
	<link><!--#siteUrl--><!--#msgNum--></link>
	<description><!--#insertStrippedClip msg="<!--#msgNum-->" length="250"--></description>
	</item>

Using the insertStrippedClip macro will remove any HTML from the source message as required by the specification. The value of the length parameter could be adjusted to include more or less of the source message, but the specified limit is 500 characters.

If you are interested Duncan Smeed has posted an excellent series of screenshots documenting the WeblogView Page-based RSS document he created for his Duncan's Jotter website.

Using an Advanced Query Page

Using the AQP is more complex because unlike a WeblogView Page, which only displays the messages posted to a particular weblog, an AQP displays all the messages matching a specific query hence the name. In terms of RSS this means you have a lot more control over the contents of your items. It could be everything from all the messages on a certain topic (searching by label or the contents of a custom field) to the most recently active topic threads in your discussion group. If you can create a query for a set of messages, you should be able to generate an RSS document to syndicate them.

First, you'll need to create an advanced query page in your structure editor. As mentioned above a particular file name or extension is not required, but the .rss file extension is commonly used (for example, you might name this page "weblog.rss").

On the Basic tab make sure that the Template is set to the full page template created earlier, and the MIME Type is set to text/xml. (If you've created a folder as explained in the section on creating on folders and mime types -- and set these properties there -- then "[use parent folder template]" and "[use parent folder mime type]" are also acceptable settings.)

For the properties on the Query Options tab you'll want make sure that "Allow search arg overides?" is set to "No", and "Run Query on Load?" to "Yes". The others can be left as they are, although you may want to set "Show only Top Level Topics?" to "Yes" if, for example, you're plan to use a label-based query and would like to prevent replies from showing up. (This is useful because replies will have the same label as the message they're in reply to.)

The settings you specify on the query defaults will determine which messages in your conversation are included as items in the RSS document you're building. For a conversation that is mainly a single editor weblog, a simple query would set a Relative Date of "-1" for the Start Date and "+1" for the End Date, set the Posted By and Modified By fields to that of the weblog editor (probably yourself), and finally make sure that sorting is by Date and in Descending order. If you use a specific label or custom field to indicate a message that is posted to your weblog you may find it useful to also specify that on this tab.

An RSS document will not have a search form so the necessary set-up on the Form Settings tab is very simple: set the "Show Form?" option to "No" and ignore everything else.

On the Result Settings tab set "Items Per Page" to however many items you want in your RSS document. As noted earlier the Netscape spec technically limits an RSS document to 15 items, but many tools and services don't observe this limit (and Netscape's own service was shut down). Generally, setting this option to about 10 items appears to be common. The "Next" and "Previous" link text templates can be skipped because they will not be used (the macros to display them are not included in the other templates).

The following templates should be used for the rest of the items on this tab:

Page Content Template

<!--#queryResult-->

Query Result Template

<!--#queryResultBody-->

Message Template

<item>
	<title><!--#msgSubject--></title>
	<link><!--#msgURL--></link>
	<description><!--#msgBody clipLength="250"--></description>
	</item>

Using the clipLength attribute with the msgBody macro will limit the amount of the source message included in your RSS document and will also remove any HTML as required by the specification. The value of the length parameter can be adjusted to include more or less of the source message, but the specified limit is 500 characters.

You don't need to adjust anything on the Error Messages tab.

If you are interested Duncan Smeed has posted an excellent series of screenshots documenting the AQP-based RSS document he created for his Duncan's Jotter website.

Credits

Credit for the methods contained in this how-to go to an honourable group of Conversant power users. Steve Ivy started it off with his own how-to which used a regular query page because the AQP feature had not been released at that point. Brian Carnell followed up with a modified version of those instructions for the WeblogView page type. Duncan Smeed has also posted useful info on using RSS (his step-by-step screenshots are linked in the relevant sections above). And, as always, a multitude of thanks to Macrobyte Resources for creating the Conversant platform on which all of this is built.

Revision History

12 October 2001

• initial draft version published

Copyright

This document is copyright © 2001 Bradley D. Peters.