Create new RichFaces Documentation Jira issue
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.
JBoss.orgCommunity Documentation
The <a4j:support> component is the most important core component in the RichFaces library. It enriches any existing non-Ajax JSF or RichFaces component with an Ajax capability. All the other RichFaces Ajax components are based on the same principles <a4j:support> has.
Table 6.9. a4j : support attributes
| Attribute Name |
Description
|
|---|---|
| action | MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by you, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property |
| actionListener | MethodBinding pointing at method accepting an ActionEvent with return type void |
| ajaxSingle | Limits JSF tree processing (decoding, conversion, validation and model updating) only to a component that sends the request. Boolean |
| binding | JSF: The attribute takes a value-binding expression for a component property of a backing bean |
| bypassUpdates | If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input |
| data | Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax |
| disabled | HTML: If "true", disable this component on page. |
| disableDefault | Disables default action for target event ( append "return false;" to JavaScript ). Default value is "false" |
| event | Name of JavaScript event property ( onclick, onchange, etc.) of parent component, for which we will build AJAX submission code |
| eventsQueue | Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.) |
| focus | ID of an element to set focus after request is completed on client side |
| id | JSF: Every component may have a unique id that is automatically created if omitted |
| ignoreDupResponses | Attribute allows to ignore an Ajax Response produced by a request if the newest 'similar' request is in a queue already. ignoreDupResponses="true" does not cancel the request while it is processed on the server, but just allows to avoid unnecessary updates on the client side if the response isn't actual now |
| immediate | True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase |
| limitToList | If "true", then of all AJAX-rendered on the page components only those will be updated, which ID's are passed to the "reRender" attribute of the describable component. "false"-the default value-means that all components with ajaxRendered="true" will be updated. |
| onbeforedomupdate | The client-side script method to be called before DOM is updated |
| oncomplete | The client-side script method to be called after the request is completed |
| onsubmit | DHTML: The client-side script method to be called before an ajax request is submitted |
| process | Id['s] (in format of call UIComponent.findComponent()) of components, processed at the phases 2-5 in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection |
| rendered | JSF: If "false", this component is not rendered |
| requestDelay | Attribute defines the time (in ms.) that the request will be wait in the queue before it is ready to send. When the delay time is over, the request will be sent to the server or removed if the newest 'similar' request is in a queue already |
| reRender | Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection |
| similarityGroupingId | If there are any component requests with identical IDs then these requests will be grouped. |
| status | ID (in format of call UIComponent.findComponent()) of Request status component |
| timeout | Timeout (in ms) for request |
Table 6.10. Component identification parameters
| Name | Value |
|---|---|
| component-type | org.ajax4jsf.Support |
| component-family | org.ajax4jsf.AjaxSupport |
| component-class | org.ajax4jsf.component.html.HtmlAjaxSupport |
| renderer-type | org.ajax4jsf.components.AjaxSupportRenderer |
To create the simplest variant on a page you should put <a4j:support> as a nested element into the component that you want to enhance with Ajax functionality. You should also specify an event that will trigger an Ajax request.
Example:
<h:inputText value="#{bean.text}">
<a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>
<h:outputText id="repeater" value="#{bean.text}"/>
In order to add the <a4j:support> in Java code you should add it as facet , not as a child:
Example:
HtmlInputText inputText = new HtmlInputText();
...
HtmlAjaxSupport ajaxSupport = new HtmlAjaxSupport();
ajaxSupport.setActionExpression(FacesContext.getCurrentInstance().getApplication().getExpressionFactory().createMethodExpression(
FacesContext.getCurrentInstance().getELContext(), "#{bean.action}", String.class, new Class[] {}));
ajaxSupport.setEvent("onkeyup");
ajaxSupport.setReRender("output");
inputText.getFacets().put("a4jsupport", ajaxSupport);
The <a4j:support> component has two key attributes:
mandatory "event" attribute that defines the JavaScript event the Ajax support will be attached to
"reRender" attribute that defines id(s) of JSF component(s) that should be rerendered after an Ajax request
As mentioned above the <a4j:support> component adds Ajax capability to non-Ajax JSF components. Let's create ajaxed <h:selectOneMenu> called "Planets and Their Moons".
We begin with the common behavior description. When a page is rendered you see only one select box with the list of planets. When you select a planet the <h:dataTable> containig moons of the selected planet appears.
In other words we need <h:selectOneMenu> with the nested <a4j:support> component that is attached to the onchange event.
When an Ajax response comes back the <h:dataTable> is re-rendered on the server side and updated on the client.
...
<h:form id="planetsForm">
<h:outputLabel value="Select the planet:" for="planets" />
<h:selectOneMenu id="planets" value="#{planetsMoons.currentPlanet}" valueChangeListener="#{planetsMoons.planetChanged}">
<f:selectItems value="#{planetsMoons.planetsList}" />
<a4j:support event="onchange" reRender="moons" />
</h:selectOneMenu>
<h:dataTable id="moons" value="#{planetsMoons.moonsList}" var="item">
<h:column>
<h:outputText value="#{item}"/>
</h:column>
</h:dataTable>
</h:form>
...
Finally we need a backing bean:
...
public class PlanetsMoons {
private String currentPlanet="";
public List<SelectItem> planetsList = new ArrayList<SelectItem>();
public List<String> moonsList = new ArrayList<String>();
private static final String [] EARTH = {"The Moon"};
private static final String [] MARS = {"Deimos", "Phobos"};
private static final String [] JUPITER = {"Europa", "Gamymede", "Callisto"};
public PlanetsMoons() {
SelectItem item = new SelectItem("earth", "Earth");
planetsList.add(item);
item = new SelectItem("mars", "Mars");
planetsList.add(item);
item = new SelectItem("jupiter", "Jupiter");
planetsList.add(item);
}
public void planetChanged(ValueChangeEvent event){
moonsList.clear();
String[] currentItems;
if (((String)event.getNewValue()).equals("earth")) {
currentItems = EARTH;
}else if(((String)event.getNewValue()).equals("mars")){
currentItems = MARS;
}else{
currentItems = JUPITER;
}
for (int i = 0; i < currentItems.length; i++) {
moonsList.add(currentItems[i]);
}
}
//Getters and Setters
...
}
There are two properties planetsList and moonsList.
The planetsList is filled with planets names in the constructor.
After you select the planet,
the planetChanged() listener is called and
the moonsList is populated with proper values of moons.
With the help of "onsubmit" and "oncomplete" attributes the <a4j:support> component allows to use JavaScript calls before and after an Ajax request respectively. Actuallly the JavaScript specified in the "oncomplete" attribute will be executed in any case whether the Ajax request is completed successfully or not.
You can easily add confirmation dialog for the planet select box and colorize <h:dataTable> after the Ajax response:
...
<h:form id="planetsForm">
<h:outputLabel value="Select the planet:" for="planets" />
<h:selectOneMenu id="planets" value="#{planetsMoons.currentPlanet}" valueChangeListener="#{planetsMoons.planetChanged}">
<f:selectItems value="#{planetsMoons.planetsList}" />
<a4j:support event="onchange" reRender="moons"
onsubmit="if(!confirm('Are you sure to change the planet?')) {form.reset(); return false;}"
oncomplete="document.getElementById('planetsForm:moonsPanel').style.backgroundColor='#c8dcf9';" />
</h:selectOneMenu>
<h:dataTable id="moons" value="#{planetsMoons.moonsList}" var="item">
<h:column>
<h:outputText value="#{item}"/>
</h:column>
</h:dataTable>
</h:form>
...
There is the result:
Information about the "process" attribute usage you can find in the " Decide what to process " guide section.
The <a4j:support> component created on a page as following
<h:inputText value="#{bean.text}">
<a4j:support event="onkeyup" reRender="output" action="#{bean.action}"/>
</h:inputText>
is decoded in HTML as
<input onkeyup="A4J.AJAX.Submit( Some request parameters )"/>
Visit <a4j:support> demo page at RichFaces live demo for examples of component usage and their sources.
