The a4j:region tag in RichFaces is probably one of the most misunderstood tags, but it provides one of the most important features in RichFaces. With it, server-side processing can be limited to only certain designated components.

One reason for misunderstanding could be the tag name. Many believe that the region tag limits what is rendered in the JSF component tree (to the browser). However, it’s used for the opposite purpose, to mark areas on the JSF component tree to be processed on the server during the Apply Request Values, Process Validations, and Update Model Values phases. Maybe “processRegion” would have been a better name, but we will just deal with what we have.

Before we continue, I want to thank Nick Belaevski (RichFaces project lead and co-author of RichFaces DZone Refcard, Exadel) and Charley Cowens (Technical Writer, Exadel) for helping edit this article.

An Example
Let’s see how the tag works in an example. Suppose there are five input components on a page. Also suppose that you only need one or two of them to be processed on the server. While we cannot change how the form is submitted (all five input field will be submitted), we can control which components will be processed on the server. Components that are not processed on the server, will not be validated and will not be pushed on to the model (during the Update Model phase).

Suppose there is the following page:

<h:form>
     <h:panelGrid>
  	<h:inputText id="input1" >
  		<a4j:support event="onblur"/>
  	</h:inputText>
  	<h:inputText id="input2" >
  		<a4j:support event="onblur"/>
  	</h:inputText>
  	<h:inputText id="input3" >
  		<a4j:support event="onblur"/>
  	</h:inputText>
    </h:panelGrid>
</h:form>

By default the entire page is a region. Thus a request sent from any of the input fields will process the entire form.

Suppose we only need to process the input1 component. To do that, we can put the component inside an a4j:region tag:

<h:panelGrid>
   <a4j:region>
      <h:inputText id="input1">
	<a4j:support event="onblur" />
      </h:inputText>
   </a4j:region>
   <h:inputText id="input2">
	<a4j:support event="onblur" />
   </h:inputText>
   <h:inputText id="input3">
	<a4j:support event="onblur" />
   </h:inputText>
</h:panelGrid

In this case, if input1 triggers the submit, only input1 will be processed on the server even though the whole form will still be submitted.

It’s also possible to nest regions:

<h:panelGrid>
   <a4j:region>
	<a4j:region>
   <h:inputText id="input1">
	<a4j:support event="onblur" />
   </h:inputText>
   </a4j:region>
	<h:inputText id="input2">
		<a4j:support event="onblur" />
	</h:inputText>
   </a4j:region>
   <h:inputText id="input3">
	<a4j:support event="onblur" />
   </h:inputText>
</h:panelGrid>

In this example, if a request is fired by component input1 (Input components don’t actually fire events. The event is fired by a4j:support), then only the immediate region will be processed on the server. If component input2 fires the event, then both, input1 and input2 will be processed. If component input3 fires the event, as it belongs to the default region that wraps the entire page, all three inputs will be processed.

When using a4j:region with an action component, only the action and listeners registered on this component will be invoked on the server:

Using renderRegionOnly attribute with a4j:region
The a4j:region tag comes with an important attribute called renderRegionOnly which can be set to true or false (false by default). This attribute limits any re-rendering to the current region only. Let’s take this code snippet as an example:

<h:panelGrid columns="2">
   <h:outputText value="Name:" />
	<h:panelGroup>
		<h:inputText id="name" value="#{bean.name}" required="true"
			 requiredMessage="Name is required" 
                         validatorMessage="Must be 3 characters or longer">
			<a4j:support event="onblur" />
			<f:validateLength minimum="3" />
		</h:inputText>
	            <rich:message for="name" />
            </h:panelGroup>
	<h:outputText value="Age:" />
	<h:panelGroup>
		<h:inputText id="age" value="#{bean.age}" size="4" required="true"
		   requiredMessage="Age is required" 
                   validatorMessage="Invalid age">
		     <a4j:support event="onblur" />
		     <f:validateLongRange minimum="0" />
		</h:inputText>
		<rich:message for="age" />
	</h:panelGroup>
</h:panelGrid>

When you tab out or click out (onblur event) from the first input field without entering anything or entering invalid input (as shown), the entire form is submitted and both fields are validated. Both fields are processed and validated because by default the whole page is a region. That’s not exactly the behavior that we want.

We don’t want to validate fields for which the user hasn’t had a chance to enter anything. Placing each input and message tag inside a region will restrict processing to the region from which the request was sent.

