Back to my page

Developer Blog

Using UWA’s JSON Feed format

UWA provides a fair number of built-in Ajax methods:

  • UWA.Data.getXml
    when you want to get XML data (including well-formed XHTML), and be able to parse it using XML’s DOM properties and methods (parentNode, childNodes, attributes, getElementsByTagName, etc.),
  • UWA.Data.getText
    when you just want to get the data in plain text, and maybe parse it using a regexp,
  • UWA.Data.getJson
    when you want to safely get JSON data, and parse it using regular JavaScript methods and properties.
  • UWA.Data.getFeed
    when you want to get a syndication feed (RSS, Atom, anything…).
  • UWA.Data.request
    when you want to go one step further (POST request with parameters, authentication, cache handling…)

Among these, one method is very useful for a given purpose, but sometimes misunderstood: UWA.Data.getFeed. This particular method has been built to ease the use of the many variations of syndication feeds into one handy format: our very own JSON Feed Format - which is rendered in JSON, as you might have guessed.

By rendering just any feed format into one easily-parseable one, UWA.Data.getFeed relieves developer from the pain of have to deal with the various versions of RSS, for instance.

The part that is not always understood, however, is the resulting JSON format - the one received in the first argument of the callback method. This format is not a tag-by-tag conversion of the Atom format, for instance, into JSON - no direct xml2json converter here. 

And therefore, developers who are used to deal with feeds do not find their usual tagnames. UWA’s JSON Feed Format does not have an entry tag for each post, nor a summary tag for a given post’s content, as in Atom ; likewise, it doesn’t use the respective RSS2.0’s equivalent item and description. Instead of that, any feed is rendered with posts available in an items array, and their summary/description tucked in a content variable.

For clarity’s sake, let’s make a small comparison table between a selection of equivalent values in RSS 2.0, Atom 1.0 and the JSON Feed Format (from top to bottom):

  • Getting to the first item:
    rss->channel->item[0]
    feed->entry[0]
    feed.items[0]
  • Current item’s title:
    item->title
    entry->title
    item.title
  • Current item’s content:
    item->description
    entry->summary
    item.content
  • Current item’s permalink:
    item->link (or item->guid with isPermalink attribute set to true)
    entry->link
    item.link
  • Current item’s date:
    item->pubDate
    entry->updated
    item.date
  • Current item’s enclosure:
    item->enclosure
    item->link (with rel="enclosure")
    item.enclosures[0].url

Because of this disparity, some developers have chosen to use UWA.Data.getXml in order to parse the data using XML’s DOM, and therefore be able to use tag names they know. It works ; however, we feel they’d be much better of using a data format that is built to be used with JavaScript.

Fortunately, the way to handle feeds using the JSON Feed format is documented. Here is the gist of it:

First, we instantiate the JS containing object, with an empty feed variable (that shall later contain the whole JSON data), and we trigger the UWA.Data.getFeed method directly from the widget.onLoad method…

MyWidget = {};
MyWidget.feed = null;

widget.onLoad = function() {
  UWA.Data.getFeed(
    'http://feeds.feedburner.com/NetvibesDevNetBlog'),
    MyWidget.display);
}

…and then, the heart of it all, where we parse the JSON Feed Format: 

MyWidget.display = function(feed) {
  if (feed) MyWidget.feed = feed;

  var feedList = widget.createElement('ul');
  feedList.className = 'nv-feedList';

  for(var i=0; i < MyWidget.feed.items.length; i++) {
    var item = MyWidget.feed.items[i];
    var li = widget.createElement('li');

    var a = widget.createElement('a');
    a.href = item.link;
    a.innerHTML = item.title;
    a.title = item.content.stripTags().truncate(255)

    li.appendChild(a);
    feedList.appendChild(li);
  }
  widget.setBody(feedList);
}

(notice that we use the FeedList template, simply by the nv-feedList class-name)

As you can see, it’s much easier to parse feed data using regular JavaScript code, than applying the tedious and longish XML DOM methods. Have a go at it, and find imaginative ways to use feeds!

This entry was posted on Friday, April 11th, 2008 at 5:21 pm and is filed under Articles, Tutorials. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

Leave a Reply