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.
===== Text query =====
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("Message from the server:
" + text + "
");
}
widget.onLoad = function() {
YourWidgetName.dataInit();
}
=====JSON query=====
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(
"Message from " + json.from + ":
" +
"To: " + json.to + ":
" +
"" + json.message + "
"
);
}
widget.onLoad = function() {
YourWidgetName.dataInit();
}
===== XML query =====
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:
Hello UWA World!
Example.org
UWA user
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(
"Message from: " + from + "
" +
"To: " + prefix + " " + to + "
" +
"" + message + "
"
);
}
widget.onLoad = function() {
YourWidgetName.dataInit();
}
=====Feed query=====
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(
"" +
"The feed for '" + feed.title +
"' contains " + feed.items.length +
" entries." +
"
"
);
}
widget.onLoad = function() {
YourWidgetName.dataInit();
}
===== Advanced Ajax use with UWA.Data.request =====
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:
^ Setting ^ Options ^ Default option ^
| method | get, post (in lowercase!) | post |
| proxy | ajax, feed | ajax |
| type | json, xml, text, html | text |
| cache | (seconds of server caching) | undefined |
| onComplete | (choose your own method) | undefined |
| parameters | (POST parameters) | undefined |
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"
});
==== POST body and content-type ====
There are two other settings that might be of use to your projects:
^ Setting ^ Options ^
| postBody | (yours to choose) |
| requestHeaders | (yours to choose) |
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".