a.k.a, “How to turn a RSS feed into a UWA widget” or “How to build a RSS reader widget”.

One of the primary use of a widget is to provide users with an easy access to your data. Many websites rely on RSS in order to provide their data. If this is your case, it is in your best interest to provide your own widgetization of your RSS feed. This is how you do it.

This is a simplified version the RSSReader examples, which you can already add to your Netvibes.

We advise you to start with our sample UWA skeleton. It contains all the starting code you will need, upon which you can build your own code and content. Then, you can test and dissect our existing UWA examples.

Remember: to use the proper UWA template, your feed should be displayed in a HTML list (ul/li), where the ul element MUST use the nv-feedList CSS class.

When building your widget, the first rule to follow is to fill-in the correct metadata. Their purpose is to describe the widget itself. Read about them in ”Anatomy of a UWA widget”.

You have first to define what will be the preferences available to the user. Each of them must have its own preference tag. For the purpose of our simple RSS Reader, we will only have two preferences: the feed URL, and the number of displayed items.

<widget:preferences>
  <preference name="url" type="text" label="URL" 
    defaultValue="http://feeds.feedburner.com/NetvibesDevBlog" />
  <preference name="limit" type="range" label="Number of items to display" 
    defaultValue="10" step="1" min="1" max="25" />
</widget:preferences>

If you don't want your users to change the URL, you only have to change the first preference tag's type to hidden: the preference will still exist and be available to the code, but will not be avalaible to the users.

The gist of your widget resides in its JavaScript code. It has to download the feed from a URL (set by the user in the preference tag) as soon as the widget is loaded, parse the obtained JSON representation of the feed, and retrieve the needed data from it, then display as many items as the appropriate preference tag specifies.

In our example, the downloaded feed will be stored in a local feed variable. We set it to false at first, waiting to be filled-in by the UWA.Data.getFeed() method.

The display method will simply be called display, and will take feed as its only argument.

All the informatin about using JavaScript and the DOM is available in the ”JavaScript Framework” section.

// Global JavaScript object,
// which will contain all of the widget's
// functions and variables.
var BasicRSSReader = {};
 
// Example of setting a global variable
BasicRSSReader.feed = false;
 
// Example of setting a global function/method
BasicRSSReader.display = function(feed) {
  // display code
}

We want the display method to be called at launch time, and everytime the “URL” preference is updated. Both loading and refreshing are handled by the widget.onLoad() method by default. That object, specific to UWA, is described in this section.

widget.onLoad = function() {
  UWA.Data.getFeed(widget.getValue('url'), BasicRSSReader.display);   
}

The widget.getValue() method is in charge of getting the content of the “URL” preference tag, while the UWA.Data.getFeed() method fetches the feed located at the given URL, builds a JSON representation of it, and finally sends it to the callback method, which is BasicRSSReader.display() - it is specified without the final ().

display() is then in charge of dealing with the rest of the widget: get the number of items to display, and loop through the items list. Each displayed item has to generate its own markup, using JavaScript methods.

Here is how it's done:

BasicRSSReader.display = function(feed) {
  // we check if 'feed' has a value, and assign it to a global variable
  if (feed) BasicRSSReader.feed = feed;
 
  // we get the number of items to display
  widget.preferences[1].max = BasicRSSReader.feed.items.length;
 
  // we create the 'ul' element, applying it the CSS class 'nv-feedList'  
  var feedList = widget.createElement('ul');
 
  // the 'ul' element MUST make use of the 'nv-feedList' class
  // to ensure that the widget uses the UWA UI library
  feedList.className = 'nv-feedList';
 
  // number of parsed items
  var j = 0;
 
  // we loop through the downloaded items
  for(var i=0; i < BasicRSSReader.feed.items.length; i++) {
    // if the limit is reached, stop looping
    if (j >= widget.getValue('limit')) break;
 
    // for each item, create the 'li' element
    var item = BasicRSSReader.feed.items[i];
    var li = widget.createElement('li');
 
    // we create and fill the 'a' element of the item with the item's link
    var a = widget.createElement('a');
    a.href = item.link;
 
    // we fill the 'a' element with the item's title
    var displayTitle = item.title;
    a.innerHTML = displayTitle;
 
    // we build the title from the 255 first characters of the content
    // remove the content's HTML tags along the way
    var title = item.content.stripTags().truncate(255);
    a.title = title;
 
    // we add a tooltip on the 'a' element, with the item's content
    a.onmouseover = function() {
      UWA.Utils.setTooltip(this, this.content, 250);
    }
 
    // finally, we append the 'a' element we just filled, into the 'li' element
    li.appendChild(a);
 
    // ...and append the 'li' element to the main 'ul' element        
    feedList.appendChild(li); 
    j++;
  }
 
  // once all the required items have been parsed,
  // we send the main 'ul' element to the HTML body tag
  widget.setBody(feedList);
}

The RSS reader presented here only works for one feed at a time, which you have to fill by hand if you want to target a new feed. Through the list preference tag, you can provide the user with a list of URLs.

Read about the list preference here.

Here is an example code:

<widget:preferences>
  <preference name="url" type="list" label="URL"
  defaultValue="http://example.com/feed1" >
    <option label="Feed 1" value="http://example.com/feed1" />
    <option label="Feed 2" value="http://example.com/feed2" /> 
    <option label="Feed 3" value="http://example.com/feed3" />
  </preference>
  <preference name="limit" type="range" label="Number of items to display" 
    defaultValue="10" step="1" min="1" max="25" />
  <preference name="search" type="hidden" defaultValue="" />
</widget:preferences>

Please note that you must provide a defaultValue - using selected=“selected” will not work.