www.webOShelp.net

We covered some of the possibilities for Ajax in webOS applications in our first webOS and AJAX tutorial. Mitch Allen also covers this topic at the end of chapter 6 of Palm webOS. This article revisits Ajax usage in webOS from Palm's perspective.

First of all, Palm explains that there are multiple ways to implement AJAX in webOS applications:

• Using the Ajax class functions of the Prototype JavaScript framework.
  • Use this method for simple functions that encapsulate the lifecycle of an XMLHttpRequest object and handlers.
  • Works with simple XML, JSON or text-based web services.
• Using the native JavaScript XMLHttpRequest object directly
  • Use this method if your data protocols are SOAP based or anything other than the data types listed above.

Palm covers only the Prototype methods in this chapter. To learn about using the native JavaScript XMLHttpRequest object for AJAX transfers, see our other article AJAX and webOS.

Ajax.Request

The Ajax.Request object manages the complete Ajax lifecycle and allows you to define callbacks at various points to insert processing within the lifecycle where your application requires it. Ajax requests are asynchronous by default, but this behavior can be overridden if necessary. (Synchronous transfers with XMLHttpRequest (the native JavaScript JavaScript object) are currently disabled in webOS. Currently, "the UI and applications run as part of a common process", so Palm says it's "necessary to preserve UI responsiveness".)

Here's an example of Ajax.Request in use:

 var request = new Ajax.Request("https://www.weboshelp.net", {
   method: 'get',
   evalJSON: 'false',
   onSuccess: this.feedRequestSuccess.bind(this),
   onFailure: this.feedRequestFailure.bind(this)
 });

The only way to generate an Ajax request is to use the new operator as demonstrated above. In addition to get requests, you can also make post requests and define other callbacks as defined below:

Callback	Lifecycle Stage
onCreate	Created
onUninitialized	Created
onLoading	Initialized
onLoaded	Request Sent
onInteractive	Response being received (per packet)
on###, onSuccess, onFailure	Response Received
onComplete	Response Received

Notes:

• onCreate is not available as a property of Ajax.Request; it is available only to Responders.
• ### represents an HTTP status code (e.g. 403, 404, etc.)
• If on### is specified, a success HTTP status code will cause on### to be invoked instead of onSuccess. A failure HTTP status code will cause on### to be invoked instead of onFailure.
• onComplete is called only after onSuccess or onFailure (if specified) is called.

Ajax.Response

The Ajax.Response object is passed as the first argument to all callbacks. Here is the full list of properties for the Ajax.Response object:

Property	Type	Description
readyState	Integer	Current lifecycle state: 0 = Uninitialized, 1 = Initialized, 2 = Request Sent, 3 = Interactive, 4 = Complete
status	Integer	HTTP status code for the request
statusText	String	HTTP status text corresponding to the code
responseText	String	Text body of the response
responseXML	XML or Document	If content type is application/xml, then XML body of the response; null otherwise
responseJSON	Object	If content type is application/json, then JSON body of the response; null otherwise
headerJSON	Object	Sometimes JSON is returned in the X-JSON header instead of response text; if not this property is null
request	Object	Original request object
transport	Object	Actual XMLHttpRequest object

Palm recommends JSON as an excellent data interchange format for use with Ajax. Usage of JSON in webOS applications will be covered in a future tutorial.

Ajax Responders

Ajax.Responders allows you to set up responders to handle common Ajax callbacks rather than setting up a callback with each request. Palm recommends their use in error handlers and activity indicators.

Click here for an example of setting up Ajax Responders.

This example shows the use of responders to manage a spinner and to handle Ajax request failures:

Ajax.Responders.register({
 onCreate: function()  {
 spinnerModel.value = true;
 this.controller.modelChanged(spinnerModel, this);
 },

 onSuccess: function(response)  {
   spinnerModel.value = false;
   this.controller.modelChanged(spinnerModel, this);
   this.processUpdate(response)
   },

 onFailure: function(response) {
   this.spinnerModel.value = false;
   this.controller.modelChanged(spinnerModel, this);
   var status = response.status;
   Mojo.Log.info("........","Invalid URL (Status ", status, " returned).");
   Mojo.Controller.errorDialog("Invalid feed - http failure ("+status+")");
   }
 });

Ajax.Updater and Ajax Periodial Updater

Ajax.Updater and Ajax.PeriodicalUpdater make an Ajax request and update the contents of a specified DOM container or element with the response.

Ajax.Updater performs the update once and Ajax.PeriodicalUpdater performs the request at some specified interval with a decay option that can extends the interval automatically if the Ajax response is unchanged.

Palm has not yet provided an example of these functions.

That about does it for Palm's Ajax coverage, at least in the Palm webOS book. We'll probably see additional examples later on in the book or on Palm's developer portal once it's made public. It's pretty evident, though, that Palm recommends the use of the Prototype Ajax methods over usage of the bare Javascript XMLHttpRequest object. Check out our previous article, webOS and the Prototype Javascript Framework, for some additional Prototype resources.

In our next (not quite) daily tutorial series, we'll check out Application Services! Grab the www.webOShelp.net RSS feed to stay in the know.

As mentioned earlier, much of the information in this article was presented in Chapter 6 of Palm webOS by Mitch Allen.