UWA Module: UWA/Data

API that provide a Cross-domain Ajax solution that allow you to fetch data through Ajax even if your app is not on the same domain than your request using UWA Proxy if required by the platforms that does not support Cross-domain Ajax calls.

Index

Members

UWA.Data.proxies
UWA.Data.request

Members

<static> UWA.Data.proxies :Object

UWA Proxy urls indexed by types.

Type

Object

Properties:

Name	Type	Description
`ajax`	String	Used to proxify a Ajax request
`resolve`	String	Used to get the final url of an url that make some redirect
`xml`	String	Used to proxify a XML request
`soap`	String	Used to proxify a SOAP request
`feed`	String	Used to proxify a Feed request to JSON Object
`icon`	String	Used to proxify an image to an ico
`richIcon`	String	Used to proxify an image to an richIcon
`spreadsheet`	String	Used to proxify a spreadsheet file to JSON Object

<static> UWA.Data.request

This method is used to get the content of an external data source even on another domain than current domain. It can be used to retrieve or set any kind of data: text-based, XML, JSON or a feed. The other Ajax methods (getText(), getXml(), getJson(), getFeed()) are all shortcut methods to specific uses of request(). This method is also the only way to perform HTTP POST request, as well as authenticated requests.

Specific proxy options:

You can pass specific options into an object that have the same name than the used proxy to configure proxy behavior, see Proxy Examples bellow for detailed usage.

Proxy	Options	Description	Default value
`xml`	xpath	apply Xpath query on xml proxy side	undefined
`soap`	methodName	SOAP method name	undefined
`soap`	methodParams	SOAP method parameters	undefined

Cache option:

By default the cache option is undefined, in this case it will use the Widget Server default cache duration that could depend the apps server config.

Cache value	Description
`undefined`	Use Widget Server default cache duration
`-1`	Never Cache response (also appends a query string parameter, "_=[TIMESTAMP]", to the URL)
`0`	Cache response forever
`n`	Cache response for n seconds

For debuging cache purpose the Widget server return 2 headers with integer value.

Header name	Description
`X-Cache-Level`	Widget Server cache level (0 not cached, > 0 cached)
`X-Cache-Lifetime`	Widget Server cache lifetime

Basic Examples:

Simple Example

 // Create a Callback
 MyOnComplete = function (text) {
   // your parsing code
 };
 MyOnCancel = function (text) {
   // your parsing code
 };

 // Launch request
 var myRequest = UWA.Data.request('http://example.org/api.php', {
   type: 'text'
   onComplete: MyOnComplete,
   onCancel: MyOnCancel
 });

 // Cancel request
 myRequest.cancel();

Xml Example

 // Create a Callback
 MyOnComplete = function (document) {
   // your parsing code
 }

 // Launch request
 var myRequest = UWA.Data.request('http://example.org/api.php?xml', {
   type: 'xml',  // Set response type to xml document
   cache: 3600,  // Set cache to one hour
   onComplete: MyOnComplete
 });

 // Cancel request
 myRequest.cancel();

Json Example

 // Create a Callback
 MyOnComplete = function (json) {
   // your parsing code
 }

 // Launch request
 var myRequest = UWA.Data.request('http://example.org/api.php?json', {
   type: 'json',
   onComplete: MyOnComplete
 });

 // Cancel request
 myRequest.cancel();

Proxy Examples:

XML with XPath filtering Example

 // Create a Callback
 MyOnComplete = function (document) {
   // your parsing code
 }

 // Launch request
 var myRequest = UWA.Data.request('http://example.org/api.php?xpath', {
   type: 'xml',                        // Set response type to xml document
   proxy: 'xml',                       // Force proxy usage
   xml: {
       xpath "/items/item[@name='item1']", // Apply XPath query on response (server side)
   },
   onComplete: MyOnComplete
 });

Original XML response

 <items title="titleAttribute">
     <item name="item1" foo="bar">item1TagValue</item>
     <item name="item2" foo="bar">item2TagValue</item>
     <item name="item3" foo="bar">item3TagValue</item>
     <item name="item4" foo="bar">item4TagValue</item>
     <label>label1TagValue</label>
     <label>label2TagValue</label>
     <title type="foo">titleTagValue</title>
 </items>

XML response after XPath filter

 <root>
     <item name="item1" foo="bar">item1TagValue</item>
 </root>

SOAP with JSON response Example

 // Create a Callback
 MyOnComplete = function (json) {
   // your parsing code
 }

 // Launch request
 var myRequest = UWA.Data.request('http://www.webservicex.net/stockquote.asmx?WSDL', {
   type: 'json',                        // Set response type to json
   proxy: 'soap',                       // Force proxy usage
   soap: {
       methodName "GetQuote",
       methodParams: {
           symbol: "AAPL"
       }
   },
   onComplete: MyOnComplete
 });

