Using the web service proxy functions directly from JavaScript code is one
option for building AJAX enabled web pages. With this approach you have allthe flexibility and power with data types and multiple parameters that you
might need.
On the other side you will have to write a lot of JavaScript code for each
scenario that you have to implement. AJAX actions will bring you another
layer of abstraction that reduces a lot of the complexity of AJAX by reducing
the amount of code.
Using the AJAX Engine is done by defining AJAX Actions that are used on
the loaded page. Here is a simple sample:
// declare an AJAX action
var action1 = {
delay: 200,
prepare: function() {
return (document.getElementById("inputField").value);
}, // prepare
call: proxies.CalcService.CalcPrimeFactors,
finish: function (p) {
document.getElementById("outputField").value = p;
}, // finish
onException: alertException
} // action1
You can see that the logical steps of an action 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. It is possible to write inline JavaScript code as well
as linking to existing available functions.
Declaring this object is easy when using the JSON syntax extended with
some functions for describing complex JavaScript objects.
AJAX Action Reference
Every action on the page is described with the assistance of an object that
holds all information together. The properties of this object are:
action.prepare(option)
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.
The option that was passed to the ajax.Start function is also available in the
prepare function as a parameter.
action.call()
This property refers to a function that was generated by the proxy generator to
a WebService.
action.finish(option)
This property defines a function that will retrieve the result of the call. This
property may be zero.
JSON stays for JavaScript Object
Notation and can be used to build
complex objects at runtime.
It’s not a class definition mechanism!
The option that was passed to the ajax.Start function is also available in the
prepare function as a parameter.
action.onException(ex, option)
This property defines a function that is called in the case of an exception. This
property may be zero.
The option that was passed to the ajax.Start function is also available in the
prepare function as a parameter.
action.delay : [msec]
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.
action.timeout : [sec]
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.
action.queueClear : [bool]
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.
action.queueTop : [bool]
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.
action.queueMultiple : [bool]
This property can be set to true to specify that an action can be queue more
than once. The default value is false.
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.
Starting an AJAX Action
ajax.Start(action, option)
By calling the Start function of the global ajax object a defined action will be
started.
With the option parameter it is possible to define an option for a specific
execution that will be passed to various functions that are defined through the
action definition. This value is stored into the queue of the AJAX engine
together with the fist parameter specifying the action.
When the prepare and finish methods are executed as well on handling en
exception, this value is passed as an additional parameter. By using this value
it is possible to store a context of an action. That may be for example a HTML
object that started the action. Because all methods have access to it, it is now
possible to use the same action definition for multiple fields, forms or other
situations. Without this parameter it was necessary to implement the direct
access to the HTML objects inside the prepare and finish methods.
ajax.Cancel()
This method cancels the execution of the currently running action. If a timeout
value is specified in the action options this method is called automatically.
ajax.CancelAll()
This method cancels the execution of the currently running and all the
pending actions.
Handling Exceptions
Also in AJAX architectures failures in the communication and in the
execution may raise errors. Fortunately when using a WebServices based
framework these cases are also defines in the SOAP communication protocol.
The answer to a call to a WebService in the SOAP format will under normal
conditions return the result of the method:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<CalcPrimeFactorsResponse xmlns="http://www.mathertel.de/CalcFactorsService/">
<CalcPrimeFactorsResult>2 2</CalcPrimeFactorsResult>
</CalcPrimeFactorsResponse>
</soap:Body>
</soap:Envelope>
In the case of an error the information about the failure of the server-side
execution will be passed back to the client.
In the simplest case this information is shown to the user but also other
reactions may be appropriate like reloading the whole page.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Server was unable to process request. --->
Input string was not in a correct format.</faultstring>
<detail />
</soap:Fault>
</soap:Body>
</soap:Envelope>
The client-side implementation allows the handling of the exceptions that
occur at the level of the WebService proxies an on the level of the AJAX
Actions.
In both cases there is an onException event available and a specialized
method handling these exceptions can be plugged in. This method gets passed
the thrown exception as a parameter and can organize the further functionality
of the page.
There is usable method defined in ajax.js that can be used for showing
exceptions:
proxies.alertException(ex):
This method shows the exception object in a readable format using an alert
box. This method can be used in proxies.service.method.onException as well
as in action.onException.
Tags:
JavaScript