O4W and RSS

RSS (“Really Simple Syndication”) is a method for “publishing” information on the web, usually of frequently-updated data. O4W allows you to create one or more RSS 2.0 “feeds” (also called “channels”) which you can update; visitors to your web page can choose to subscribe to one or more of these feeds, and then software on their computer (called an “RSS feed reader”) will update them whenever the data in the feed has been updated.

To display a link or an image (or both) that allows the user to subscribe to your feed, you can use the O4WRSSPublish API. This will both display the subscription link and allow you to define, inside O4W, the parameters of the feed. For example, on your main page you might have the following code:

                * put up the 'publish' link

                O4WRSSPublish("bugtrack", "Subscribe to the bug tracker", "", "Revelation Software Bug Tracker", "Openinsight Bug tracker", "http://www.revelation.com")

This will display a link and the default RSS image at the current location, and (if not already defined) store the overall information for the “bugtrack” feed. The parameters for the O4WRSSPublish API call are:

Subroutine O4WRSSPublish(FeedName, subsText, imgURL, FeedParams, title, desc, url, subrName,  maxcnt, boverwriteflag)

Where FeedName is the name of the feed you want to allow users to subscribe to. For the display of the RSS subscription link, subsText is the optional text to show in a link, imgURL is the optional url to show in a link, and feedParams is the optional additional information you wish to provide to the link that is used for retrieving the RSS data. Note that the feedParams value can be anything desired to uniquely identify the feed; for example, feedParams might contain an encoded value to indicate which user has requested the feed, or it might contain the type of information that should be retrieve (such as “FORM” or “REPORT”). You must specify at least one of the subsText, imgURL, or feedParams parameters for the link to be displayed.

For the definition of the feed, title is the title text that describes this feed, desc is the description of the feed, url is the overall url to your site that generates this feed, subrname is the optional name of a stored procedure to call to build and/or “filter” the feed the results, and maxcnt is the maximum number of data items to display in the feed (default is 15). The definition of the feed will only be written the first time the O4WRSSPublish call is made for a particular feedname; if you wish to change the values of the feed definition, you can set the bOverwriteFlag to “1”. If you only wish to define the feed, and not actually display the link, leave the subsText, imgURL, and feedParams values empty.

To completely delete a feed definition, call O4WRSSPublish with just the feedname:

O4WRSSPublish(“bugtrack”)

Once the feed has been defined, you can call O4WRSSPublish on all pages where you want to display the RSS feed link; alternatively, you can manually embed the link in the HTML template that you use on multiple pages of your site. Where you wish the RSS feed link to go, add in the following HTML:

<a href=”O4W_RSS?feedName=feedname&feedParams=params”>Subscription_text</a>

Where feedName is the name of the feed, params is the optional feedParams value (which can be omitted if no feedParams are required), and subscription_text is whatever text you want to display for the RSS feed link; for example,

<a href=”O4W_RSS?feedName=bugtrack”>Subscribe to the bug tracker</a>

To update the feed data, you can call O4WRSSData; for example:

                * also update the 'contents' of our RSS feed

                O4WRSSData("bugtrack", “Issue ":issueNum, "Bug issue number ”:issueNum:” updated”, "http:www.revelation.com/o4w/oecgi4.exe/O4W_BUGTRACK?ISSUE=”:issueNum")

This will add the specified information to the list of items that the “bugtrack” feed will list. When users look at their “feed reader” for the “bugtrack” feed, they will see this item and they can click on the link to bring them to the specific URL. The API for O4WRSSData is:

Subroutine O4WRSSData(FeedName, title, description, url, changeDate, GUID, extraFieldNames, extraFieldValues)

Where feedName is the name of the previously-defined feed, title is the title of this particular feed item, description is a description of this particular feed item, url is the url to click to in order to get to this particular feed item, changeDate is an optional internal date to record when this feed item was created, GUID is an optional unique identifier that RSS readers can use to identify when a feed item is unique, and extraFieldNames and extraFieldValues are @SVM-associated fields containing other optional RSS data fields and values that you might wish to provide.

When a user clicks on the “subscribe” link, or an RSS feed reader refreshes its list of data items from your feed, the O4W provided routine O4W_RSS will be invoked. This routine will obtain the feed name and additional feed parameters from the browser or feed reader and generate the list of data items available for that feed. Because O4W dynamically generates the required XML list of data in the O4W_RSS procedure, you can actually dynamically create or modify the list of data items returned by asking O4W to call a user-defined stored procedure (the name of the stored procedure to use was specified when the feed was first defined). The user-defined procedure must have 3 parameters, for example:

SUBROUTINE FILTERMYFEED(FEEDNAME, FEEDPARAMS, CURRENTLIST)

The name of the feed, the “feedparams” defined in the feed, and the current list (built through calls to O4WRSSData) will be passed to the subroutine; the subroutine may add, remove, or otherwise change the third parameter (“CURRENTLIST”). When the stored procedure returns, O4W_RSS will use the modified contents of that third parameter to build the list of data; thus it is even possible to dynamically build the list of feed data from scratch, and skip the use of O4WRSSData, entirely. Note that the “feedparams” value can be anything desired to uniquely identify the feed; for example, the feedparams might contain an encoded value to indicate which user has requested the feed, so that the stored procedure can filter results based on that user, or it might contain the type of information that should be retrieve (such as “FORM” or “REPORT”) so that the stored procedure can limit the results to just that type of data.

The fields of the currentList record that are used by O4W_RSS (and thus which the user-defined stored procedure may modify, delete, or add to) to create the list of data are:

1. Overall title for this feed

2. Description for this feed

3. URL for the web page for the overall feed
 

5. Maximum number of data items to return


10. Changed date (in internal format)  ]

11. Title of this particular data item ]

12. Description of this data item      ]

13. URL for retrieving this item       ]

14. GUID for this item                 ]

15. Add’l RSS field names     \        ]

16. Add’l RSS field data      \        ]

Where fields 10-16 are @VM delimited multivalue fields associated together, and fields 15 and 16 are @SVM delimited and associated together.