RichFaces region – partial JSF tree processing

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:


     
  	
  		
  	
  	
  		
  	
  	
  		
  	
    

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

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:


   
	
   
	
   
   
	
		
	
   
   
	
   

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:


   
	
		
			
			
		
	            
            
	
	
		
		     
		     
		
		
	

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.

regiontag1

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.


   
	
		
		
	
	
      




   
	
			
			
	
	
   

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)
    regiontag2
  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)
    regiontag3

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”:

...

 
   
	
	
   
 
 

...
...

   
	
	   
	   
	 
	 
   

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:
regiontag4

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.


   


Is the same as:

And this:


    
		
   

Is the same as this:


   

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.


   

...

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.

RichFaces training and support

Exadel offers custom on-site RichFaces training. Get your entire team up to speed in just 1-2 days (info, outline). Exadel also offers RichFaces support.

17 thoughts on “RichFaces region – partial JSF tree processing

  1. Superb, richfaces internal & tips & tricks. We were struggling with situation like these, but can’t figure out exactly what happening….

    Simply, its rich faces’s so powerful & strong features… I really appreciate the to the point & technical article…. Thanks Max

  2. Hello …
    Could process attribute be used in conjunction with a region tag ? …
    somthing like an a4j button that is placed into a region (ajaxSingle is not set ) and make use of the process attribute …
    thx a lot

  3. Another very informative blog posting, Max. Thanks.

    You say “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.”

    What is the difference between form submission and component processing? I assume components that are processed go through all phases of the JSF lifecycle. What happens to components that are merely submitted, but not processed?

  4. Hi, I can’t see any code, just a gray box… I tried to read your article in differents browsers, but it isn’t possible to see the code.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s