======How to widgetize a RSS feed?====== a.k.a, "How to turn a RSS feed into a UWA widget" or "How to build a RSS reader widget". {{example:example-feed.png|}} 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 [[examples:rssreader|RSSReader examples]], which you can already add to your Netvibes. A RSS reader widget cannot make use of Netvibes' full-screen RSS reader. This is only available for feeds directly added to Netvibes =====First step===== We advise you to start with our sample [[uwa_specification:uwa_skeleton|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 [[:examples|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. =====Building the preferences====== 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 "[[uwa:documentation:anatomy_of_a_uwa_widget|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.

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. =====Scripting it all===== 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 [[:uwa:documentation:json_feed_format|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 "[[uwa:documentation:javascript_framework|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 [[uwa:documentation:javascript_framework|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 [[uwa:documentation:json_feed_format|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);
}

=====Using a set list of URLs rather than URL textfield===== 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 [[:uwa:documentation:anatomy_of_a_uwa_widget#preference_tags|here]]. Here is an example code:

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