Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 9.2 Creating Navigation Rules

With JavaServer Faces, navigation between application pages is defined by a set of rules. Navigation rules determine the next page to display when a user clicks a navigation component, such as a button or a hyperlink.

A navigation rule defines the navigation from one page to one or more other pages. Each navigation rule can have one or more cases, which define where a user can go from that page. For example, if a page has links to several other pages in the application, you can create a single navigation rule for that page and one navigation case for each link to the different pages. The rule itself can define the navigation from:

- A specific JSF page

- All pages whose paths match a specified pattern, such as all the pages in one directory, which is called a pattern-based rule

- All pages in an application, which is called a global navigation rule

## 9.2.1 How to Create Page Navigation Rules

Navigation rule definitions are stored in the JSF configuration file (`faces-config.xml`). You can define the rules directly in the configuration file, or you can use the JSF Navigation Modeler and the JSF Configuration Editor in JDeveloper. Oracle recommends that you use the navigation modeler and the configuration editor, because these tools:

- Provide a GUI environment for modeling and editing the navigation between application pages

- Enable you to map out your application navigation using a visual diagram of pages and navigation links

- Update the `faces-config.xml` file for you automatically

Use the navigation modeler to initially create navigation rules from specific pages to one or more other pages in the application. Use the configuration editor to create global or pattern-based rules for multiple pages, create default navigation cases, and edit navigation rules.

### 9.2.1.1 About Navigation Rule Elements

Understanding the elements that define a navigation rule in the `faces-config.xml` file helps when creating rules using the navigation modeler and the configuration editor, or directly in the configuration file. The general syntax of a JSF navigation rule element in the `faces-config.xml` file is shown in Example 9-1.

Example 9-1 JSF Navigation Rule Syntax in the faces-config.xml File

    <navigation-rule>
      <from-view-id>page-or-pattern</from-view-id>
      <navigation-case>
        <from-action>action-method</from-action>
        <from-outcome>outcome</from-outcome>
        <to-view-id>destination-page</to-view-id>
        <redirect/>
      </navigation-case>
      <navigation-case>
        ...
      </navigation-case>
    </navigation-rule>

A navigation rule can consists of the following elements:

- `<navigation-rule>`: The wrapper element for the navigation cases.

- `<from-view-id>`: Contains either the complete page identifier (the context sensitive relative path to the page) or a page identifier prefix ending with the asterisk (*) wildcard character. If you use the wildcard character, the rule applies to all pages that match the wildcard pattern. To make a global rule that applies to all pages, leave this element blank.

- `<navigation-case>`: The wrapper element for each case in the navigation rule. Each case defines the different navigation paths from the same page.

- `<from-action>`: An optional element that limits the application of the rule only to outcomes from the specified action method. The action method is specified as an EL binding expression. For example, `#{backing_SRCreate.cancelButton_action}`. JDeveloper displays a list of valid binding expressions from which you can choose.

- `<from-outcome>`: Contains an outcome value that is matched against values specified in the `action` attribute of UI components. Later you will see how the outcome value is referenced in a UI component either explicitly or dynamically through an action method return.

- `<to-view-id>`: Contains the complete page identifier of the page to which the navigation is routed when the rule is implemented.

- `<redirect/>`: An optional element that indicates that the new view is to be requested through a redirect response instead of being rendering as the response to the current request. This element requires no value. (For more information, see Section 9.2.2, "What Happens When You Create a Navigation Rule".)

### 9.2.1.2 Using the Navigation Modeler to Define Navigation Rules

As a starting point for creating navigation rules, use JDeveloper's JSF Navigation Modeler. The navigation modeler is a visual modeling tool for creating application pages and navigation cases for those pages.

After creating the basic navigation rules using the navigation modeler, you can edit the rules in the JSF Configuration Editor or directly in the navigation modeler.

To define a navigation rule for a specific page using the JSF Navigation Modeler:

1. In the Application Navigator, double-click the `faces-config.xml` file located in the `WEB-INF` directory to display the configuration file in the visual editor.

2. In the visual editor, activate the Diagram tab to display the navigation modeler, as shown in Figure 9-1.

   Notice that the Component Palette automatically displays the JSF Navigation Modeler components.

   Figure 9-1 Navigation Modeler

3. Add application pages to the diagram using one of the following techniques:

   - To create a new page, drag JSF Page from the Component Palette onto the diagram. Double-click the page icon on the diagram to display the Create JSF JSP wizard where you can name and define the page characteristics.

   - To add an existing page to the diagram, drag the page from the Application Navigator onto the diagram.

   Tip: You can view a thumbnail of the entire diagram by clicking the Thumbnail tab in the Structure window.

