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:

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.

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.