6.6.  < a4j:form >

6.6.1. Description

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 NameDescription
acceptThis 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")
acceptCharsetThis 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
ajaxSingleif "true", submits ONLY one field/link, instead of all form controls
ajaxSubmitIf true, it becomes possible to set AJAX submission way for any components inside .
bindingThe attribute takes a value-binding expression for a component property of a backing bean
bypassUpdatesIf "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
dataSerialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
enctypeThis 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"
eventsQueueName 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.)
focusid of element to set focus after request completed on client side
idEvery component may have a unique id that is automatically created if omitted
ignoreDupResponsesAttribute 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
limitToListIf "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
onbeforedomupdateJavaScript code for call before DOM has been updated on client side
oncompleteJavaScript code for call after request completed on client side
onresetThe onreset event occurs when a form is reset. It only applies to the FORM element
onsubmitThe onsubmit event occurs when a form is submitted. It only applies to the FORM element
prependIdThe 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.
processId['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
renderedIf "false", this component is not rendered
requestDelayAttribute 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
reRenderId['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
statusID (in format of call UIComponent.findComponent()) of Request status component
targetThis 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
timeoutTimeout ( in ms ) for request.

Table 6.12. Component identification parameters

NameValue
component-typeorg.ajax4jsf.Form
component-familyjavax.faces.Form
component-classorg.ajax4jsf.component.html.AjaxForm
renderer-typeorg.ajax4jsf.FormRenderer

6.6.2. Creating on a page

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>

6.6.3. Creating the Component Dynamically Using Java

Example:


import org.ajax4jsf.component.html.AjaxForm;
...
AjaxForm myForm = new AjaxForm();
...

6.6.4. Key attributes and ways of usage

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.

6.6.5. Relevant resources links

Here you can see the example of <a4j:form> usage and sources for the given example.