======UWA JSON feed format======

The Universal Widget API makes heavy use of [[:uwa_specification:ajax_examples|Ajax]], and therefore exchange format such as XML and JSON are first class citizen in the Netvibes environment. To that end, we designed a specific JSON representation format for feeds.

While you may be familiar with XML, JSON might warrant some presentation. JSON stands for JavaScript Object Notation, and is a fast, lightweight data-exchange format. It is very popular with web-based services, and is easy to use in a browser-based environment: because it uses a known JavaScript dialect, the vast majority of browser can parse it out of the box.

Netvibes provides a way to retrieve your data using JSON instead of XML. Through the JavaScript method ''UWA.Data.getFeed(url, callback)'', you are able to retrieve a RSS or XML feed, and get a JSON representation of it.

=====Sample usage=====

Here a sample of a JSON feed representation obtained using ''UWA.Data.getFeed()''.

<code javascript>
// json989533 is the name of the internal JavaScript object 
// it is unique to the current representation
json989533 = 
 {
 "type": "rss",
 "version": "rss10",
 "nvFeed": 1, 
 "htmlUrl": "http://blog.netvibes.com/", 
 "title": "Netvibes Blog",
 "content": "Netvibes.com development blog"
 "items":
  [
   {
    // the id is generated from the post URL 
    "id": "httpblognetvibescom20060628netvibesnewfeaturespreview", 
    "title": "Netvibes new features review", 
    "link": "http:\/\/blog.netvibes.com\/?2006\/06\/28\/netvibes-new-features-preview",
    "content": "<p>A post with an enclosure<\/p>", 
    "date": "Jun 28, 2006 11:18:31 GMT", 
    "enclosures": 
     [ 
      { 
      "type": "image/png", 
      "url": "http://blog.netvibes.com/images/20060531-launch/account-change.png"
      } 
     ] 
   },
   {
    "id": "httpblognetvibescom20060624netvibesintroduces", 
    "title": "Netvibes introduce Keyboard control",
    "link": "http:\/\/blog.netvibes.com\/?2006\/06\/24\/netvibes-introduces",
    "content": "<p>This is our HTML content<\/p>", 
    "date": "Jun 24, 2006 11:18:31 GMT"
   }
  ]
}
</code>

The ''UWA.Data.getFeed(url, callback)'' method is used in the following way:

<code javascript>
var MyWidgetName = {}

MyWidgetName.display = function(feed) {
  widget.setBody(
    "<p>" +
      "The feed for '" + feed.title +
      "' contains " + feed.items.length +
      " entries." +
    "</p>"
  );
}

// The following code will fire when the widget is loaded
widget.onLoad = function() {
  // widget.getValue('url') : the value for the preference tag named 'url'
  // MyWidgetName.display   : the function fired when the request is successful
  UWA.Data.getFeed(widget.getValue('url'), MyWidgetName.display);   
}
</code>

=====The JSON feed format=====

<note>
This section is reserved for the curious and adventurous among you.
</note>

Using ''UWA.Data.getFeed()'' will return a JSON object, built using a specific format. 

For this purpose, we designed our own JSON Schema format, in order to document our JSON format. You don't need to know its inner workings in order to retrieve your content properly, but some of you might want to delve a little deeper into this format.

<code javascript>
j-feed  =
{
 "name": "j-feed",
 "description" : "A format to describe Feeds",
 "url": "http://example.org/schemas/j-feed",
 "type": "object",
 "members":
 [
    { "name": "nvFeed" },
    { "name": "htmlUrl" },
    { "name": "title" },
    { "name": "description" },
    {
      "name": "items",
      "type": "array",
      "members": j-feed-item
    }
 ]
}

j-feed-item =
{
 "name": "j-feed-item",
 "description": "A format to describe Feed items",
 "url": "http://example.org/schemas/j-feed-item",
 "type": "object",
 "members":
 [
    { "name": "id" },
    { "name": "title" },
    { "name": "content" },
    { "name": "author" },
    { "name": "date" },
    {
      "name": "enclosures",
      "type": "array",
      "members": j-feed-enclosure
    }
 ]
}

j-feed-enclosure =
{
 "name": "j-feed-enclosure",
 "description": "A format to describe Feed enclosures",
 "url": "http://example.org/schemas/j-feed-enclosure",
 "type": "object",
 "members":
 [
    { "name": "url" },
    { "name": "type" }
 ]
}
</code>

Continue to  [[:uwa_specification:uwa_skeleton|a sample UWA skeleton]]...