|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
 Previous |
 Next |
|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
|
Previous |
Next |
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
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
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.
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".)
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:
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.
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.
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. |
Create the navigation cases between the pages using the following technique:
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.
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.
In the diagram, double-click the arrow representing the navigation case to display the navigation-case Properties dialog, shown in Figure 9-3.
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".
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.
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.
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 anull value in the action attribute. In this case, no navigation occurs; instead, the same page is redisplayed.
|
Edit existing rules and cases.
To create a navigation rule using the JSF Configuration Editor:
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.
In the visual editor, activate the Overview tab to display the configuration editor.
From the element list (in the left corner), select Navigation Rules, as shown in Figure 9-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 thefrom-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.
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 thefrom-outcome value exactly the same way, including lowercase and uppercase letters.
|
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>
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:
If the outcome returned by an action method is null, it returns immediately and redisplays the current page.
It merges all navigation rules with the same from-view-id value.
If a rule exists whose from-view-id value matches the view ID exactly, it uses that rule.
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.
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.
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):
If both the from-outcome and from-action values of a case match the current action method and action value, it uses that case.
If a case has no from-action element, but the from-outcome value matches the current action value, it uses that case.
If a case has no from-outcome element, but the from-action value matches the current action method, it uses that case.
If there is a case with neither a from-outcome element nor a from-action element, it uses that case.
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". |
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.
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.
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.
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>
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>
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.
