### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.1.4. < a4j:region > available since 3.0.0

expand all

#### 6.1.4.1. Description

The <a4j:region> component specifies the part of the component tree to be processed on server. If no <a4j:region> is defined the whole View functions as a region.

Table 6.6. a4j : region attributes

Attribute Name | Description
--- | ---
ajaxListener | MethodExpression 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
binding | JSF: The attribute takes a value-binding expression for a component property of a backing bean
id | JSF: Every component may have a unique id that is automatically created if omitted
immediate | Flag 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
rendered | JSF: If "false", this component is not rendered
renderRegionOnly | Excludes all the components from the outside of the region from updating on the page on Renderer Response phase. Default value is "false".
selfRendered | if "true", self-render subtree at InvokeApplication ( or Decode, if immediate property set to true ) phase

Table 6.7. 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

#### 6.1.4.2. Creating the Component with a Page Tag

To create the simplest variant of the <a4j:region> component on a page use the following syntax:

    <a4j:region>

          ...

    </a4j:region>

#### 6.1.4.3. Creating the Component Dynamically Using Java

Example:

    import org.ajax4jsf.component.html.HtmlAjaxRegion;

    ...

    HtmlAjaxRegion newRegion = new HtmlAjaxRegion();

    ...

#### 6.1.4.4. Details of Usage

The <a4j:region> component specifies the part of the component tree to be processed on server. The processing includes data handling during decoding, conversion, validation and model update. Note that the whole Form is still submitted but only part taken into region will be processed.

Example:

    <h:form>

          ...

          <a4j:region>

                <a4j:commandLink/>

          </a4j:region>

          ...

    <h:form>

The whole Form on the schematic listing above will be submitted by request invoked with the <a4j:commandLink> . The only part that is going to be processed on the server is enclosed with <a4j:region> and </a4j:region> tags. If no <a4j:region> is defined the whole View functions as a region.

The regions could be nested. Server picks out and decodes only the region, which contains the component that initiates the request.

Example:

    <h:form>

           ...

          <a4j:region>

                <a4j:commandLink value="Link 1" id="link1"/>

                <a4j:region>

                     <a4j:commandLink value="Link 2" id="link2"/>

                </a4j:region >

          </a4j:region>

          ...

    <h:form>

The external region is decoded for `link1` and the internal one is decoded for `link2`.

The "renderRegionOnly" attribute is used when it is necessary to exclude all the components from the outside of the region from updating on the page during Renderer Response phase. Such manipulation allows region to be passed straight into Encode and reduces performance time. This optimization should be implemented carefully because it doesn't allow data from the outside of active region to be updated.

Example:

    <h:form>

           ...

          <a4j:region renderRegionOnly="true">

                <a4j:commandLink value="Link 1" id="link1"/>

          </a4j:region>

           ...

          <a4j:region renderRegionOnly="false">

                <a4j:commandLink value="Link 2" id="link2"/>

          </a4j:region>

           ...

    </h:form>

On the example above the first region only will be updated if `link1` initiates a request. When a request is initiated by `link2` both regions will be updated. In this case search for components to include them into Renderer Response will be performed on the whole component tree.

RichFaces allows setting Ajax responses rendering basing on component tree nodes directly, without referring to the JSP (XHTML) code. This speeds up a response output considerably and could be done by setting the <a4j:region> "selfRendered" attribute to "true". 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 value="Link" id="link"/>

          <!--Some HTML content-->

    </a4j:region>

In this case the processing is quicker and going on without referring to the page code. The HTML code is not saved in a component tree and could be lost. Thus, such optimization should be performed carefully and additional RichFaces components usage (e.g. <a4j:outputPanel> ) is required.

Starting from RichFaces 3.2.0 the <a4j:region> can be used together with iterative components (e.g. <rich:column> or <rich:scrollableDataTable> , etc.). It became possible to re-render a particular row in a table 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>

In most cases there is no need to use the <a4j:region> as `ViewRoot` is a default one.

#### 6.1.4.5. Relevant resources links

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

Useful articles and examples:

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

- "A sad story about UIInput" at personal blog of I.Shabalov and exhaustive example of solving the problem with the help of <a4j:region> .

- Prev6.1.3. < a4j:form > a...
- Top of page
- Front page
- Next6.1.5. < a4j:support > ...