====== JSON Feed format ====== 


UWA relies heavily on Ajax, and therefore exchange format such as XML and JSON are first class citizen in that environment. In order to trear all feed formats the same way, Netvibes 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 any type of feed 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 Schema =====

<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, Netvibes designed its own JSON Schema format, in order to document the JSON Feed format. Developers do not need to know its inner workings in order to retrieve content properly, but some 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>