This chapter details the basic components that respond to a user action and submit an Ajax request.
component-type:
org.ajax4jsf.ActionParametercomponent-class:
org.ajax4jsf.component.html.HTMLActionParameter
The <a4j:actionParam> behavior combines the functionality of the JavaServer Faces (JSF) components <f:param> and <f:actionListener>.
Basic usage of the <a4j:actionParam> requires three main attributes:
name, for the name of the parameter;value, for the initial value of the parameter; andassignTo, for defining the bean property. The property will be updated if the parent command component performs an action event during the Process Request phase.
Example 4.1, “<a4j:actionParam> example” shows a simple implementation along with the accompanying managed bean. When the button is pressed, the application sets the name parameter of the bean to Alex, and displays the name in the output field.
Example 4.1. <a4j:actionParam> example
<!DOCTYPE null [
<!ENTITY version "4.0.0.20100715-M1">
<!ENTITY today "July 15, 2010">
]>
<h:form id="form">
<a4j:commandButton value="Set name to Alex" reRender="rep">
<a4j:actionparam name="username" value="Alex" assignTo="#{actionparamBean.name}"/>
</a4j:commandButton>
<h:outputText id="rep" value="Name: #{actionparamBean.name}"/>
</h:form>
public class ActionparamBean {
private String name = "John";
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
The <a4j:actionParam> behavior can be used with non-Ajax components in addition to Ajax components. In this way, data model values can be updated without an JavaScript code on the server side.
The converter attribute can be used to specify how to convert the value before it is submitted to the data model. The property is assigned the new value during the Update Model phase.
Validation failure
If the validation of the form fails, the Update Model phase will be skipped and the property will not be updated.
Variables from JavaScript functions can be used for the value attribute. In such an implementation, the noEscape attribute should be set to true. Using noEscape="true", the value attribute can contain any JavaScript expression or JavaScript function invocation, and the result will be sent to the server as the value attribute.
listener-class:
org.ajax4jsf.event.AjaxListenerevent-class:
org.ajax4jsf.event.AjaxEventtag-class:
org.ajax4jsf.taglib.html.jsp.AjaxListenerTag
The <a4j:ajaxListener> component adds an action listener to a parent component. It works similar to the JavaServer Faces <f:actionListener> or <f:valueChangeListener> components, except that the invocation of <a4j:ajaxListener> is not canceled if validation of the Update Model phase fails. The <a4j:ajaxListener> component is guaranteed to be invoked with each Ajax response.
Basic usage requires only the type attribute, which defines the fully-qualified Java class name for the listener. This Java class should implement the org.ajax4jsf.event.AjaxListener interface, which is a base listener for all listeners and is capable of receiving Ajax events. The object from which the event originated could be accessed using the java.util.EventObject.getSource() method.
The <a4j:ajaxListener> component is not invoked for non-Ajax requests, or when the RichFaces works in the Ajax request generates non-Ajax response mode, so the <a4j:ajaxListener> invocation is a good indicator that an Ajax response is going to be processed.
component-type:
org.ajax4jsf.CommandButtoncomponent-family:
javax.faces.Commandcomponent-class:
org.ajax4jsf.component.html.HtmlAjaxCommandButtonrenderer-type:
org.ajax4jsf.components.AjaxCommandButtonRenderer
The <a4j:commandButton> is similar to the JavaServer Faces (JSF) component <h:commandButton>, but additionally includes Ajax support. When the command button is clicked it generates an Ajax form submit, and when a response is received the command button can be dynamically rendered.
The <a4j:commandButton> requires only the value and render attributes to function. The value attribute specifies the text of the button and the render attribute specifies which areas are to be updated. The <a4j:commandButton> uses the onclick event instead of the onsubmit event, but otherwise uses all common Ajax attributes as listed in Chapter 2, Common Ajax attributes.
Set disabledDefault="true"
When attaching a JavaScript function to a <a4j:commandButton> with the help of a <rich:componentControl>, do not use the attachTo attribute of <rich:componentControl>. The attribute adds event handlers using Event.observe but <a4j:commandButton> does not include this event.
component-type:
org.ajax4jsf.CommandLinkcomponent-family:
javax.faces.Commandcomponent-class:
org.ajax4jsf.component.html.HtmlAjaxCommandLinkrenderer-type:
org.ajax4jsf.components.AjaxCommandLinkRenderer
The <a4j:commandLink> is similar to the JavaServer Faces (JSF) component <h:commandLink>, but additionally includes Ajax support. When the command link is clicked it generates an Ajax form submit, and when a response is received the command link can be dynamically rendered.
The <a4j:commandLink> requires only the value and render attributes to function. The value attribute specifies the text of the link and the render attribute specifies which areas are to be updated. The <a4j:commandLink> uses the onclick event instead of the onsubmit event, but otherwise uses all common Ajax attributes as listed in Chapter 2, Common Ajax attributes.
The following reference data is taken from the old <rich:componentControl> reference. The details may be different now that the component is part of the a4j tag library.
component-type:
org.richfaces.ComponentControlcomponent-family:
org.richfaces.ComponentControlcomponent-class:
org.richfaces.component.html.HtmlComponentControlrenderer-type:
org.richfaces.ComponentControlRenderertag-class:
org.richfaces.taglib.ComponentControlTag
The <rich:componentControl> allows JavaScript API functions to be called on components after defined events. Initialization variants and activation events can be customized, and parameters can be passed to the target component.
The event, for, and operation attributes are all that is required to attach JavaScript functions to the parent component. The event attribute specifies the event that triggers the JavaScript API function call. The for attribute defines the target component, and the operation attribute specifies the JavaScript function to perform.
Example 4.2. rich:componentControl basic usage
<h:commandButton value="Show Modal Panel">
<!--componentControl is attached to the commandButton-->
<rich:componentControl for="ccModalPanelID" event="onclick" operation="show"/>
</h:commandButton>
The example contains a single command button, which when clicked shows the modal panel with the identifier ccModalPanelID.
The attachTo attribute can be used to attach the event to a component other than the parent component. If no attachTo attribute is supplied, the <rich:componentControl> component's parent is used, as in Example 4.2, “rich:componentControl basic usage”.
Example 4.3. Attaching <rich:componentControl> to a component
<rich:componentControl attachTo="doExpandCalendarID" event="onclick" operation="Expand" for="ccCalendarID" />
In the example, the onclick event of the component with the identifier ccCalendarID will trigger the Expand operation for the component with the identifier doExpandCalendarID.
The operation can receive parameters either through the params attribute, or by using <f:param> elements.
Example 4.4. Using parameters
- The
paramsattribute <rich:componentControl name="func" event="onRowClick" for="menu" operation="show" params="#{car.model}"/>
<f:param>elements<rich:componentControl event="onRowClick" for="menu" operation="show">
<f:param value="#{car.model}" name="model"/>
</rich:componentControl>
The name attribute can be used to define a normal JavaScript function that triggers the specified operation on the target component.
The attachTiming attribute can determine the page loading phase during which the <rich:componentControl> is attached to the source component:
immediateattached during execution of the script.
onavailableattached after the target component is initialized.
onloadattached after the page is loaded.
component-type:
org.ajax4jsf.HtmlCommandLinkcomponent-family:
javax.faces.Commandcomponent-class:
org.ajax4jsf.component.html.HtmlCommandLinkrenderer-type:
org.ajax4jsf.HtmlCommandLinkRenderer
The <a4j:htmlCommandLink> component functions similarly to the standard <h:commandLink> component, but addresses some of the potential issues that can occur.
When using the standard component, hidden fields were not rendered to child elements if they were deemed unnecessary, so command links relating to content on the initial page could become broken if they were later updated through Ajax. The <a4j:htmlCommandLink> component addresses this by always rendering all hidden fields.
component-type:
org.ajax4jsf.Functioncomponent-family:
org.ajax4jsf.components.ajaxFunctioncomponent-class:
org.ajax4jsf.component.html.HtmlajaxFunctionrenderer-type:
org.ajax4jsf.components.ajaxFunctionRenderer
The <a4j:jsFunction> component allows Ajax requests to be performed directly from JavaScript code, and server-side data to be invoked and returned in JavaScript Object Notation (JSON) format to use in client-side JavaScript calls.
The <a4j:jsFunction> component has all the common Ajax action attributes as listed in Chapter 2, Common Ajax attributes; the action and actionListener attributes can be invoked and parts of the page can be re-rendered after a successful call to the JavaScript function. Example 4.5, “<a4j:jsFunction> example” shows how an Ajax request can be initiated from the JavaScript and a partial page update performed. The JavaScript function can be invoked with the data returned by the Ajax response.
Example 4.5. <a4j:jsFunction> example
<!DOCTYPE null [
<!ENTITY version "4.0.0.20100715-M1">
<!ENTITY today "July 15, 2010">
]>
<h:form>
...
<a4j:jsFunction name="callScript" data="#{bean.someProperty1}" reRender="someComponent" oncomplete="myScript(data.subProperty1, data.subProperty2)">
<a4j:actionParam name="param_name" assignTo="#{bean.someProperty2}"/>
</a4j:jsFunction>
...
</h:form>
The <a4j:jsFunction> component allows the use of the <a4j:actionParam> component or the JavaServer Faces <f:param> component to pass any number of parameters for the JavaScript function.
The <a4j:jsFunction> component is similar to the <a4j:commandButton> component, but it can be activated from the JavaScript code. This allows some server-side functionality to be invoked and the returned data to subsequently be used in a JavaScript function invoked by the oncomplete event attribute. In this way, the <a4j:jsFunction> component can be used instead of the <a4j:commandButton> component.
component-type:
org.ajax4jsf.Pollcomponent-family:
org.ajax4jsf.components.AjaxPollcomponent-class:
org.ajax4jsf.component.html.AjaxPollrenderer-type:
org.ajax4jsf.components.AjaxPollRenderer
The <a4j:poll> component allows periodical sending of Ajax requests to the server. It is used for repeatedly updating a page at specific time intervals.
The interval attribute specifies the time in milliseconds between requests. The default for this value is 1000 ms (1 second).
The timeout attribute defines the response waiting time in milliseconds. If a response isn't received within the timeout period, the connection is aborted and the next request is sent. By default, the timeout is not set.
The <a4j:poll> component can be enabled and disabled using the enabled attribute. Using Expression Language (EL), the enabled attribute can point to a bean property to apply a particular attribute value.
component-type:
org.ajax4jsf.Pushcomponent-family:
org.ajax4jsf.components.AjaxPushcomponent-class:
org.ajax4jsf.component.html.AjaxPushrenderer-type:
org.ajax4jsf.components.AjaxPushRenderer
The <a4j:push> component periodically performs an Ajax request to the server, simulating "push" functionality. While it is not strictly pushing updates, the request is made to minimal code only, not to the JSF tree, checking for the presence of new messages in the queue. The request registers EventListener, which receives messages about events, but does not poll registered beans. If a message exists, a complete request is performed. This is different from the <a4j:poll> component, which performs a full request at every interval.
The interval attribute specifies the time in milliseconds between checking for messages. The default for this value is 1000 ms (1 second). It is possible to set the interval value to 0, in which case it is constantly checking for new messages.
The timeout attribute defines the response waiting time in milliseconds. If a response isn't received within the timeout period, the connection is aborted and the next request is sent. By default, the timeout is not set. In combination with the interval attribute, checks for the queue state can short polls or long connections.
component-type:
org.ajax4jsf.Repeatcomponent-family:
javax.faces.Datacomponent-class:
org.ajax4jsf.component.html.HtmlAjaxRepeatrenderer-type:
org.ajax4jsf.components.RepeatRenderer
REVIEW COMMENT - a4j:repeat is not an action, should be moved. The <a4j:repeat> component is used to iterate changes through a repeated collection of components. It allows specific rows of items to be updated without sending Ajax requests for the entire collection. The <a4j:repeat> component forms the basis for many of the tabular components detailed in Chapter 9, Tables and grids.
The contents of the collection are determined using Expression Language (EL). The data model for the contents is specified with the value attribute. The var attribute names the object to use when iterating through the collection. This object is then referenced in the relevant child components. After an Ajax request, only the rows specified with the ajaxKeys attribute are updated rather than the entire collection. Example 4.6, “<a4j:repeat> example” shows how to use <a4j:repeat> to maintain a simple table.
Example 4.6. <a4j:repeat> example
<!DOCTYPE null [
<!ENTITY version "4.0.0.20100715-M1">
<!ENTITY today "July 15, 2010">
]>
<table>
<tbody>
<a4j:repeat value="#{repeatBean.items}" var="item" ajaxKeys="#{updateBean.updatedRow}">
<tr>
<td><h:outputText value="#{item.code}" id="item1" /></td>
<td><h:outputText value="#{item.price}" id="item2" /></td>
</tr>
</a4j:repeat>
</tbody>
</table>
Each row of a table contains two cells: one showing the item code, and the other showing the item price. The table is generated by iterating through items in the repeatBeans.items data model.
The <a4j:repeat> component uses other attributes common to iteration components, such as the first attribute for specifying the first item for iteration, and the rows attribute for specifying the number of rows of items to display.
component-type:
org.ajax4jsf.Ajaxcomponent-family:
org.ajax4jsf.Ajaxcomponent-class:
org.ajax4jsf.component.html.HtmlAjaxSupportrenderer-type:
org.ajax4jsf.components.AjaxSupportRenderer
REVIEW COMMENT: a4j:support is a4j:ajax in 4.0, paths need to be updated. The <a4j:ajax> component allows Ajax capability to be added to any non-Ajax component. It is placed as a direct child to the component that requires Ajax support. The <a4j:ajax> component uses the common attributes listed in Chapter 2, Common Ajax attributes.
Attaching JavaScript functions
When attaching the <a4j:ajax> component to non-Ajax JavaServer Faces command components, such as <h:commandButton> and <h:commandLink>, it is important to set disabledDefault="true". If this attribute is not set, a non-Ajax request is sent after the Ajax request and the page is refreshed unexpectedly.
Example 4.7. <a4j:ajax> example
<h:panelGrid columns="2">
<h:inputText id="myinput" value="#{userBean.name}">
<a4j:ajax event="onkeyup" reRender="outtext" />
</h:inputText>
<h:outputText id="outtext" value="#{userBean.name}" />
</h:panelGrid>