Original XML SOAP response (e.g using type xml)

 <?xml version="1.0" encoding="UTF-8"?>
 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
       <GetQuoteResponse xmlns="http://www.webserviceX.NET/">
          <GetQuoteResult>&lt;StockQuotes&gt;...&lt;/StockQuotes&gt;</GetQuoteResult>
       </GetQuoteResponse>
    </soap:Body>
 </soap:Envelope>

JSON response after XML conversion (e.g using type json)

 {
   "GetQuoteResult": "<StockQuotes>...</StockQuotes>"
 }

Methods

<static> UWA.Data.proxifyUrl(url, options) → {String}

Proxify an URL using UWA proxy.

Parameters

Name	Type	Description
`url`	String	url to proxify
`options`	String	some options from <request> options parameter

Returns

full url to proxy with proxified options (header, data) has parameter.

Type: String

<static> UWA.Data.getFeed(url, callback) → {Object}

Gets the content of a feed, in a JSON format.

In this example, the callback method is named "dataProcessor", and is used to parse the feed Object, which is contained in the 'feed' variable.

var dataProcessor = function (feed) {
 // your display code
}

UWA.Data.getFeed('http://feeds.feedburner.com/NetvibesDevBlog', dataProcessor);

Feed Object format:

// Following an example of response for a feed on "http://blog.example.org/feed"
{
   "url": "http://blog.example.org/feed",
   "type": "atom",                             // Could be "rss" or "atom"
   "version": "atom10",                        // Could be "rss2" or "atom10"
   "title": "Example.org News Feed"            // Feed title
   "link": "http://blog.example.org",          // Feed website
   "content": "Some Example.org News",         // Feed description
   "language": "en",                           // Feed language
   "author": "john doe",                       // Feed author
   "date": "Fri, 04 May 2012 10:35:47 +0200"   // Last Feed update
   "items": [                                  // Feed items/articles objects
       {
           "title": "Article One",                                 // Article title
           "description": "My nice article about example.org",     // Article description
           "link": "http://blog.example.org/post/1",               // Article link
           "date": "Thu, 03 May 2012 18:08:33 +0200",              // Article publishing date
           "authors": {                                            // Article authors
               "0": {
                   "name": "john doe"
               }
           },
           // Article raw content
           "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...."
       },
       ...
   ]
}

Parameters

Name	Type	Description
`url`	String	The URL of the feed data source
`callback`	Function	The callback method that will be triggered when the request is succesful This method must have one parameter to receive the feed (JSON format) returned by the request.

Returns

An object that contains the cancel method. If the request is successful, the callback onComplete is fired and receives the content as a parameter; If the request is aborted the callback onCancel is fired, else the onFailure or onTimeout methods are fired.

Type: Object

<static> UWA.Data.getXml(url, callback) → {Object}

This method is used to get the content of an external XML data source. It can be used to retrieve the content of a feed in XML format.

In this example, the callback method is named "dataProcessor", and is used to parse the XML tree, which is contained in the 'xml' variable.

var dataProcessor = function (xml) {
   // your parsing code
   var items = xml.getElementsByTagName('item');
}

var myRequest = UWA.Data.getXml('http://example.com/content.xml', dataProcessor);

Parameters

Name	Type	Description
`url`	String	the URL of the XML data source,
`callback`	Function	the callback method that will be fired when the request is succesful This method must have one parameter to receive the XML content returned by the request.

Returns

Type: Object

<static> UWA.Data.getText(url, callback) → {Object}

This method is used to get the content of an external data source. It can be used to retrieve any kind of content, as long as it is made of text.

In this example, the callback method is named "dataProcessor", and is used to test the text content, which is contained in the "data" variable.

var dataProcessor = function (data) {
   // your parsing code
   var isValid = data.contains('success');
};

var myRequest = UWA.Data.getText('http://example.com/content.txt', dataProcessor);

Parameters

Name	Type	Description
`url`	String	the URL of the data source,
`callback`	Function	the callback method that will be fired when the request is succesful This method must have one parameter to receive the text content returned by the request.

Returns

Type: Object

<static> UWA.Data.getJson(url, callback) → {Object}

This method is used to get the content of an external JSON data source. It can be used to retrieve any kind of JSON data.

var dataProcessor = function (json) { // your parsing code };

var myRequest = UWA.Data.getJson('http://example.com/json.php', dataProcessor); ```

Parameters

Name	Type	Description
`url`	String	the URL of the data source,
`callback`	Function	the callback method that will be fired when the request is succesful This method must have one parameter to receive the JSON content returned by the request.

Returns

Type: Object