<h:panelGroup>
   <a4j:region>
	<h:inputText id="name" value="#{bean.name}" required="true"
		requiredMessage="Name is required" 
                validatorMessage="Must be 3 characters or longer">
		<a4j:support event="onblur" />
		<f:validateLength minimum="3" />
	</h:inputText>
	<rich:message for="name" />
      </a4j:region>
</h:panelGroup>
 
<h:outputText value="Age:" />
<h:panelGroup>
   <a4j:region>
	<h:inputText id="age" value="#{bean.age}" size="4" required="true"
		requiredMessage="Age is required" 
                validatorMessage="Invalid age">
			<a4j:support event="onblur" />
			<f:validateLongRange minimum="0" />
	</h:inputText>
	<rich:message for="age" />
   </a4j:region>
</h:panelGroup>

While we solved the problem of only processing the field which fired the event, we now run into another problem.

1. Place the mouse cursor inside the name field
2. Without entering anything (or entering less than 3 characters), leave the field and place the mouse in the age field
3. An error is displayed next to the name field as expected (only this field is processed)
   
4. Enter a negative number in the age field and leave the field
5. An error is displayed next to the age field (as expected). However, the error message next to the name field gets cleared (not expected)
   

What happened? First, JSF error messages are request-scoped. Secondly, rich:message works just like h:message, but the component is always rendered, whether there is an error or not.

So, how are these two related? When the age field fired an event, only the age field was processed. As the name field wasn’t processed, no error message was queued and the old one is now gone as this is a new request. Because we used rich:message , an empty string value (or empty error) replaced the original error message in the browser.

To help us solve this, we are going to use the renderRegionOnly attribute. For both a4j:region tags, we are setting renderRegionOnly=”true”:

...
<h:panelGroup>
 <a4j:region renderRegionOnly="true">
   <h:inputText id="name" value="#{bean.name}" required="true"
	requiredMessage="Name is required" 
        validatorMessage="Must be 3 characters or longer">
	<a4j:support event="onblur" />
	<f:validateLength minimum="3" />
   </h:inputText>
 <rich:message for="name" />
 </a4j:region>
</h:panelGroup>
...
...
<h:panelGroup>
   <a4j:region renderRegionOnly="true">
	<h:inputText id="age" value="#{bean.age}" 
                 size="4" required="true"
		requiredMessage="Age is required" 
                validatorMessage="Invalid age">
	   <a4j:support event="onblur" />
	   <f:validateLongRange minimum="0" />
	 </h:inputText>
	 <rich:message for="age" />
   </a4j:region>
</h:panelGroup>

This means that any re-rendering is limited to the region from which the request was fired. When we leave the age field without entering anything, the name error is not cleared as we just limited updating to the current region (the region in which age field is).

The desired result is achieved: both error messages are displayed:

One thing to keep in mind, setting renderRegionOnly=”true” doesn’t define what to re-render, it only limits the updates to the current region. What to re-render is determined by rich:message

Using renderRegionOnly allows the creation of a true AJAX region on a page – meaning all input for processing on the server and all output for re-rendering is limited to this particular region.

Using ajaxSingle attribute

A closely related feature to the region is ajaxSingle attribute. The attribute can be applied to just one component while a4j:region can contain any number of components.

<a4j:region>
   <a4j:commandButton action="#{bean.save}" value="Click Me"/>
</a4j:region>
 
Is the same as:
<pre lang="xml">
<a4j:commandButton action="#{bean.save}" value="Click Me" ajaxSingle="true">

And this:

<a4j:region>
    <h:inputText id="age" value="#{bean.city}">
		<a4j:support event="onblur" />
   </h:inputText>
</a4j:region>

Is the same as this:

<h:inputText id="age" value="#{bean.city}">
   <a4j:support event="onblur" ajaxSingle="true"/>
</h:inputText>

Using process attribute

Another important attribute is process. It’s available on all RichFaces components that fire an AJAX request and is used in conjunction with ajaxSingle. When ajaxSingle is set to true, we know that only this component will be processed. A situation might arise where you still need to process some specific other components on the page in addition. The process attribute points to those components or containers.

<h:inputText>
   <a4j:support event="onblur" ajaxSingle="true" process="mobile"/>
</h:inputText>
...
<h:inputText id="mobile"/>

process can also point to an EL expression or container component id in which case all components inside the container will be processed:

Summary
Partial tree processing is one of the key concepts in RichFaces, so make sure you understand it. Another core concept is partial tree rendering and more specifically rendering content not previously rendered. You can read about it here.

One thing to keep in mind is that regions only work in the context of an AJAX request. Regions don’t work with a non-AJAX request.