4. Create the navigation cases between the pages using the following technique:

   - In the Component Palette, select JSF Navigation Case.

   - On the diagram, click the icon for the source page, then click the icon for the destination page.

     JDeveloper draws the navigation case on the diagram as a solid line ending with an arrow between the two pages, as shown in Figure 9-2.

     Figure 9-2 Navigation Case

     The arrow indicates the direction of the navigation case. A default `from-outcome` value is shown as the label on the arrow. JDeveloper automatically creates the navigation rule for the source page and adds a default navigation case that references the destination page. If a page is the source for multiple navigation cases (for example, a page that provides links to several other pages), JDeveloper creates one rule for the source pages and adds the multiple cases to that rule.

5. In the diagram, double-click the arrow representing the navigation case to display the navigation-case Properties dialog, shown in Figure 9-3.

   Figure 9-3 The navigation-case Properties Dialog

6. Use the navigation-case Properties dialog to define the elements in the navigation case. For a description of each element, see Section 9.2.1.1, "About Navigation Rule Elements".

### 9.2.1.3 Using the JSF Configuration Editor

Once you have defined your basic navigation between specific pages, you can use the JSF Configuration Editor to:

- Define pattern-based navigation rules for a group of pages.

  For example, if a group of pages in your application have a set of common links, such as the links from a menu bar, you can create a pattern-based rule that applies to all the pages. You identify the pages affected by the rule using a wildcard pattern, where the wildcard character (*) must be the last item in the pattern. A typical use of patterns in JSF navigation rules is to identify all the pages in a certain directory. Example 9-2 shows a sample of a pattern-based navigation rule. Notice that the `from-view-id` element contains a pattern instead of a specific page name. This pattern would cause the rule to apply to all pages in the `management` directory whose names start with SR.

  Example 9-2 Pattern-Based Navigation Rule

      <navigation-rule>
        <from-view-id>/app/management/SR*</from-view-id>
        ...
      </navigation-rule>

- Define global navigation rules that apply to all pages.

  For example, an application could define one rule that applies to all pages and returns users to the application's home page. When you create a global rule, you exclude the `from-view-id` element, which causes the rule to apply to all pages. You can optionally include a `from-outcome` element, if you want to apply the rule whenever a UI component on any page returns a specific outcome. Example 9-3 shows a sample global navigation rule. It causes the home page to be displayed when any component on any page returns the value `gohome`.

  Example 9-3 Global Navigation Rule

      <navigation-rule>
        <navigation-case>
          <to-view-id>home.jsp</to-view-id>
          <from-outcome>gohome</from-outcome>
        </navigation-case>
      </navigation-rule>

- Define default navigation cases in which no outcome is specified.

  For example, if a navigation component is defined using a dynamic outcome (where the outcome could be one of multiple values), you may want to create a navigation case for one or two specific outcomes and a default case for all other possible outcomes. This way, if a navigation component returns an unexpected outcome, the page navigates to a specific page. Example 9-4 shows a sample default navigation rule. It displays the home page whenever any component on any page returns an outcome that is not handled by any other navigation case.

  Tip: Default navigation cases do not apply if a component specifies a `null` value in the `action` attribute. In this case, no navigation occurs; instead, the same page is redisplayed.

  Example 9-4 Default Navigation Rule

      <navigation-rule>
        <navigation-case>
          <to-view-id>home.jsp</to-view-id>
        </navigation-case>
      </navigation-rule>

- Edit existing rules and cases.

To create a navigation rule using the JSF Configuration Editor:

1. In the Application Navigator, double-click the `faces-config.xml` file located in the `WEB-INF` directory to display the configuration file in the visual editor.

2. In the visual editor, activate the Overview tab to display the configuration editor.

3. From the element list (in the left corner), select Navigation Rules, as shown in Figure 9-4.

   Figure 9-4 Configuration Editor

