Ajax

Table of Contents

Ajax (<ace:ajax>)

Since 3.0

The ACE components allow developers to customize the ajax behaviour of various supported synthetic events. This is done by nesting an <ace:ajax /> tag inside the component that one wishes to customize, and as of 4.0, it is possible to nest components inside this tag to add ajax behaviours to them.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Many of the attributes of the <ace:ajax /> tag are similar to those of the <f:ajax /> tag. They are described below:

event - Specifies the event that will trigger the ajax request. If if this attribute is not specified, then the default event for the component will be used.
execute - Specifies a space-separated list of component ids to execute in the request. The keywords @all, @form, @this, and @none can be used as well.
render - Specifies a space-separated list of component ids to be rendered in the request, which may cause view updates in the client when the response is received. The keywords @all, @form, @this, and @none are also supported.
listener - Method to call in the request. Such method must be public, return void and take a javax.faces.event.AjaxBehaviorEvent object as the only parameter.
disabled - Boolean value to disable/enable the ajax capabilities of the component.

Each synthetic event has its own associated default values for the execute and render attributes. So, it's possible to omit these attributes if the most common behavior is desired for the event.

In addition to these attributes that work as in <f:ajax />, another set of attributes are supported to offer more control over the ajax request in the client side. For example, using the onStart attribute, it is possible to decide in the client side, whether the ajax request is sent or not to the server.

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

onStart - Client-side callback to execute before the request is sent to the server. It is passed the 'cfg' argument, containing the ajax request configuration to be modified before the request is sent. If this callback returns false (including null, undefined, 0, and the empty string), then the ajax request will be aborted. This function must return true (or any value that doesn't evaluate to false) to allow the ajax request to continue.
onSuccess - Client-side callback to execute when the ajax request is sucessful (i.e. a 200 status code). It is passed the 'data' argument, containing the XML content of the entire JSF response.
onError - Client-side callback to execute when there was an error with the request/response. It is passed the 'status' and 'error' arguments, containing the returned server status code and error message, respectively.
onComplete - Client-side callback to execute when the ajax request is completed. It is passed the 'args' argument, containing ACE callback parameters such as 'validationFailed'. It fires after onSuccess or onError are called.

As of ICEfaces 4, it is also possible to nest more than one <ace:ajax /> tags in the same component, even if they are for the same event. A separate ajax request will be made for each tag.

Examples

Basic usage

Will submit after the slider handle is released. Since this is the default event, adding event="slideEnd" in the ajax tag is not necessary.

<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax execute="@this" render="outputValue" />
</ace:sliderEntry>
<h:outputText id="outputValue" value="${ajaxTestBean.sliderValue}">
Specifying an event

Will update the value of the outputText as the slider handle is moved.

<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax event="slide" execute="@this" render="outputValue" />
</ace:sliderEntry>
<h:outputText id="outputValue" value="${ajaxTestBean.sliderValue}">
Trapping an event and submitting to server

Will show an alert before submitting to server.

<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax onStart="alert('The value is about to be submitted to the server.'); return true;" execute="@this" render="outputValue" />
</ace:sliderEntry>
<h:outputText id="outputValue" value="${ajaxTestBean.sliderValue}">
Trapping an event and NOT submitting to server

Initially, the value won't be submitted to the server. When clicking the button, this behavior will toggle between sending and not sending to the server, depending on the returned value of the onStart callback.

<script type="text/javascript">
window.submitValue = false;
window.updateInput = true;
</script>
<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax onStart="if (updateInput) cfg.render += ' inputValue'; return submitValue;" execute="@this" render="outputValue" />
</ace:sliderEntry>
<h:outputText id="outputValue" value="${ajaxTestBean.sliderValue}">
<h:inputText id="inputValue" value="${ajaxTestBean.sliderValue}">
<button onclick="submitValue = !submitValue;">Toggle submit</button>
Using server-side listeners and using more than one ajax event

A message will be displayed when the sliding has been started, and another message, when the sliding has been ended.

<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax event="slideStart" execute="@this" render="outputValue" listener="${ajaxTestBean.slideStartListener}" />
	<ace:ajax event="slideEnd" execute="@this" render="outputValue" listener="${ajaxTestBean.slideEndListener}" />
</ace:sliderEntry>
<h:outputText id="outputValue" value="${ajaxTestBean.sliderStatus}" />

Code in the backing bean:

	private String sliderStatus = "";
	
	public String getSliderStatus() {
		return sliderStatus;
	}
	
	public void slideStartListener(javax.faces.event.AjaxBehaviorEvent event) {
		sliderStatus = "Sliding has been started.";
	}
	
	public void slideEndListener(javax.faces.event.AjaxBehaviorEvent event) {
		sliderStatus = "Sliding has been ended.";
	}

Examples of nesting components inside <ace:ajax>

Apply ajax to "button1" and "text1":
<ace:ajax>
	<h:form>
		<ace:pushButton id="button1" ...>
		<ace:textEntry id="text1" ..>
	</h:form>
</ace:ajax>
Apply ajax to "text1" only, since <ace:pushButton> doesn't support the "valueChange" ajax event:
<ace:ajax event="valueChange">
	<h:form>
		<ace:pushButton id="button1" ...>
		<ace:textEntry id="text1" ..>
	</h:form>
</ace:ajax>
Apply ajax to "button1", since <ace:textEntry> doesn't support the "action" ajax event:
<ace:ajax event="action">
	<h:form>
		<ace:pushButton id="button1" ...>
		<ace:textEntry id="text1" ..>
	</h:form>
</ace:ajax>
Override the default ajax action. "button1" is associated with the ajax execute="cancel" action, since inner ajax tags take precedence.
<ace:ajax event="action" execute="reset">
	<h:form>
		<ace:pushButton id="button1" ...>
			<ace:ajax execute="cancel"/>
		</ace:pushButton>
		<ace:textEntry id="text1" ...>
	</h:form>
</ace:ajax>

Merging Ajax Behaviours

If a component has multiple ajax behaviours registered for the same event, these will be merged into a single request in the client side. Some of the request settings will be extended, while others will be overridden. Specifically, custom parameters from all behaviours ('params') will be extended, so that all of them are included in the request. The value of the 'execute' parameter will be extended as well, so that all client ids of all components to be executed are included in this parameter; the same is true for the 'render' parameter. The 'node' parameter will be replaced; the node in the last ajax behaviour is the one that gets used; the same is true for the 'event' parameter. The 'source' parameter is NOT changed; the value set the first time stays unmodified (in practice, all 'source' parameters of all ajax behaviours for the same event should be the same). The 'onstart', 'onerror', 'onsuccess', and 'oncomplete' callbacks are executed in chain, in order.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2018 ICEsoft Technologies Canada Corp.