6.20.  < a4j:region >

6.20.1. Description

The <a4j:region> component defines an area that is decoded on the server after Ajax submission.

Table 6.39. a4j : region attributes

Attribute NameDescription
ajaxListenerMethodExpression representing an action listener method that will be notified when this component is activated by the ajax Request and handle it. The expression must evaluate to a public method that takes an AjaxEvent parameter, with a return type of void
bindingThe attribute takes a value-binding expression for a component property of a backing bean
idEvery component may have a unique id that is automatically created if omitted
immediateFlag indicating that, if this component is activated by ajaxrequest, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase
renderedIf "false", this component is not rendered
renderRegionOnlyFlag to disable rendering in AJAX responses content outside of active region. If this attribute set to "true" , no one of the components outside of region will be included to AJAX response. If set to "false", search for components to include in response will be performed on all tree. Default "false"
selfRenderedif "true", self-render subtree at InvokeApplication ( or Decode, if immediate property set to true ) phase

Table 6.40. Component identification parameters

NameValue
component-typeorg.ajax4jsf.AjaxRegion
component-familyorg.ajax4jsf.AjaxRegion
component-classorg.ajax4jsf.component.html.HtmlAjaxRegion
renderer-typeorg.ajax4jsf.components.AjaxRegionRenderer

6.20.2. Creating on a page

Here is an example of the region decoding on a page.


                <a4j:region>
                    <h:inputText value="#{userBean.name}">
                        <a4j:support event="onkeyup" reRender="outname" />
                    </h:inputText>
                </a4j:region>

6.20.3. Creating the Component Dynamically Using Java

Example:


import org.ajax4jsf.component.html.HtmlAjaxRegion;
...
HtmlAjaxRegion newRegion = new HtmlAjaxRegion();
...

6.20.4. Key attributes and ways of usage

The region is a component used for manipulation with components sent to the server. It sets particular processing parameters for an area on the server, i.e. the region deals with data input on the server and has no direct impact on output. To read more on the components responsible for out, see "reference" here.

The region marks an area page that is decoded on the server. In most cases it is not necessary to use the region, as ViewRoot is a default region. This component helps to reduce data quantity processed by the server, but the region doesn't influence on the standard submission rules. It means that:

  • The area that is to be submitted onto the server should be embedded in <h:form>/<a4j:form> component.

  • The whole form is submitted on Ajax response and not a region that request is performed from.

Example:


<h:form id="form1">
    <a4j:region>
        <a4j:commandLink reRender="someID" value="Link" id="link1"/>
        <!--..Some content that will be decoded on server after Ajax request.-->
    </a4j:region>
<h:form>

Hence, the <a4j:commandLink> request generation causes full "form1" form submission onto the server, the only difference is that a component tree part decoded on the serve is the part included into the region.

The regions could be nested in any order, the server picks out and decodes only the region, which contains a particular component that sends a request.

Example:


<a4j:region>
    <a4j:commandLink reRender="someID" value="Link" id="link1"/>
    <a4j:region>
        <a4j:commandLink reRender="someID" value="Link" id="link2"/>
        <!--..Some content that will be decoded on server after Ajax request.-->
    </a4j:region >
    <!--..Some content that will be decoded on server after Ajax request.-->
</a4j:region >

Therefore, the external region is decoded for the "link1" and the internal one is decoded for the "link2".

RichFaces allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by "selfRendered" attribute setting to "true" on <a4j:region> and could help considerably speed up a response output. However, this rapid processing could cause missing of transient components that present on view and don't come into a component tree as well as omitting of <a4j:outputPanel> usage described below.

Example:


<a4j:region selfRendered ="true">
    <a4j:commandLink reRender="someID" value="Link" id="link1"/>
    <!--..Some content with HTML used ("br" ,"h1" and other tags used)-->
</a4j:region >

In this case, the processing is quicker and going on without referring to a page code, but the HTML code that isn't saved in a component tree could be lost. Thus, this optimization should be very carefully performed and a usage of the additional components RichFaces ( <a4j:outputPanel> ) is required.

The processing could be also accelerated if a region decoded for the processing passes straight away into Encode. But to update some data out of the region or on another region, use the "renderRegionOnly" attribute set to "false" ("true" on default) to change this behaviour.

Example:


<a4j:region renderRegionOnly="true">
    <a4j:commandLink reRender="someID2" value="Link1" id="link1"/>
    <h:panelGroup id="someId1">
    </h:panelGroup>
</a4j:region>
<a4j:region renderRegionOnly="false">
    <a4j:commandLink reRender="someID1" value="Link2" id="link2"/>
    <h:panelGroup  id="someId1">
    </h:panelGroup>
</a4j:region>

This example shows that one of the regions is decoded when a link is used inside. Nevertheless, if after processing the "link1" is clicked, the first region passes into Encode as a root region and encode performance time is reduced. This optimization doesn't allow data update out of the region and should be implemented very carefully. The data out of the region described with "renderRegionOnly" ="false" is updated successfully.

6.20.5. Relevant resources links

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