JERSS Project Documentation

Using the JERSS servlet

The JERSS servlet works by taking two parameters, and returning Javascript objects populated with information about the news headlines. The web author can then use Javascript and these populated objects to generate HTML that presents the headlines in whatever manner the author sees fit. This way the author has 100% control over the design of the presentation.

If you use the JERSS servlet to include at least one newsfeed in your web page, you must include the following script tag in the HEAD of your HTML document:

Replace [rss.js] with the URL of the rss.js file included in the JERSS package as it exists on your server. For example, if you store the rss.js file at http://www.yourserver.com/javascript/rss.js, you would replace [rss.js] with that URL.

To add a newsfeed to your web page, include the following tag in the HEAD of your HTML document (you should include one tag per channel you want to include - if you have three channels, you'll have three of these tags):

Replace [JERSS] with the URL of the JERSS servlet on your server. You'll see examples with the URL http://www.jayeckles.com/servlets/RSSViewerServlet. Don't use this URL - it will bog down my web server. You should use the URL of the servlet on your server; for instance, http://www.yourserver.com/path/to/RSSViewerServlet.
Replace [RSS] with the URL of the RSS newsfeed you want to include on your web page. For example, if you want to include the top stories feed from Moreover, you'd use the URL http://p.moreover.com/cgi-local/page?index_topstories%2Brss.
Replace [x] with a prefix you'd like to use to uniquely identify the variables associated with this particular newsfeed. This is optional and is useful if you want to include multiple newsfeeds on one web page. This parameter is optional, so if you're only using one newsfeed on a page, you can exclude it. For a top stories feed, you might use the prefix "top".

To create HTML out of the Javascript generated by the JERSS servlet, you'll need to write some Javascript of your own. Exactly how you do this is up to you, because it will be unique to the design of your website. However, there are some things to keep in mind:

Information about the RSS channel is stored in an object called [prefix]channel. So, if you use "top" as the prefix parameter passed to the JERSS servlet, the object would be called topchannel. If you exclude the value of the prefix parameter (or the parameter altogether), then the object would be called channel. If you included two newsfeeds and used the prefix "top" for one and "phl" for the other, then there would be two objects, one named topchannel and the other named phlchannel.
- Channel has several properties, all of which may not be populated - it depends on the data provided in the specific RSS file. The properties available are channel.title, description, link, editor, webmaster, copyright, and language.
Information about the items in an RSS channel is stored in an array of objects called [prefix]items. If you use "top" as the prefix, the array is called topitems. If the prefix is "phl", the array is called phlitems. If you exclude the prefix, the array is called items.
- Each object in the items array has three properties: items[i].title, description, and link.
The number of items in the channel is stored in a variable called [prefix]NumberOfItems. If you use "top" as the prefix, the variable is called topNumberOfItems. If you exclude the prefix, the variable is called NumberOfItems.

Here's an example of some very simple Javascript to produce some very simple HTML to display news headlines (it assumes the prefix "top" was used when including the channel):

For a complete example of an HTML document that brings together the concepts of including channels and writing HTML based on the Javascript objects and variables, please see the examples page.

A final note: There are many different versions of RSS, including 0.91, 0.92, 1.0, and various versions of a related format known as RDF. JERSS works with most 0.91, 1.0, and RDF files, but not 0.92 and some 1.0 or RDF files. Please test your JERSS-parsed newsfeed before you publish it to your live website.

If you have any questions or would like to contact me for any reason, please email me at j.eckles@computer.org.