4. Define the navigation rule using the following technique:

   - Click the New button to the right of the Navigation Rules box to display the Create Navigation Rule dialog.

   - Use the Create Navigation Rule dialog to specify the `from-view-id` element of the navigation rule using one of the following techniques:

     - To create a rule for a single page, enter a fully qualified page name or select a page from the dropdown list.

     - To create a pattern-based rule that applies to a group of pages whose names match the pattern, enter a pattern that uses the asterisk (*) wildcard character. You must use the wildcard character at the end of the pattern. For example, the pattern `/app/management/SR*` would cause the rule to apply to all pages in the management directory whose names start with SR. A typical use of patterns in JSF navigation rules is to identify all the pages in a certain directory.

     - To create a global navigation rule that applies to all pages in the application, select <Global Navigation Rule> from the dropdown list. This causes the `from-view-id` element to be excluded from the `faces-config.xml` file.

       Tip: When defining a global navigation rule, you can exclude the `from-view-id` element. However, for the sake of clarity in the `faces-config.xml` file, you may want to specify the value as `<from-view-id>``*` `</from-view-id>` or <from-view-id>`/*``</from-view-id>`, with the former being the preferred approach. All of these styles produce the same result—the rule is applied to all pages in the application.

     When you finish, the new navigation rule appears in the navigation rules in the configuration editor.

5. Define the navigation cases using the following technique:

   - In the list of navigation rules, select the rule to which you want to define navigation cases.

   - Click the New button to the right of the Navigation Cases box to display the Create Navigation Case dialog.

   - Use the Create Navigation Case dialog to specify the elements of the navigation case, which were previously described in Section 9.2.1.1, "About Navigation Rule Elements".

     You must supply a to-view-id value, to identify the destination of the navigation case, but can leave either or both the from-action and from-outcome elements empty. If you leave the from-action element empty, the case applies to the specified outcome regardless of how the outcome is returned. If you leave the from-outcome element empty, the case applies to all outcomes from the specified action method, thus creating a default navigation case for that method. If you leave both the from-action and the from-outcome elements empty, the case applies to all outcomes not identified in any other rules defined for the page, thus creating a default case for the entire page.

     Tip: If you have already defined the outcome values in the navigation components on the page, make sure you enter the `from-outcome` value exactly the same way, including lowercase and uppercase letters.

## 9.2.2 What Happens When You Create a Navigation Rule

When you create a navigation rule using the JSF Navigation Modeler or the JSF Configuration Editor, JDeveloper automatically adds the navigation rule elements to the `faces-config.xml` file for you.

When JDeveloper first creates an empty `faces-config.xml` file, it also creates a diagram file (`faces.config.oxd_faces`) to hold diagram details such as layout and annotations. JDeveloper always maintains this diagram file alongside the `faces-config.xml` file, which holds all the settings needed by your application. This means that if you are using versioning or source control, the diagram file is included as well as the `faces-config.xml` file it represents.

Example 9-5 shows a navigation rule defined in the `faces-config.xml` file for the SRCreate page in the SRDemo application. This rule defines two cases. The first case defines an outcome that navigates to a dialog.

Typically, you manage the navigation into a dialog by defining a standard JSF navigation rule with a special `dialog:` outcome, which indicates that the page in the `to-view-id` element should be launched as a dialog. For more information about creating dialogs, see Section 11.3, "Using Popup Dialogs". The second case defines a navigation where the `SRCreateConfirm` page is displayed when the outcome specified by the `action` is `Confirm`.

Example 9-5 Navigation Rule for a Specific Page

    <navigation-rule>
        <from-view-id>/SRCreate.jspx</from-view-id>
        <navigation-case>
          <from-outcome>dialog:FAQ</from-outcome>
          <to-view-id>/SRFaq.jspx</to-view-id>
        </navigation-case>
        <navigation-case>
          <from-outcome>Confirm</from-outcome>
          <to-view-id>/SRCreateConfirm.jspx</to-view-id>
        </navigation-case>
    </navigation-rule>

Example 9-6 shows another navigation rule defined in the SRDemo application. The rule uses the wildcard character in the `from-view-id` element, which causes the rule to apply to all pages. The cases defined in this global rule handle the navigation from the standard menu displayed on all of the pages.

In the example, some of the cases use the `redirect` element. The `redirect` element causes JSF to send a redirect response that asks the browser to request the new page. When the browser requests the new page, the URL shown in the browser's address field is adjusted to show the actual URL for the new page. If a navigation case does not use the `redirect` element, the new page is rendered as a response to the current request, which means that the URL in the browser's address field does not change and that it will contain the address of the previous page. Direct rendering can be faster than redirection.

Any navigation case can be defined as a redirect. To decide whether to define a navigation case as a redirect, consider the following factors:

- If you do not use redirect rendering, when a user bookmarks a page, the bookmark will not contain the URL of the current page; instead, it will contain the the address of the previous page.

- If a user reloads a page, problems may arise if the URL is not refreshed to the new view. For example, if the page submits orders, reloading the page may submit the same order again. If any harm might result from not refreshing the URL to the new view, define the navigation case as redirect.

