JSF JSF and Ajax Basics <DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <h:head> <title>a Simple JavaServer Faces 2.0 View</title> </h:head> <h:body> <h:form> You entered: #{requestscope.input}. <h:inputtext id="input" value="#{requestscope.input}"> <f:ajax render="@form" /> </h:inputtext> </h:form> </h:body> </html> Whenever the user moves the cursor out of the input field, the effect will be the same as if that user pressed the button, with the all important exception that the contents of the form will update asynchronously, without a full page refresh. That s what the rendered="@form" attribute on the <f:ajax> tag means. Let s say we want to add a userid field to the register.xhtml page, and make it so that the availability of the userid is checked automatically as the user fills out the form. The beginning lines of the new register.xhtml file are shown here: <DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"> <h:head> <title>a Simple JavaServer Faces Registration Application</title> </h:head> <h:body> <h:form> <h2>jsf Registration App</h2> <h4>registration Form</h4> <table> <tr> <td>userid:</td> <td> <f:ajax render="useridmessage"> <h:inputtext label="userid" id="userid" value="#{userbean.userid}" required="true"/> <h:message id="useridmessage" for="userid" /> </f:ajax> </td> </tr> The presence of the <f:ajax> tag wrapping the input field and its corresponding message will cause the form to be submitted, processed, and rendered, partially. In this case, only the value of the userid field is submitted, and only the necessary components that need to process the userid field are processed in the JSF lifecycle. Ajax is just a way to take action on discrete subtrees of a complete server-side view.
The <f:ajax> Tag and Its Attributes This section explains the options available on the <f:ajax> tag and gives some insight into how to use them. The general form for the <f:ajax> tag is shown in Figure 12-6. All of the attributes are optional. The action taken in the case of missing attributes is explained in the accompanying sidebar. Like most of the tags in the f: library, the <f:ajax> tag cannot be used in isolation; it has to be nested within, or wrapped around, a tag that corresponds to a server side UIComponent. This code wraps the input field and the button and applies Ajax capabilities to each component: <f:ajax <f:ajax> <h:inputtext value="#{model.username}" /> <h:commandbutton action="next" /> </f:ajax> execute="space separated list of client ids, ValueExpression that evaluates to such a list, or a special keyword" The values submitted on this POST will be determined from the value of the execute attribute. The subtrees in the server side view that are traversed during the execute portion of the lifecycle are also determined from the value of the execute attribute. If the listener attribute is non null, it is invoked during the INVOKE APPLICATION lifecycle phase. render="space separated list of client ids, ValueExpression that evaluates to such a list, or a special keyword" The subtrees of the server side view that are rendered are determined from the value of the render attribute. listener="methodexpression pointing to a method with signature void f(ajaxbehaviorevent e)" immediate="true, false, or ValueExpression that evaluates to true or false" disabled="true, false, or ValueExpression that evaluates to true or false. If true, the tag has no effect." event="string that is one of the supported event names from table 12-1" For the UIComponent to which this tag applies, when the JavaScript event corresponding to the event attribute is delivered by the browser, send a POST request via Ajax to the JSF page that rendered this page. onevent="name (or ValueExpression that evaluates to name) of a JavaScript function that accepts one argument" onerror="name (or ValueExpression that evaluates to name) of a JavaScript function that accepts one argument onerror and onevent refer to JavaScript functions that are called to allow user code to be aware of the status of the ajax request and response. /> This code does the same thing but using the nesting syntax: <h:inputtext value="#{model.username}"> <f:ajax /> </h:inputtext> <h:commandbutton action="next"> <f:ajax /> </h:commandbutton> You may well ask, If both variants do the same thing, why have two variants? The answer comes when you need to customise the attributes for each specific usage. In this case, the fine granularity of nesting the <f:ajax> within individual components is probably what you want. Note that it is possible to wrap and nest the same component, as shown here: <f:ajax event="mouseout"> <h:inputtext value="#{model.username}"> <f:ajax event="dblclick" /> </h:inputtext> <h:commandbutton action="next" /> </f:ajax>
In such cases, the attributes effectively are the union of the wrapping tag and the wrapped tag. In the preceding example, the <h:inputtext> would have Ajax behaviour applied for the mouseout and dblclick events, while the <h:commandbutton> would only have Ajax behaviour for mouseout. Figure 12-6 tells what happens when the <f:ajax> tag is applied to a UIComponent tag. The accompanying simple rules describe to which UIComponent tags the <f:ajax> tag applies. Rules to Determine Which UIComponent Tag Is Imbued with Ajax Behaviour: This sidebar lists the rules the JSF runtime follows to determine to which UIComponent tag the <f:ajax> tag applies. If the <f:ajax> tag has no UIComponent tag children and is nested immediately inside of a UIComponent tag, the parent UIComponent is imbued with Ajax behaviour. If the <f:ajax> tag has UIComponent children (and any children of those children, and so on) are imbued with Ajax behaviour. Optional Arguments and <f:ajax> As mentioned previously, all of the attributes on the <f:ajax> tag are optional and have sensible default values described here. - If execute is not specified, the client ID of the UIComponent to which the <f:ajax> tag applies is the default. This means that only one name=value pair will be submitted in the POST data and only one UIComponent will be processed during the postback. - If render is not specified, no components will be traversed during the Render Response phase. - If listener is not specified, the only action that will be invoked during the Invoke Application phase will be the one that corresponds to an ActionSource component listed in the execute attribute, if the execute attribute refers to such a component. This attribute makes the <f:ajax> tag cause potentially any component to act like an ActionSource. - If immediate is not specified, the action happens during the Invoke Application phase; otherwise, the action happens during the Apply Request Values phase. This attribute is semantically equivalent to the attribute of the same name on other components in JSF. - If disabled is not specified, the Ajax behaviour performs as planned. This is useful for conditionally turning off Ajax, for example, if the application is aware of whether or not JavaScript is supported in the browser. - If event is not specified, the value returned from the getdefaulteventname( ) method on the UIComponent is used. If specified, the event name must be one of the values returned from the geteventnames( ) method on the UIComponent. Later Table 12-1 lists the default and additional supported event names for each component in the Standard HTML RenderKit. - If onevent is not specified, no JavaScript function is called to provide status updates. - If onerror is not specified, in Development mode, for Sun s Mojarra JSF implementation only, a modal alert dialog is raised sent. In all other modes, the error is unhandled if no onerror is specified. Special Keywords for Use in the execute and render Attributes The execute and render keywords accept a set of special keywords, each with the meaning shown in this table.
Keyword Meaning @all When used in execute Every component on the page is submitted and processed. This is useful when you want to do a fullpage submit. When used in render Every component on the page is rendered. This is useful when you just want to rerender the whole page asynchronously. This behavior is useful if you want to update the page and keep some client side state outside of JSF. @none Execute the lifecycle, including its phase listeners, but no components will be traversed. Perform the Render Response phase, including firing any prerenderview events, but don t actually render anything. @this @form Submit and process only the component to which the <f:ajax> is applied. Submit and process the entire <h:form> in which the component that has the <f:ajax> is nested. Render only the component to which the <f:ajax> is applied. Render the entire <h:form> in which the component that has the <f:ajax> is nested. To round out our description of the <f:ajax> tag, Table 12-1 lists the default and supported values for the event attribute for all of the tags in the Standard HTML RenderKit. Before this complete list, there are two important global default events value that override those listed in Table 12-1. The default event value for any component that is an EditableValueHolder is change. This corresponds to the onchange JavaScript event and means that the Ajax transaction will commence when the browser detects that the user has changed the value of the field. This is very similar to the onblur JavaScript event with subtle differences between browsers The default event value for any component that is an ActionSource is action. This event maps to the onclick JavaScript event. The word action was chosen over click to be more general and to account for an ActionSource component that may not support a click concept. However, the <h:commandbutton> and <h:commandlink> components do support the click concept, and thus action is a synonym for click on those components.
Tag Name Default Event Attribute Value Supported Event Attribute Values <h:body> none click dblclick keydown keypress keyup load mouseup unload <h:commandbutton> action change click action dblclick focus keydown keypress keyup mousedown mousemove <h:commandlink> blur click action dblclick focus keydown keypress keyup mouseup <h:datatable> none click dblclick keydown keypress keyup mousedown <h:form> none click dblclick keydown keypress keyup mousedown <h:graphicimage> none click dblclick keydown keypress keyup mousedown <h:inputsecret> valuechange blur change valuechange click dblclick focus <h:inputtextarea> valuechange blur change valuechange click dblclick focus <h:button> none blur click dblclick focus keydown keypress keyup mouseup <h:link> action blur click action dblclick focus keydown keypress keyup mousedown mousemove mouseout mouseover mouseup <h:outputlabel> none blur click dblclick focus keydown keypress keyup mouseup <h:outputlink> action blur click action dblclick focus keydown keypress keyup mousedown mousemove mouseout mouseover mouseup
<h:panelgrid> none click dblclick keydown keypress keyup mousedown <h:selectbooleancheckbox> valuechange blur change click valuechange dblclick focus <h:selectmanycheckbox> valuechange blur change click valuechange dblclick focus <h:selectmanylistbox> valuechange blur change valuechange click dblclick focus <h:selectmanymenu> valuechange blur change valuechange click dblclick focus <h:selectonelistbox> valuechange blur change valuechange click dblclick focus <h:selectonemenu> valuechange blur change valuechange click dblclick focus <h:selectoneradio> valuechange blur change click valuechange dblclick focus
The onevent and onerror Attributes Two of the attributes are special in that they allow you to pass the name of a JavaScript function to the <f:ajax> tag so that the system can call you back in various cases as the Ajax transaction progresses. JavaScript is a dynamically typed language with lots of functional language capabilities. Therefore, it is very easy to pass around references to functions, and the signatures for those functions are dynamic. So when Figure 12-6 states that onerror and onevent refer by name to a function that takes one argument, a function that takes no arguments will work as well, you just won t have access to the useful information passed in that argument. The rest of the section assumes that you do in fact have JavaScript functions with one argument when you use the onevent and onerror callback facility. Property Name Meaning Type Status The value of the event attribute that this callback is describing. For example, click. Begin when the request has not yet been sent. complete when the Ajax response has been received but has not yet been processed. A complete status will be delivered even in the case of an error. success after the complete status has been shared and after the response has successfully been processed. responsecode The HTTP status code from the response, such as 404 or 200. responsexml The actual XML response, beginning with <partial-response>, such as shown in Figure 12-5. responsetext source A String, not XML, version of responsexml. The DOM element that caused the Ajax transaction to be sent.