======How to widgetize a RSS feed?====== a.k.a, "How to turn a RSS feed into a UWA widget". {{example:example-feed.png|}} One of the primary use of a widget it 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. =====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 MUST 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 abide is to fill-in the correct metadata. Their purpose is to describe the widget itself. Read about them in "[[uwa_specification:content_of_the_xhtml_file|Content of the XHTML file]]". You have first to define what will be the preference available to the use. Each of them must have its own ''preference'' tag. For the purpose of our simple RSS Reader, we will 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, but will not be avalaible to the users. =====Scripting it all===== The gist of your widget resides in your JavaScript code. It has to download the feed residing at the URL (set by the user in the ''preference'' tag) as soon as the widget is loaded, parse the obtained [[:uwa_specification:uwa_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. 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_specification:using_javascript_and_ajax|Using JavaScript and Ajax in a UWA widget]]" section.


var BasicRSSReader = {}

BasicRSSReader.feed = false;

BasicRSSReader.display = function(feed) {
  // display code
}

The ''display'' will be called at launch time, and everytime the URL preference is updated. Both are handled by the ''widget.onLoad()'' method, from the ''widget'' object. That object, specific to UWA, is described in [[uwa_specification:using_javascript_and_ajax|this section]].


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

The ''widget.getValue()'' method is charge of getting the content of the URL ''preference'' tag. ''UWA.Data.getFeed()'' gets the feed located at the URL, builds [[uwa_specification:uwa_json_feed_format|a JSON representation]] of it, then sends it to the widget's ''display()'' method. ''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) {
  if (feed) BasicRSSReader.feed = feed;
    
  // get the number of items to display
  widget.preferences[1].max = BasicRSSReader.feed.items.length;

  // create the 'ul' element, applying it the CSS class 'nv-feedList'  
  var feedList = widget.createElement('ul');

  // your 'ul' element MUST make use of the 'nv-feedList' class
  // to ensure your widget uses the UWA UI library
  feedList.className = 'nv-feedList';

  // number of parsed items
  var j = 0;

  // 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');

    // create and fill the 'a' element of the item with the item's link
    var a = widget.createElement('a');
    a.href = item.link;

    // fill the 'a' element with the item's title
    var displayTitle = item.title;
    a.innerHTML = displayTitle;

    // 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;

    // set a tooltip on the 'a' element, with the item's content
    a.onmouseover = function() {
      UWA.Utils.setTooltip(this, this.content, 250);
    }

    // finally 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 the needed items have been parsed,
  // send the main 'ul' element to the HTML body tag
  widget.setBody(feedList);
}

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

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