Example 9-6 Navigation Rule Defined with Redirect Rendering

    <navigation-rule>
        <from-view-id>*</from-view-id>
        <navigation-case>
          <from-outcome>GlobalHome</from-outcome>
          <to-view-id>/app/SRList.jspx</to-view-id>
          <redirect/>
        </navigation-case>
        <navigation-case>
          <from-outcome>GlobalSearch</from-outcome>
          <to-view-id>/app/staff/SRSearch.jspx</to-view-id>
        </navigation-case>
        <navigation-case>
          <from-outcome>GlobalCreate</from-outcome>
          <to-view-id>/app/SRCreate.jspx</to-view-id>
        </navigation-case>
        <navigation-case>
          <from-outcome>GlobalManage</from-outcome>
          <to-view-id>/app/management/SRManage.jspx</to-view-id>
          <redirect/>
        </navigation-case>
        <navigation-case>
          <from-outcome>GlobalLogout</from-outcome>
          <to-view-id>/app/SRLogout.jspx</to-view-id>
          <redirect/>
        </navigation-case>
        <navigation-case>
          <from-outcome>dialog:GlobalContact</from-outcome>
          <to-view-id>/app/SRContact.jspx</to-view-id>
        </navigation-case>
    </navigation-rule>

## 9.2.3 What Happens at Runtime

The JSF default implementation reads the navigation rules in the `faces-config.xml` file and calls the `NavigationHandler` class, which evaluates the navigation rules and determines which page to display. Knowing how the navigation rules are evaluated can help in debugging navigation issues.

When evaluating which navigation rules to execute, the navigation handler looks at three things:

- The ID of the current page.

- The action method used to handle the link.

- The outcome string value of the `action` attribute, or the string returned by the action method.

The navigation handler evaluates navigation outcomes and rules in the following manner:

1. If the outcome returned by an action method is `null`, it returns immediately and redisplays the current page.

2. It merges all navigation rules with the same `from-view-id` value.

3. If a rule exists whose `from-view-id` value matches the view ID exactly, it uses that rule.

4. It evaluates all pattern-based navigation rules, and determines whether the prefix (the section before the wildcard character) is identical to the corresponding prefix of the ID of the current view.

5. If there are matching rules, it uses the rule whose matching prefix is longest. If there is a rule without a `from-view-id` element, it uses that rule.

6. If there is no match at all, it redisplays the current page.

Because the navigation handler merges navigation rules with matching `from-view-id` values, there may be several navigation cases from which to choose. After determining the correct navigation rule, the navigation handler evaluates which case to use based on a prioritized set of criteria. If no case meets one criteria, the next criteria is applied until either a case is found or all criteria have been evaluated. The case evaluation criteria is as follows (shown in order of priority):

1. If both the `from-outcome` and `from-action` values of a case match the current action method and `action` value, it uses that case.

2. If a case has no from-action element, but the `from-outcome` value matches the current `action` value, it uses that case.

3. If a case has no `from-outcome` element, but the `from-action` value matches the current action method``, it uses that case.

4. If there is a case with neither a `from-outcome` element nor a `from-action` element, it uses that case.

5. If no case meets any of the criteria, it redisplays the current page.

Tip: When you are using ADF bindings in a page's UI components, the rowset iterators keep track of the current row. If a user clicks the browser's Back button instead of using the page's navigation buttons, the iterator becomes out of sync with the page displayed because the iterator has been bypassed. For more information about what happens when a user clicks the browser back button, see Section 6.4.4, "What You May Need to Know About the Browser Back Button".

## 9.2.4 What You May Need to Know About Navigation Rules and Cases

In addition to the basic navigation rules that have been discussed, you can define navigation rules in more than one JSF configuration file or define rules that overlap. You can also define overlapping navigation cases and cases that are split among different rules.

### 9.2.4.1 Defining Rules in Multiple Configuration Files

If your application uses more than one JSF configuration file, JSF finds and loads your application's configuration settings in a predefined order. (For a description of how the configuration settings are evaluated, see Chapter 4, "Getting Started with ADF Faces".)

Usually, the navigation rules in each JSF configuration file are concerned with navigation between the pages only in a specific area of the application. However, it is possible to specify rules in any of the JSF configuration files to apply to any pages in the application. In particular, each JSF configuration file may define rules for some general navigation features, such as returning to the home page or displaying help information. In such a scenario, when a navigation event arises at runtime, the rules from all the JSF configuration files are considered together.

### 9.2.4.2 Overlapping Rules

Through the use of global or pattern-based rules, it is possible to define a hierarchy of overlapping rules.

Defining a hierarchy of rules ensures that particular navigation cases are directed to specific pages, and that general cases, such as clicking a Home button or a Help button, are handled in the same way across the whole application.

For example, you could create a hierarchy of rules by defining the `from-view-id` values as follows:

- `/products/select.jsp` to apply a rule to one page only

- `/product/*` to apply a rule to all pages in the product directory, including the page covered by the first rule

- `/*` to apply to all pages, including the ones covered by the previous two rules

Overlapping rules can be defined in a single rule or in multiple rules. When a user clicks a link, the more specific case is considered first, then the more general case.

### 9.2.4.3 Conflicting Navigation Rules

Because you can define several navigation rules for the same page, it is possible to define rules that conflict with one another. Also, because navigation rules can be defined in more than one JSF configuration file, similar rules may be defined in different files. Example 9-7 shows an example of conflicting rules in the same configuration file.

If there is a conflict in which two or more cases have the same `from-view-id`, `from-action`, and `from-outcome` values, the last case (as they are listed in the `faces-config.xml`) is used. If the conflict is among rules defined in different configuration files, the rule in the last configuration file to be loaded is used. Configuration files are loaded in the order they appear in the `web.xml` file.

Example 9-7 Conflicting Navigation Cases

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

    <navigation-rule>
      <from-view-id>*</from-view-id>
      <navigation-case>
        <from-outcome>globalhelp</from-outcome>
        <to-view-id>/menu/help.html</to-view-id>
        <redirect/>
      </navigation-case>
    </navigation-rule>

### 9.2.4.4 Splitting Navigation Cases Over Multiple Rules

You can split the navigation cases for the links on one page among different navigation rules. For example, if your application provides users with a common set of controls for navigating to particular parts of the application, one rule could define the navigation cases for all the common controls, while other navigation rules would define the navigation from other controls.

To define navigation split over multiple rules, you must create separate navigation rules that would together define all the navigation cases, as shown in Example 9-8. When these rules are evaluated, the more specific navigation cases are used first, then the more general case.

Example 9-8 Navigation Cases Split Over Multiple Rules

    <navigation-rule>
      <from-view-id>/order.jsp</from-view-id>
      <navigation-case>
        <from-action>#{backing_home.submit}</from-action>
        <from-outcome>success</from-outcome>
        <to-view-id>/summary.jsp</to-view-id>
      </navigation-case>
      <navigation-case>
        <from-action>#{backing_home.check}</from-action>
        <from-outcome>success</from-outcome>
        <to-view-id>/check.jsp</to-view-id>
      </navigation-case></navigation-case>
    </navigation-rule>
    <navigation-rule>
      <from-view-id>/order.jsp</from-view-id>
      <to-view-id>/again.jsp</to-view-id>
      </navigation-case>
    </navigation-rule>

## 9.2.5 What You May Need to Know About the Navigation Modeler

When using the navigation modeler to create and maintain page navigation, be aware of the following features:

- Changes to navigation rules made directly in the `faces-config.xml` file using the XML editor or made in the configuration editor usually refresh the navigation modeler. If the navigation diagram does not match the current `faces-config.xml` file, you can manually refresh the diagram by right-clicking on the diagram and choosing Diagram > Refresh diagram from faces-config.

- When you delete a navigation case on the diagram, the associated `navigation-case` element is removed from the `faces-config.xml` file. If you remove all the cases in a rule, the `navigation-rule` element remains in the `faces-config.xml` file. You can remove the rule directly in the `faces-config.xml` file.

- When you edit the label for the navigation case on the diagram, the associated `navigation-case` element is updated in the `faces-config.xml` file. You cannot change the destination of the navigation case in the diagram. You can, however, change the destination of a navigation case in the JSF Configuration Editor or directly in the `faces-config.xml` file itself.

- When you delete a page icon from the navigation diagram, the associated page file is not deleted the from the Web Content folder in the ViewController project in the Application Navigator.

- When you edit pages manually, JDeveloper does not automatically update the navigation diagram or the associated `faces-config.xml` file. Conversely, when you make changes to a page flow that affect the behavior of an existing page, JDeveloper does not automatically update the code in the page. To coordinate the navigation diagram with web page changes, right-click on the page in the navigation diagram and choose Diagram > Refresh Diagram from All Pages.

- The navigation modeler diagram is the default editor for the `faces-config.xml` file. If you have a large or complex application, loading the diagram may be slow, because the file may be large. If you do not want JSF diagram files to be created for your JSF configuration files, use the Tools > Preferences > File Types > Default Editor > JSF Configuration File option to change the default editor. If you change the default editor before opening the `faces-config.xml` file for the first time, no diagram file is created unless you specifically request one.