logo
Home Article

JSF Navigation by Examples


The JavaServer Faces (JSF) Navigation Framework provides navigation rules that allow you to define navigation from view to view (mostly JSP pages) in a Web application. These navigation rules are defined in JSF configuration files along with other definitions for a JSF application. Usually, this file is named faces-config.xml. However, you can assign any other name and even use more than one file to store JSF configuration data. To specify configuration files, use lines like the following in your web.xml file:

<context-param> 
<param-name>javax.faces.CONFIG_FILES</param-name> 
      <param-value>/WEB-INF/faces-config.xml,/WEB-INF/faces-beans.xml</param-value> 
</context-param> 

A Simple Example

The actual construction of a navigation rule is quite simple. Letís look at our first example:

<navigation-rule> 
    <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/greeting.jsp</to-view-id> 
    </navigation-case> 
    <navigation-case> 
      <from-outcome>sayGoodbye</from-outcome> 
      <to-view-id>/pages/goodbye.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule>  
  

This code specifies that view /pages/inputname.jsp has two outputs, sayHello and sayGoodbye, associated with particular pages.

Making a Default Outcome Case

The basic construction is simple, but there are many variations you can do on the basic construction. Look at the next snippet:

<navigation-rule> 
   <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/greeting.jsp</to-view-id> 
    </navigation-case> 
    <navigation-case> 
      <to-view-id>/pages/goodbye.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule>  
  

This code is very similar to the previous example, except that the from-outcome element for the second navigation-case is missing. This means that all outcomes except sayHello, will be forwarded to /pages/goodbye.jsp

Using Patterns

The JSF navigation model allows us to use patterns. These patterns consist of a string ending in an asterisk "*". This is shown in the next example:

<navigation-rule> 
    <from-view-id>/pages/*</from-view-id> 
    <navigation-case> 
      <from-outcome>menu</from-outcome> 
      <to-view-id>/menu/main_main.jsp</to-view-id> 
    </navigation-case> 
    <navigation-case> 
      <from-outcome>info</from-outcome> 
      <to-view-id>/menu/info.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

This navigation rule will be applied for any page like /pages/exit.jsp that has /pages/ as the beginning of the URL. Note that the asterisk must be located at the end. For example, a pattern such as /pages/*.jsp would not work.

Resolving More Than One Matching Rule

Now letís pay more attention to how rules can be specified in the JSF navigation model. Look at this next example:

<navigation-rule> 
    <from-view-id>/pages/*</from-view-id> 
    <navigation-case> 
      <from-outcome>info</from-outcome> 
      <to-view-id>/menu/generalHelp.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

  <navigation-rule> 
    <from-view-id>/pages/login.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>info</from-outcome> 
      <to-view-id>/menu/loginHelp.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

In this example, the second navigation rule, not the first rule, will work for outcomes from /pages/login.jsp even though it is also matched by the pattern /pages/* in the first rule. The most specific match of from-view-id always takes precedence for a particular from-outcome.

"Global" Outcomes

Letís say we want the globalHelp outcome from any page to always cause a transition to the page /menu/generalHelp.jsp . For this, we can use either of these two declarations:

<navigation-rule> 
    <from-view-id>*</from-view-id> 
    <navigation-case> 
      <from-outcome>globalhelp</from-outcome> 
      <to-view-id>/menu/generalHelp.jsp</to-view-id> 
    </navigation-case> 
</navigation-rule> 

<navigation-rule> 
    <navigation-case> 
      <from-outcome>globalhelp</from-outcome> 
      <to-view-id>/menu/generalHelp.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

The first snippet uses an asterisk for the from-view-id element, while the second snippet doesnít use a from-view-id element at all. Both approaches work the same. Note though, that an empty from-view-id element, as displayed in the snippet below, will not work at all

<navigation-rule> 
   <from-view-id></from-view-id> 
    <navigation-case> 
      <from-outcome>globalhelp</from-outcome> 
      <to-view-id>/menu/generalHelp.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

Collision of Rules

Here is an interesting question. What happens when a couple of navigation rules that have the same from-view-id and the same from-outcome point to different pages. Look at the next example:

<navigation-rule> 
    <from-view-id>*</from-view-id> 
    <navigation-case> 
      <from-outcome>globalhelp</from-outcome> 
      <to-view-id>/menu/generalHelp.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

<navigation-rule> 
    <from-view-id>*</from-view-id> 
    <navigation-case> 
      <from-outcome>globalhelp</from-outcome> 
      <to-view-id>/pages/goaway.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

The last rule is always used in such a situation. Also, remember, we spoke at the very beginning of this article about the possibility of splitting JSF configuration data into several files. In the case where the competing rules are in different configuration files, the rule in the last loading configuration file as listed in the web.xml file prevails.

Spreading Out Parts of a Navigation Rule

This is one more variation on the same theme. Compare the following snippets:

<navigation-rule> 
    <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/greeting.jsp</to-view-id> 
    </navigation-case> 
    <navigation-case> 
      <from-outcome>sayGoodbye</from-outcome> 
      <to-view-id>/pages/goodbye.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 
<navigation-rule> 
    <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/greeting.jsp</to-view-id> 
    </navigation-case> 
<navigation-rule> 
... 
... 
<navigation-rule> 
    <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayGoodbye</from-outcome> 
      <to-view-id>/pages/goodbye.jsp</to-view-id> 
    </navigation-case> 

Both snippets produce the same result at run-time. However, the second snippet shows that the declaration can be arbitrarily split up and spread out into different parts of a configuration file or even different configuration files. You can use either approach based on your own preferences.

Navigation Rules in Action

Now, it is time to lift the veil a little to see how what weíve learned can be put to use in an application. A JSP page might contain the following line:

<h:commandButton id="submit" action="sayHello" value="Submit" /> 

The action attribute will be used as an outcome. Or, here is another variation:

<h:commandButton id="submit" action="#{GetNameBean.helloAction}" value="Submit" /> 

This means that the helloAction method of GetNameBean will be invoked and the result will be used as an outcome. helloAction should be a public method that returns String. This distinction between two ways of specifying the action attribute is significant in considering an element in the configuration file we havenít looked at yet. This is the from-action element. Look at the following code:

  <navigation-rule> 
   <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/anotherhello.jsp</to-view-id> 
    </navigation-case> 
    <navigation-case> 
      <from-action>#{GetNameBean.helloAction}</from-action> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/pages/hello.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule>  

In this code, both navigation cases have the same from-view-id and from-outcome, however the second navigation case includes a from-action element. If the sayHello outcome is determined by GetNameBean.helloAction, the second navigation case will take effect, but only because otherwise both cases had equal precedence.

Review

Letís check how well you understand the material. The page /pages/inputname.jsp has the following declaration for commandButton:

<h:commandButton id="submit" action="#{GetNameBean.helloAction}" value="Submit" /> 

The JSF configuration file contains the following code:

<navigation-rule> 
   <from-view-id>/pages/inputname.jsp</from-view-id> 
    <navigation-case> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/a.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule> 

<navigation-rule> 
   <from-view-id>/pages/*</from-view-id> 
    <navigation-case> 
      <from-action>#{GetNameBean.helloAction}</from-action> 
      <from-outcome>sayHello</from-outcome> 
      <to-view-id>/b.jsp</to-view-id> 
    </navigation-case> 
  </navigation-rule>  

If the submit button mentioned above is pressed, what will the next page /a.jsp or /b.jsp if GetNameBean.helloAction returns sayHello?

See Also:

JSF Navigation Handler Decorator


Extending the standard navigation mechanism used in the JSF.

How to do Smart Navigation Handler in JSF


Now itís really time to make smart navigation system.