The UWA JavaScript framework provides developers with various methods for communicating with web-services using JavaScript/Ajax requests. These methods are easy to use, and specialized for different kind of data types.

Ajax requests are asynchronous by design: calling a method doesn't imply getting an immediate return value. This return value might take some time, depending on the server, the traffic, the bandwidth, etc. Therefore, you have to pass a callback function's name to the method. This callback method will process the data sent back by the web service, as soon as it arrives.

A generic use of AJAX with UWA would make use of the advanced UWA.Data.request method:

var YourWidgetName = {};
 
YourWidgetName.dataProcessor = function(response) {
  // do your data processing here
}
 
YourWidgetName.dataInit = function() {
  UWA.Data.request(
    'http://example.org/api.php', 
     { 
     method: 'get', 
     proxy: 'ajax', 
     type: 'xml', 
     cache: 3600,
     onComplete: YourWidgetName.dataProcessor
     }
  );
}
 
widget.onLoad = YourWidgetName.dataInit;
}

When returned by the web service, the data will be passed to the callback function's first argument (in the above example, .dataProcessor()'s only argument, which we call response).

The type of the data depends on the Ajax method used - or, if the developers uses the UWA.Data.request method, as seen above, the type will depend on the type parameter of the request. In the above example, we used the xml type.

The above example presents a generic, yet advanced use of UWA methods: you can and must control everything. In addition to UWA.Data.request(), UWA offers four easier, more specialized methods, optimized for various data types.

This is the simplest Ajax method, to be used when the web-service simply returns a text message - which may contain HTML code or specially formatted data, but will nevertheless be sent as a String. It's up to the developer to code methods to process that string correctly.

For instance, if the http://example.org/api.php service returns the following string of text:

Hello UWA World!

Here is a way of properly retrieving that string using the UWA.Data.getText() method:

var YourWidgetName = {};
 
YourWidgetName.dataInit = function() {
  UWA.Data.getText(
    'http://example.org/api.php',
    YourWidgetName.dataProcessor
  );
}
 
YourWidgetName.dataProcessor = function(text) {
  widget.setBody("<h1>Message from the server:</h1><p>" + text + "</p>");
}
 
widget.onLoad = function() {
  YourWidgetName.dataInit();
}

JSON is JavaScript's native data description format. If the web-service returns data using this format, UWA's UWA.Data.getJson() method allows you to handle it without annoyance, even if it's a complex data.

Here is a simple JSON code that a web-service might return:

{
  message: "Hello UWA World!",
  from: "Example.org",
  to: "UWA user"
}

This is how it could be handled using UWA:

var YourWidgetName = {};
 
YourWidgetName.dataInit = function() {
  UWA.Data.getJson(
    'http://example.org/api.php',
    YourWidgetName.dataProcessor
  );
}
 
YourWidgetName.dataProcessor = function(json) {
  widget.setBody(
    "<p>Message from " + json.from + ":</p>" +
    "<p>To: " + json.to + ":</p>" +
    "<p>" + json.message + "</p>"
  );
}
 
widget.onLoad = function() {
  YourWidgetName.dataInit();
}

XML is a very common standard data description language, used by most web-services to get and send data. It is the basis of most data exchange on the Web today.

The easiest way to process XML using JavaScript is through the browser's DOM methods. UWA lets developers retrieve XML data using the UWA.Data.getXml method.

Here is a simple XML code that a web-service might send back:

<example>
  <message>Hello UWA World!</message>
  <from>Example.org</from>
  <to prefix="Mr.">UWA user</to>
</example>

This is how it could be handled using UWA:

var YourWidgetName = {}
 
YourWidgetName.dataInit = function() {
  UWA.Data.getXml(
    'http://example.org/api.php',
    YourWidgetName.dataProcessor
  );
}
 
YourWidgetName.dataProcessor = function(xml) {
  var rootNode = xml.documentElement;
  var message = rootNode.getElementsByTagName('message')[0].firstChild.nodeValue;
  var from = rootNode.getElementsByTagName('from')[0].firstChild.nodeValue;
  var to = rootNode.getElementsByTagName('to')[0].firstChild.nodeValue;
  var prefix = rootNode.getElementsByTagName('to')[0].getAttribute('prefix');
  widget.setBody(
    "<p>Message from: " + from + "</p>" +
    "<p>To: " + prefix + " " + to + "</p>" +
    "<p>" + message + "</p>"
  );
}
 
widget.onLoad = function() {
  YourWidgetName.dataInit();
}

RSS and Atom feeds are becoming a common way of sharing not only regular news items, but also other recurring data. Because of the many available formats and versions in the wild, they might not be easy to process directly. UWA provides the UWA.Data.getFeed method, which facilitates the process of getting and parsing a feed, by turning it into the special JSON Feed Format.

Here's an example for processing entries from the Netvibes' blog:

var YourWidgetName = {};
 
YourWidgetName.dataInit = function() {
  UWA.Data.getFeed(
    'http://blog.netvibes.com/rss.php',
    YourWidgetName.dataProcessor
  );
}
 
YourWidgetName.dataProcessor = function(feed) {
  widget.setBody(
    "<p>" +
      "The feed for '" + feed.title +
      "' contains " + feed.items.length +
      " entries." +
    "</p>"
  );
}
 
widget.onLoad = function() {
  YourWidgetName.dataInit();
}

This method should be used if you want to finetune your Ajax request. Therefore, we advise you to only use it if the other methods (getFeed(), getXml(), getJson() or getText()) are not enough for you.

The method's first parameter is the URL of the data source.

The second parameter, named request, is a JSON-like object. It can take the following form:

{ method : 'get', proxy: 'ajax', type: 'xml', onComplete: callback }

…which makes the whole function call take this form:

UWA.Data.request(
  'http://example.org/api.php', 
   { 
   method: 'get', 
   proxy: 'ajax', 
   type: 'xml', 
   cache: 3600,
   onComplete: myCallbackMethod 
   });

Here are the available settings for the request object:

If needed, POST parameters are to be set using parameters, as a plain string. For instance:

   ...
   cache: 3600,
   onComplete: myCallbackMethod,
   parameters: "firstname=James&lastname=Bond&number=007"
   });
</script>

There are two other settings that might be of use to your projects:

For example, shoud you want to POST a JSON object, here's how you could do:

UWA.Data.request(
  'http://example.org/api.php', 
  { 
    'method': 'post', 
    'type': 'text', 
    'proxy': 'ajax',
    'onComplete': myCallbackMethod,
    'postBody': '{"version" : "1.1", "method" : "test", "params" : [1, 2, 3, 4, 5]}',
    'requestHeaders' : ['Content-Type', 'application/json']
  }); 

If you want to make this more readable, remember that you can use variables:

var thePostBody = '{"version" : "1.1", "method" : "test", "params" : [1, 2, 3, 4, 5]}';
var theReqHeaders = ['Content-Type', 'application/json'];
 
UWA.Data.request(
  'http://example.org/api.php', 
  { 
    'method': 'post', 
    'type': 'text', 
    'proxy': 'ajax',
    'onComplete': myCallbackMethod,
    'postBody': thePostBody,
    'requestHeaders' : theReqHeaders
  }); 

In order to POST XML data, the same solution should work, only with a different content-type, such as “text/xml”.