Mittwoch, Juli 06, 2005

AJAX Actions

The fundamental parts of an AJAX engine that handle all the asynchrony calling of the server-side functionality using JavaScript and the XMLHTTP object are available using the WebService proxies. To make realization easier some more layering is needed above this: AJAX Actions.

2 examples of AJAX actions are already published on the examples Website at

The actual code to implement an AJAX action is located in the two files CalcFactorsAJAX.htm and OrteLookup.htm. Each sample consists of only some lines of code. The reminding work is covered by the implementation of the engine in the file ajax.js.

As you can see in these samples the logical steps of the actions are written in the source code step by step as they will be executed even if there are timers and callback methods used to implement it behind the scene.

This makes it easy to follow the idea of each action.

The AJAX engine layers upon the WebService proxies shown before.

Every action on the page is described with the assistance of an object that holds all information together. The properties of this object are:

prepare(): This property defines a function that is used directly before sending the SOAP of package to the server. This function has to return the data that is used as the argument of the call to the server. If this function is not defined then a server-side method without parameters is called.

call(): This property refers to a function that was generated by the proxy generator to a WebService.

finish(): This property defines a function that will retrieve the result of the call. This property may be zero.

onException(): This property defines a function that is called in the case of an exception. This property may be zero.

delay: This property defines the time in milliseconds how long the call should be delayed. This is useful together with events that are triggered very often and in a fast order. The default value of 0 deactivates this functionality and the action starts immediately.

timeout: This property defines the time in seconds how long the call to the server can last before it is canceled on the client. When this time runs off without an answer from the server the http connection is closed. The default value of 0 deactivates this functionality.

A timeout of more than approx. 60 seconds does not work well because http requests can be terminated by the network layer before this time.

With some additional flags you can specify how pending actions are handled.

queueClear: This property can be set to true to specify that the queue with the pending actions is cleared before the new action is entered. An already running action will not be stopped. The default value is false.

queueTop : This property can be set to true to specify that the action is entered into the queue in front of all other pending actions. The default value is false.

queueMultiple: This property can be set to true to specify that an action can be queue more than once. The default value is false.

// declare an AJAX action
var action1 = {
  prepare: function() { return (document.getElementById("inputField").value); },
  call: proxies.CalcService.CalcPrimeFactors,
  finish: function (p) { document.getElementById("outputField").value = p; },
  onException: alertException
} // action1

In the samples you can see that it is not necessary to write functions before assembling them into the action object. The implementation of a function is also possible using inline code.

Important Note: The last property of a definition of a JavaScript object MUST NOT have a trailing comma. The otherwise quite tolerant Microsoft Internet Explorer complains of this error during the Firefox tolerates this. I lost some hours not seeing a comma like this.

Keine Kommentare: