Ajax (<ace:ajax>)

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. At the moment, it is not possible to wrap a number of components inside the tag, but each component needs to have its own nested tag.

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.

onStart - Client-side callback to execute before the request is sent to the server. 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).
onError - Client-side callback to execute when there was an error with the request/response.
onComplete - Client-side callback to execute when the ajax request is completed. It fires after onSuccess or onError are called.

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;
</script>
<ace:sliderEntry value="${ajaxTestBean.sliderValue}">
	<ace:ajax onStart="return submitValue;" execute="@this" render="outputValue" />
</ace:sliderEntry>
<h:outputText id="outputValue" 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.";
	}

Ajax