Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Navigation Model

> The JavaServer Faces navigation model makes it easy to define page navigation and to handle any additional processing needed to choose the sequence in which pages are loaded.

> As defined by JavaServer Faces technology, navigation is a set of rules for choosing the next page to be displayed after a button or hyperlink is clicked. These rules are defined by the application architect in the application configuration resource file (see Application Configuration Resource File, page 450) using a small set of XML elements.

> To handle navigation in the simplest application, you simply

> - Define the rules in the application configuration resource file.
> - Refer to an outcome `String` from the button or hyperlink component's `action` attribute. This outcome `String` is used by the JavaServer Faces implementation to select the navigation rule.

> The Guess Number example uses this kind of simple navigation. Here is an example navigation rule from the `guessNumber` application described in Defining Page Navigation:

>     <navigation-rule>
>       <from-view-id>/greeting.jsp</from-view-id>
>       <navigation-case>
>         <from-outcome>success</from-outcome>
>         <to-view-id>/response.jsp</to-view-id>
>       </navigation-case>
>     </navigation-rule>

> This rule states that when the button component on `greeting.jsp` is activated, the application will navigate from the `greeting.jsp` page to the `response.jsp` page if the outcome referenced by the button component's tag is `success`. Here is the `commandButton` tag from `greeting.jsp` that specifies a logical outcome of success:

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

> As the example demonstrates, each `navigation-rule` element defines how to get from one page (specified in the `from-view-id` element) to the other pages of the application. The `navigation-rule` elements can contain any number of `navigation-case` elements, each of which defines the page to open next (defined by `to-view-id`) based on a logical outcome (defined by `from-outcome`).

> In more complicated applications, the logical outcome can also come from the return value of an action method in a backing bean. This method performs some processing to determine the outcome. For example, the method can check whether the password the user entered on the page matches the one on file. If it does, the method might return `success`; otherwise, it might return `failure`. An outcome of `failure` might result in the logon page being reloaded. An outcome of `success` might cause the page displaying the user's credit card activity to open. If you want the outcome to be returned by a method on a bean, you must refer to the method using a method expression, using the `action` attribute, as shown by this example:

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

> When the user clicks the button represented by this tag, the corresponding component generates an action event. This event is handled by the default `ActionListener` instance, which calls the action method referenced by the component that triggered the event. The action method returns a logical outcome to the action listener.

> The listener passes the logical outcome and a reference to the action method that produced the outcome to the default `NavigationHandler`. The `NavigationHandler` selects the page to display next by matching the outcome or the action method reference against the navigation rules in the application configuration resource file by the following process:

> 1. The `NavigationHandler` selects the navigation rule that matches the page currently displayed.
> 2. It matches the outcome or the action method reference it received from the default `ActionListener` with those defined by the navigation cases.
> 3. It tries to match both the method reference and the outcome against the same navigation case.
> 4. If the previous step fails, the navigation handler attempts to match the outcome.
> 5. Finally, the navigation handler attempts to match the action method reference if the previous two attempts failed.

> When the `NavigationHandler` achieves a match, the render response phase begins. During this phase, the page selected by the `NavigationHandler` will be rendered.

> For more information on how to define navigation rules, see Configuring Navigation Rules (page 465).

> For more information on how to implement action methods to handle navigation, see Writing a Method to Handle an Action Event (page 411).

> For more information on how to reference outcomes or action methods from component tags, see Referencing a Method That Performs Navigation (page 370).