a4j:region

Component identification parameters

Name | Value
--- | ---
component-type | org.ajax4jsf.AjaxRegion
component-family | org.ajax4jsf.AjaxRegion
component-class | org.ajax4jsf.component.html.HtmlAjaxRegion
renderer-type | org.ajax4jsf.components.AjaxRegionRenderer

## 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>

## Creating the Component Dynamically Using Java

Example:

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

## 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 Sun official documentation.

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" />
    </a4j:region>
    <a4j:region renderRegionOnly="false">
          <a4j:commandLink reRender="someID1" value="Link2" id="link2"/>
    	    <h:panelGroup  id="someId1" />
    </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.

Starting from version 3.2.0 <a4j:region> can be used inside any iterative component (e.g. <rich:column>, <rich:scrollableDataTable>) and just re-render the components from the same row without updating the whole table and without any additional listeners.

Example:

    <rich:column>
           <a4j:region>
                  <a4j:commandLink reRender="out"/>
           </a4j:region>
    </rich:column>
    <rich:column>
            <h:outputText id="out">
    </rich:column>

## Relevant resources links

Visit <a4j:region> demo page at RichFaces live demo for examples of component usage and their sources.

Useful articles:

- <a4j:region> and two <h:inputTexts> in RichFaces cookbook at JBoss portal.