| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
This chapter describes how to create navigation rules and cases, and how to create basic navigation components, such as buttons and links, that trigger navigation rules using outcomes.
This chapter includes the following sections:
For information about how to create dynamic navigation menus, see Chapter 19, "Using Complex UI Components".
Navigation through a JSF application is defined by navigation rules. These rules determine, based on outcomes specified by UI components, which page is displayed next when the UI component is clicked.
Defining page navigation for an application is a two-step process:
First, you create navigation rules for all the pages in your application.
In most cases, you define one rule for each page in your application. However, you can also define pattern-based rules that affect groups of pages or global rules that affect all pages.
Next, in each navigation component on the pages, such as a command button or link, you specify either a static or dynamic outcome value in the action attribute.
Static outcome values are an explicit reference to a specific outcome defined in a navigation rule. Dynamic outcome values are derived from a binding on a backing bean method that returns an outcome value. In either case, the outcome value specified in the action attribute must match an outcome defined in the navigation rules or be handled by a default navigation rule for navigation to occur.
While you can create simple hand-coded navigation links between pages, using outcomes and navigation rules makes defining and changing application navigation much easier.
Read this chapter to understand:
What navigation rules and cases are and how to create them
How to create global, pattern-based, and default rules
How to create UI components that use static outcome values
How to bind navigation components to backing beans that return dynamic outcomes
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 16-1.
Example 16-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 consist of the following elements:
navigation-rule: A mandatory wrapper element for navigation case elements.
from-view-id: An optional element that contains either a 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: A mandatory wrapper element for each case in the navigation rule. Each case defines the different navigation paths from the same page. A navigation rule must have at least one navigation case.
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}.
from-outcome: A mandatory element that 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: A mandatory element that 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 16.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. There is one navigation modeler diagram for each JSF configuration file that you create.
To define a navigation rule 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, click the Diagram tab to display the navigation modeler, as shown in Figure 16-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:
In the Component Palette, select JSF Navigation Case to activate it.
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 16-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 16-3.
Use the navigation-case Properties dialog to define the elements in the navigation case. For a description of each element, see Section 16.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 16-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 16-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 16-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.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, click the Overview tab to display the configuration editor.
From the element list (in the left corner), select Navigation Rules, as shown in Figure 16-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.
When you create a global navigation rule, 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 either <from-view-id>* </from-view-id> or <from-view-id>/*</from-view-id>. 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 16.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 16-5 shows a navigation rule with two cases defined in the faces-config.xml file for the SRCreate page in the SRDemo application. The first case navigates to the SRCreateConfirm page when the outcome specified in the action attribute of an activated navigation component is Continue. The second case navigates to the SRFaq page when the action attribute of an activated navigation component is dialog:FAQ. The dialog: outcome prefix causes the page in the to-view-id element to be launched as a dialog. For more information about creating dialogs, see Section 19.3, "Using Popup Dialogs".
Example 16-5 Navigation Rule for a Specific Page
<navigation-rule>
<from-view-id>/app/SRCreate.jspx</from-view-id>
<navigation-case>
<from-outcome>Continue</from-outcome>
<to-view-id>/app/SRCreateConfirm.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>dialog:FAQ</from-outcome>
<to-view-id>/app/SRFaq.jspx</to-view-id>
</navigation-case>
</navigation-rule>
Example 16-6 shows a global 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 in the application. The cases defined in this global rule handle the navigation from the standard menu displayed on all of the pages.
Some of the cases use the redirect element, which 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 using the redirect element.
Example 16-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>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 Sun JSF Reference 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 Oracle 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 13.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.
In a large application, you might want to define the navigation rules for pages in specific areas of the application in separate JSF configuration files. 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. In JDeveloper, there is one navigation modeler diagram for each separate JSF configuration file.
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 11, "Getting Started with ADF Faces".)
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 16-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 16-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 16-8. When these rules are evaluated, the more specific navigation cases are used first, then the more general case.
Example 16-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. Each JSF configuration file has its own navigation modeler diagram. If the information in a navigation diagram does not match the information in its 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.
When a component is defined using static navigation, the outcome value in the action attribute is a constant value that always triggers the same navigation case. When a user clicks a component that is using static navigation, a specific JSF page is displayed—there are no alternative navigation paths.
To use static navigation, you create the navigation case using a from-outcome value, but not a from-action value. In the action attribute of the navigation button or link you specify a constant outcome value that matches the value you entered in the from-outcome element of the navigation case.
For example, if you create a navigation case with a from-outcome value of Confirm, as shown in Example 16-9, you would create a button or link on the page that specifies Confirm as a static value of the action attribute, as shown in Example 16-10. In this case, when the user clicks the button, the navigation case causes the ConfirmAction page to be displayed.
Example 16-9 Navigation Case Defined in the faces-config.xml File
<navigation-case> <from-outcome>Confirm</from-outcome> <to-view-id>/app/ConfirmAction.jspx</to-view-id> </navigation-case>
Example 16-10 Static Navigation Button Defined in a JSF Page
<af:commandButton text="Continue" action="Confirm"/>
To create a navigation component that uses a static outcome, you can create the component using the Component Palette or the Data Control Palette. If you use the Data Control Palette, the actionListener attribute of the component will be bound to a data control operation or method. Once you have created the component, you can then specify the outcome value in the action attribute. When the user clicks the component, the application navigates to the page determined by the outcome value and navigation case. However, if the component is bound to a data control, first the operation or method is invoked, and then the navigation is performed.
For more information about command components that are bound to data control methods, see Section 17.3, "Creating Command Components to Execute Methods".
To create a navigation component that uses a static outcome:
Create a navigation component using one of the following techniques:
From the ADF Faces Core page of the Component Palette, drag a CommandButton or a CommandLink component onto the page.
Tip:
You can also use the JSFcommandButton or commandLink components.From the Data Control Palette, drag and drop an operation or a method onto the page and choose ADF Command Button or an ADF Command Link from the context menu.
If you drag and drop a method that takes parameters, the ADF command button and command link components appear under Method in the context menu. JDeveloper displays the Action Binding Editor where you can define any parameter values you want to pass to the method. For more information about passing parameters to methods, see Section 17.4, "Setting Parameter Values Using a Command Component".
In the Structure window, select the navigation component and open the Property Inspector.
Tip:
The shortcut for opening the Property Inspector is Ctrl+Shift-I.In the Action field displayed in the Property Inspector, enter the outcome value.
The value must be a constant or an EL expression that evaluates to a string. To view a list of outcomes already defined in the page's navigation cases, click the dropdown in the Action field of the Property Inspector.
Tip:
If you want to trigger a specific navigation case, the outcome value you enter in theaction attribute must exactly match the outcome value in the navigation case, including uppercase and lowercase. If the outcome specified by an action does not match any outcome in a navigation case, the navigation will be handled by a default navigation rule (if one exists), or no navigation will occur.
Also, the action attribute must be either an outcome value or an EL expression that evaluates to an outcome value. You cannot enter a page URL in the action attribute.
When you create a navigation component with static outcomes, JDeveloper adds the component to the JSF page. If you have not already done so, you will then need to add a navigation case to the faces-config.xml file to handle the navigation outcome specified in the component.
Example 16-11 shows a simple navigation component that was created using the ADF Faces commandLink component, which is available from the Component Palette. This command link appears on many of the SRDemo application's pages; it navigates to the SRAbout page, which displays information about the application.
Since there is only one possible navigation path, the command link is defined with a static outcome in the action attribute. The outcome value is GlobalAbout, which matches the from-outcome value of the navigation case shown in Example 16-12. The navigation case belongs to a global navigation rule that applies to all pages in the application.
Example 16-11 Navigation Component That Specifies a Static Outcome Value
<af:commandLink text="#{res['srdemo.about']}" action="GlobalAbout"
immediate="true"/>
Example 16-12 Navigation Rule Referenced by a Static Outcome Value
<navigation-rule>
<from-view-id>*</from-view-id>
...
<navigation-case>
<from-outcome>GlobalAbout</from-outcome>
<to-view-id>/app/SRAbout.jspx</to-view-id>
</navigation-case>
...
</navigation-rule>
Tip:
If you enabled auto-binding by choosing the Automatically Expose UI Components in a New Managed Bean option when you created the page, any navigation component you create will automatically contain a binding to the managed bean (also known as a backing bean) defined for the page, even if the binding is not used. In a simple navigation component that has a static outcome, you may want to remove the unused binding from the component.Instead of explicitly specifying a static outcome value in a navigation component, you can dynamically determine the outcome by binding the action attribute of a navigation component to an action method. An action method is a method in a backing bean (also known as a managed bean) that can perform an action (such as saving user input, for example) and return an outcome value. The outcome value determines the next page that should be displayed after the method performs an action. For example, an action method that verifies user input on a page might return one outcome if the input is valid and return another outcome if the input is invalid. Each of these different outcomes could trigger different navigation cases, causing the application to navigate to one of two possible target pages. As with static outcomes, a dynamic outcome triggers a navigation case that contains a matching from-outcome value or a default navigation case.
The method bound to a navigation component must be a public method with no parameters, and it must return a string representing the outcome of the action. An action method can return one of multiple outcomes depending on the processing it carries out. In other words, you can define conditional outcomes in the method logic. The outcome returned by the method must be defined in one of the cases in the page's navigation rules (unless you are using default rules, which handle all outcomes not specified in any navigation case).
Tip:
In ADF applications, most processing of data objects is handled by the data control. Therefore, if a navigation component that uses dynamic outcomes needs to perform some processing on a data object (for example, creating, editing, deleting), it should be bound to a backing bean method that injects the ADF binding container. When a backing bean injects the ADF binding container, it calls the specified data control method to handle the processing of the data and then, based on the results, returns a navigation outcome to the UI component. For more information about injecting the binding container into a backing bean, see Section 17.5, "Overriding Declarative Methods".If you want the outcome of a navigation component to be determined dynamically, you can bind the component to a method on a backing bean. The backing bean can execute some application logic and, depending on the results, return an outcome. The returned outcome will determine the navigation rule that is implemented. For information about creating backing beans, see Section 11.5, "Creating and Using a Backing Bean for a Web Page".
Note:
If you enabled auto-binding by choosing the Automatically Expose UI Components in a New Managed Bean or the Automatically Expose UI Components in an Existing Managed Bean options when you created the page, any navigation component you create will automatically contain a binding to the managed bean (also known as a backing bean) defined for the page.To create a navigation component that binds to a backing bean:
From the ADF Faces Core page of the Component Palette, drag a CommandButton or a CommandLink onto the page.
Tip:
You can also use the JSFcommandButton and commandLink components.In the visual editor double-click the UI component to display the Bind Action Property dialog, as shown in Figure 16-5.
The Bind Action Property dialog enables you to identify the backing bean and method to which you want to bind the component. If you enabled auto-binding when you created the page, the Bind Action Property dialog does not display the option for specifying a static outcome.
In the Bind Action Property dialog, identify the backing bean and the method to which you want to bind the component using one of the following techniques:
Click New to create a new backing bean. The Create Managed Bean dialog is displayed. Use this dialog to name the bean and the class.
Select an existing backing bean and method from the dropdown lists.
After identifying the backing bean and method, click OK on the Bind Action Property dialog.
JDeveloper displays the source editor. If it is a new method, the source editor displays a stub method, as shown in Example 16-13. If it is an existing method, the source editor displays that method, instead of the stub method.
Add any required processing logic to the method.
Change the return values of the method to the appropriate outcome strings.
You may want to write conditional logic to return one of multiple outcomes depending on certain criteria. For example, you might want to return null if there is an error in the processing, or another outcome value if the processing was successful. A return value of null causes the navigation handler to forgo evaluating navigation cases and to immediately redisplay the current page.
Tip:
To trigger a specific navigation case, the outcome value you enter in the
action attribute must exactly match the outcome value in the navigation rule, including uppercase and lowercase letters.When you create a navigation component that specifies a dynamic outcome, JDeveloper adds an EL expression to the action attribute of the component tag. The EL expression references the backing bean method that will perform some application processing, such as saving user input, and return an outcome value.
Example 16-14 shows a button on the SRCreateConfirm page of the SRDemo application that uses a dynamic outcome value. The button was created using the ADF Faces commandButton component, which is available from the Data Control Palette context menu. The user clicks the button to create a new service request.
Example 16-14 Navigation Component That Uses Dynamic Outcomes
<af:commandButton text="#{res['srcreate.submit.button']}"
partialSubmit="false"
action="#{backing_SRCreateConfirm.createSRButton_action}"
id="createSRButton"/>
The button's action attribute is bound to the createSRButton_action method on the SRCreateConfirm backing bean, which is shown in Example 16-15.
Example 16-15 Backing Bean Method That Returns a Dynamic Outcome
public String createSRButton_action() {
BindingContainer bindings = getBindings();
OperationBinding operBinding =
bindings.getOperationBinding("createServiceRequest");
Integer newServiceRequestId = (Integer)operBinding.execute();
//Put the number of the created service ID onto the request as an
// example of passing data in that way
JSFUtils.setRequestAttribute("SRDEMO_CREATED_SVRID",newServiceRequestId);
return "Complete";
}
The backing bean method creates the service request and returns an outcome value of Complete. To create the service request, the backing bean method overrides the declarative method createServiceRequest, which was used to initially create the button. When a method overrides a declarative method, the JSF runtime injects the binding container for the current page using the managed property called bindings. The backing been method calls the getBindings() property getter, which accesses the current binding container, then it executes the method action binding for the createServiceRequest method in the SRService data control. For more information about overriding declarative methods, see Section 17.5, "Overriding Declarative Methods".
Example 16-16 shows the navigation rule that handles the outcome returned by the backing bean.
When a user clicks a navigation component that has a dynamic outcome, the action method on the backing bean is executed. The method usually processes some user input and then returns an outcome value to the page. The JSF navigation handler evaluates the outcome returned by the action method and matches it to a navigation case that has the same value defined in the from-outcome element. The matching rule is then implemented and the page defined in the rule's to-view-id element is displayed. If the method does not return an outcome or if the outcome does not match any of the navigation cases, the user remains on the current page.
When using an action method to handle navigation in an application, you don't need to implement an action listener interface to invoke the method because JSF uses a default action listener to invoke action methods for page navigation: the method's logical outcome value is used to tell the JSF navigation handler what page to use for the render response.
If an action method returns different outcomes depending on the processing logic, you may want to define a default navigation case to prevent having the method return an outcome that is not covered by any specific navigation case.
Default navigation cases catch all the outcomes not specifically covered in other navigation cases. To define a default navigation case, you can exclude the from-outcome element, which tells the navigation handler that the case should apply to any outcome not handled by another case.
For example, suppose you are using an action method to handle a Submit command button. You can handle the success case by displaying a particular page for that outcome. For all other outcomes, you can display a page explaining that the user cannot continue. Example 16-17 shows the navigation cases for this scenario.
Example 16-17 Navigation Rule with a Default Navigation Case
<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.submit}</from-action>
<to-view-id>/again.jsp</to-view-id>
</navigation-case>
</navigation-rule>
In the example, the first navigation case is a dynamic navigation case, where an action method is determining the outcome. If the outcome is success, the user navigates to the /summary.jsp page.
The second navigation case is a default navigation case that catches all other outcomes returned by the action method and displays the /again.jsp for all outcomes. Notice that the default case does not specify a from-outcome value, which causes this case to be implemented if the outcome returned by the action method does not match any of the other cases.
You can use action listener methods in a navigation component when you have an action that needs information about the user interface. Suppose you have a button that uses an image of the state of California, and you want a user to be able to select a county and display information about that county. You could implement an action listener method that determines which county is selected by storing an outcome for each county, and an action method that uses the outcome value to navigate to the correct county page.
To use an action method and action listener method on a component, you would reference them as shown in Example 16-18.
Instead of binding an action attribute to a backing bean, you can bind it to a data control method that returns a navigation outcome. To bind the action attribute to a data control method you must enter the ADF binding expression manually and use the outcome binding property, as shown in Example 16-19.
Example 16-19 Navigation Component Bound to a Data Control Method
<af:commandButton
text="Delete Service History Notes"
action="#{bindings.deleteServiceHistoryNotes.outcome}"/>
The outcome property invokes the outcome() method in the FacesCtrlActionBinding class, which executes the data control method by calling the execute method of that same class. When the data control method returns a value, the outcome() method converts it to a string (if necessary) and returns it to the action attribute.
