The UWA provides various methods for communicating with web services using JavaScript/AJAX. These methods are easy to use, and specialized for different kind of data types. Here are some examples to use them.

Please note: AJAX queries are not initially working if you use the widget in standalone mode. It's a limitation of JavaScript, for safety reasons. You should setup a proxy application on your own server to make it possible (see how in the FAQ).

AJAX queries in UWA are asynchronous: 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 UWA.Data.request method:

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

When returned by the web service, the data will be passed to the callback functions's first parameter.

The type of the data depends on the AJAX method you used - or, if you used the UWA.Data.request method, as seen above, the type will depend on the type parameter of your query. In the above example, we used the xml type, for instance.

The above example is a generic, yet advanced use of UWA methods: you can and must control everything. UWA offers more specialized methods, optimized for the various available data types.

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

Let's say the service you want to use sends back 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 sends you data using this format, UWA allows you to handle it without annoyance, even if it's a complex data, through the UWA.Data.getJson method.

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

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

This is how you could handle it 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 let's you retrieve XML data using its 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 you could handle it 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 object. It takes this form, for a XML request:

{ 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>

Continue to our JSON Feed representation…