The <a4j:form> component is very similar to the same component from the JSF HTML library, the only slight difference is in generation of links inside and possibility of Ajax by-default submission.
Table 6.11. a4j : form attributes
Attribute Name | Description |
---|---|
accept | This attribute specifies a comma-separated list of content types that a server processing this form will handle correctly. User agents may use this information to filter out non-conforming files when prompting you to select files to be sent to the server (cf. the INPUT element when type="file") |
acceptCharset | This attribute specifies the list of character encodings for input data that is accepted by the server processing this form. The value is a space- and/or comma-delimited list of charset values. The client must interpret this list as an exclusive-or list, i.e., the server is able to accept any single character encoding per entity received. The default value for this attribute is the reserved string "UNKNOWN". User agents may interpret this value as the character encoding that was used to transmit the document containing this FORM element |
ajaxSingle | if "true", submits ONLY one field/link, instead of all form controls |
ajaxSubmit | If true, it becomes possible to set AJAX submission way for any components inside . |
binding | 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 |
enctype | This attribute specifies the content type used to submit the form to the server (when the value of method is "post"). The default value for this attribute is "application/x-www-form-urlencoded". The value "multipart/form-data" should be used in combination with the INPUT element, type="file" |
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 element to set focus after request completed on client side |
id | 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 |
limitToList | If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components |
onbeforedomupdate | JavaScript code for call before DOM has been updated on client side |
oncomplete | JavaScript code for call after request completed on client side |
onreset | The onreset event occurs when a form is reset. It only applies to the FORM element |
onsubmit | The onsubmit event occurs when a form is submitted. It only applies to the FORM element |
prependId | The flag indicating whether or not this form should prepend its id to its descendent id during the clientId generation process. If this flag is not set, the default value is true. |
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 | 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 |
status | ID (in format of call UIComponent.findComponent()) of Request status component |
target | This attribute specifies the name of a frame where a document is to be opened. By assigning a name to a frame via the name attribute, authors can refer to it as the "target" of links defined by other elements |
timeout | Timeout ( in ms ) for request. |
Table 6.12. Component identification parameters
Name | Value |
---|---|
component-type | org.ajax4jsf.Form |
component-family | javax.faces.Form |
component-class | org.ajax4jsf.component.html.AjaxForm |
renderer-type | org.ajax4jsf.FormRenderer |
Component definition on a page is similar to definition of the original component from JSF HTML library.
Example:
<a4j:form>
<h:panelGrid>
<h:commandButton value="Button" action="#{userBean.nameItMark}" />
</h:panelGrid>
</a4j:form>
Example:
import org.ajax4jsf.component.html.AjaxForm;
...
AjaxForm myForm = new AjaxForm();
...
The difference with the original component is that all hidden fields required for command links are always rendered and it doesn't depend on links rendering on the initial page. It solves the problem with invalid links that weren't rendered on a page immediately, but after some Ajax request.
Beginning with release 1.0.5 additional attributes that make this form variant universal have appeared.
If "ajaxSubmit" attribute is true, it becomes possible to set Ajax submission way for any components inside, i.e. not a page URL is used as an "action" attribute, but the javascript:A4J.AJAX.Submit(...) call. In this case, the "reRender" attribute contains a list of Ids of components defined for re-rendering. If you have <h:commandButton> or <h:commandLink> inside the form, they work as <a4j:commandButton> .
Example:
<a4j:form id="helloForm" ajaxSubmit="true" reRender="table">
...
<t:dataTable id="table"... >
...
</t:dataTable>
...
<t:datascroller for="table"... >
...
</t:datascroller>
...
</a4j:form
This example shows that in order to make <t:datascroller> submissions to be Ajax ones it's required only to place this <t:datascroller> into <a4j:form> . In the other case it is necessary to redefine renders for its child links elements that are defined as <h:commandLink> and can't be made Ajax ones with using e.g. <a4j:support> .
With the help of "limitToList" attribute you can limit areas, which are updated after the responses. If "limitToList" is true, only the reRender attribute is taken in account. Therefore, if you use blocks of text wrapped with <a4j:outputPanel> and "ajaxRendered" = true, blocks of text are ignored.
Information about the "process" attribute usage you can find here.
Here you can see the example of <a4j:form> usage and sources for the given example.