JSF Navigation by Examples

[Sergey Smirnov]

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:

Code: Select all

<context-param>
<param-name>javax.faces.CONFIG_FILES</param-name>
      <param-value>/WEB-INF/faces-config-navigation.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:

Code: Select all

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

Code: Select all

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

Code: Select all

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

Code: Select all

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

Code: Select 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>


Code: Select all

<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

Code: Select 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:

Code: Select 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>

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

Code: Select all

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

Code: Select all

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

Code: Select all

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

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

Code: Select all

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

Code: Select all

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

Code: Select all

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

The JSF configuration file contains the following code:

Code: Select all

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

[sanjayb]

Is there any trick to having multiple faces files? I've put 2 faces files in my web.xml file as follows:-

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

seems like whatever I put in my login-faces-config.xml is not getting recognized!

[Sergey Smirnov]

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

Just remove 'application' from the param name. I.e. it should be:

Code: Select all

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

This article was written a long time ago. So, it used to contain the old name. I have corrected it. Thank you for asking.

[sanjayb]

That worked.

[rostanin]

Hello,

I have a problem to solve.

In my project the user can start work with JSF-application from different jsp-pages. Is there any possibility do define a global rule that checks if the user is already logged in and in case if not then forward him to the login page. In other words, if the user is not logged in then only the login page is accessible.

One could do it with scriplets or <jsp:forward>, but is there any legitime solution in JSF navigation for it?

Thank you in advanse,

Best OR.

[Sergey Smirnov]

The default jsf navigation framework does not allow to define such transitions.
However, JSF is pretty extendable architecture. You can write your own NavigationHandler decorator and provide any functionality on the navigation level. Probably, it is not for beginner, but, technicaly speaking, it is not very hard work.

I have written an example that shows the idea:
http://www.jsftutorials.net/jsfNavigation/jsf-login-navigation-redirect.html

[rostanin]

I will try it

[allanctan]

How can I post an action from a hyperlink?

[Nguyen]

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:

Code: Select all

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

Code: Select all

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

Code: Select all

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

Code: Select all

<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.html</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:

Code: Select all

<navigation-rule>
    <from-view-id>/pages/*</from-view-id>
    <navigation-case>
      <from-outcome>info</from-outcome>
      <to-view-id>/menu/generalHelp.html</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.html</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 /help/index.html . For this, we can use either of these two declarations:

Code: Select all

<navigation-rule>
    <from-view-id>*</from-view-id>
    <navigation-case>
      <from-outcome>globalhelp</from-outcome>
      <to-view-id>/menu/generalHelp.html</to-view-id>
    </navigation-case>
  </navigation-rule>
<navigation-rule>
    <navigation-case>
      <from-outcome>globalhelp</from-outcome>
      <to-view-id>/menu/generalHelp.html</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

Code: Select all

<navigation-rule>
   <from-view-id></from-view-id>
    <navigation-case>
      <from-outcome>globalhelp</from-outcome>
      <to-view-id>/menu/generalHelp.html</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:

Code: Select all

<navigation-rule>
    <from-view-id>*</from-view-id>
    <navigation-case>
      <from-outcome>globalhelp</from-outcome>
      <to-view-id>/menu/generalHelp.html</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.html</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:

Code: Select all

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

Code: Select all

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

Code: Select all

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

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

Code: Select all

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

Code: Select all

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

Code: Select all

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

The JSF configuration file contains the following code:

Code: Select all

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

Hello Sergey,
I am trying to passing a parameter to another page, such as product id so that another page can be open for a specific product. Is it possible to define a navigation rule this way:
<to-view-id>/product.jsp?#{backingBean.ProductId}</to-view-id>

If this does not work, do you have any advice for workaround solution?
Thanks in advance,
Nguyen

[Sergey Smirnov]

No. It should not work for sure. If you want to have behaviour exactly like that you have to add your own navigation handler decorator and provide such functionality there. Otherwize, you have to pass the param as usual, i.e., from the previous page.

[Nguyen]

No. It should not work for sure. If you want to have behaviour exactly like that you have to add your own navigation handler decorator and provide such functionality there. Otherwize, you have to pass the param as usual, i.e., from the previous page.

Thanks Sergey.
Just for curiosity, I tried this method last night and it worked. Here is how I did it.
1. create a page with an input field and a command button. The action of this button will determine the navigation to the next page.
2. in the face-config.xml, I add this navigation rule:
<navigation-case>
<from-outcome>newpage</from-outcome>
<to-view-id>/employee/mydetails.jspx?#{ProductId}</to-view-id>
</navigation-case>
3. on mydetails.jspx, I use #{param.ProductId} to get the value.

I don't know if I am breaking any rule here, but it worked.

Cheers,

[Sergey Smirnov]

1. create a page with an input field and a command button.

What is this input field id name? I guess, it is "ProductId". If so, you can remove the #{} from the config file. It does not make sense.

[yuki.yoshida]

Dear Sergey;
Let me make it more clear.

The footnote on the page 7-10 of JSF spec 1.1 says:

It is an error to specify more than one <navigation-case>, nested within one or more <navigation-rule>
elements with the same <from-view-id> matching pattern, that have exactly the same combination of <fromxxx>
element values.

Do you mean this footnote prohibits rule collision only in one configuration file? If these rules are in different files, the rule in the last loading configuration file will be used. Is it OK?

[Sergey Smirnov]

Yuki,
your question sounds like I am an author of the JSF 1.1 specification.
Anyway, the JSF run-time consolidates together faces configuration files located at your application. From this point of view, there is no difference between one file or several files. You should not use the matched fromxxx patterns. The result might be unpredictable and depends of the particular jsf implementation. In the JSF-RI, the latest rule overwrites the previous ones.

[maliba]

can I specify in faces-navigation rules that the destination page will be opened in a new window


I mean , for 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-rule>

Can I specify that greeting.jsp will be opened in a new window ?!! so I will have two windows : one for inputname.jsp and the other for greeting.jsp

thank you!!