Typical uses of navigation components are to create buttons and links to allow users to navigate to another page or window, to perform actions on data, or to perform actions and navigate at the same time. For example, as shown in Figure 20-2, the main page of the File Explorer application contains a button component that you click to refresh the page after making a skin selection and a link component that opens a popup window when clicked.

Figure 20-2 File Explorer Application Main Page

At the top right corner of the File Explorer application, there are four global application links. While you can use link components to provide the destinations for navigation, the File Explorer application uses the navigationPane and child commandNavigationItem components to provide links that either navigate directly to another location or deliver an action that results in navigation.

The navigationPane component also lets you organize application content in a meaningful structure and provides a navigation method for users to move through different content areas in the application to perform various functions. For example, a simple HR application might have pages that let employees check on company benefits, and pages for administration to view and create employee data, as shown in Figure 20-3. The navigationPane component provides the structure with tabs, bars, or lists for example, and the child commandNavigationItem components provide the navigation links.

Figure 20-3 Page Showing Navigation Tab, Bar and List Links

The navigationPane component can also be used with a menu model, where the component is bound to the menu model managed bean. For complex page hierarchies, using a menu model is more efficient as the framework generates the correct number of navigation items in the structure on each page and also keeps track of which items are to be displayed as "selected".

The menuBar component can also be bound to a menu model to implement menus and submenus for navigating different levels in a page hierarchy. Most shopping websites use a system of menus to categorize shopping areas and provide a one-click action to a specific subcategory or item in the hierarchy. As shown in Figure 20-4, the menu bar shows the first level of menu items at a glance. As the mouse cursor hovers over a menu, a submenu of more items display for the user to browse and choose. Typically you would not implement more than three levels of menu items.

Figure 20-4 Page With Three Menus on a Bar with a Submenu Expanded

Whether you use navigationPane or menuBar (bound to a menu model) to create your page hierarchy, you can use the breadCrumbs component and a series of child commandNavigationItem components to provide users with a visual indication to their current location in the page hierarchy. As shown in Figure 20-5, the breadCrumbs component displays a line of text links starting from the root page down to the current page, which is always the last link. If you create your page hierarchy using a menu model, you can also bind the breadCrumbs component to the same menu model managed bean and let the framework dynamically generate the links for you.

Figure 20-5 Page Showing Horizontal Breadcrumb Links

The train component allows users to quickly see where they are in a multistep process and also navigate through that process. The trainButtonBar component provides additional navigation for a train process in the form of back and next buttons as arrows, and also gives information about the current and total number of pages as shown in Working with Navigation Components.

Figure 20-6 ADF Faces Train and TrainButtonBar Demonstration Pages

You may find it helpful to understand other ADF Faces features before you implement your navigation components. Additionally, once you have added these components to your page, you may find that you need to add functionality such as accessibility and localization. Following are links to other functionality that navigation components can use.

• Using parameters in text: You can use the ADF Faces EL format tags if you want the text displayed in a component to contain parameters that will resolve at runtime. See How to Use the EL Format Tags.

• Events: Components fire both server-side and client-side events that you can have your application react to by executing some logic. See Handling Events.

• Partial page rendering: ADF Faces navigation components can be used to trigger partial rerendering of components on a page. See Rerendering Partial Page Content.

• Accessibility: You can make your navigation components accessible. See Developing Accessible ADF Faces Pages.

• Localization: Instead of directly entering text for labels, you can use property files. These files allow you to manage translation of the text strings. See Internationalizing and Localizing Pages.

• Skins: You can change the look and feel of navigation components by changing the skin. See Customizing the Appearance Using Styles and Skins.

• Touch Devices: ADF Faces components may behave and display differently on touch devices. See Creating Web Applications for Touch Devices Using ADF Faces.

• Drag and Drop: You can configure your components so that the user can drag and drop them to another area on the page. See Adding Drag and Drop Functionality.

1. In the Components window, from the General Controls panel, drag and drop the action component that you want to use onto the JSF page. More specifically, drag and drop a:

   • Button to create a button component.

   • Link to create a link component.

2. In the Properties window, expand the Common section and set the following:

   • Text: Specify the text to display.

     Tip:

     Alternatively, you can use the textAndAccessKey attribute to provide a single value that defines the label along with the access key to use for the button or link. For information about how to define access keys, see How to Define Access Keys for an ADF Faces Component.

   • Icon: Set to the URI of the image file if you want to render an icon inside the component. If you render an icon, you can also set values for hoverIcon, disabledIcon, depressedIcon, and iconPosition in the Appearance section.

     Tip:

     You can use either the text attribute (or textAndAccessKey attribute) or the icon attribute, or both.

   • IconPosition: If you specified an icon, you can determine the position of the icon relative to the text by selecting a value from the dropdown list:

     • <default> (leading): Renders the icon before the text.

     • trailing: Renders the icon after the text.

     • top: Renders the icon above the text.

     • bottom: Renders the icon below the text.

   • Selected: Set to true so that the component appears as selected when the page renders.

   • Action: Set to an outcome string or to a method expression that refers to a backing bean action method that returns a logical outcome String. For information about configuring the navigation between pages, see Defining Page Flows.

     The default JSF ActionListener mechanism uses the outcome string to select the appropriate JSF navigation rule, and tells the JSF NavigationHandler what page to use for the Render Response phase. For information about using managed bean methods to open dialogs, see Using Popup Dialogs, Menus, and Windows. For information about outcome strings and navigation in JSF applications, see the Java EE tutorial at http://docs.oracle.com/javaee/index.html.

     Tip:

     The actionListener attribute can also be used for navigation when bound to a handler that returns an outcome. Usually, you should use this attribute only to handle user interface logic and not navigation.

     For example, in the File Explorer application, the Search button in Search panel does not navigate anywhere. Instead, it performs a search. It has the following value for its actionListener attribute:

     actionListener="#{explorer.navigatorManager.searchNavigator.
                                                searchForFileItem}"

     This expression evaluates to a method that actually performs the search.

3. Expand the Behavior section and set the following:

   • Disabled: Select true from the dropdown list if you want to show the component as a noninteractive button or link.

   • PartialSubmit: Select true from the dropdown list to fire a partial page request each time the component is activated. See Using Partial Triggers.

   • Immediate: Select true from the dropdown list if you want to skip the Process Validations and Update Model phases. The component's action listeners (if any), and the default JSF ActionListener handler are executed at the end of the Apply Request Values phase of the JSF lifecycle. See Using the Immediate Attribute.

4. Optionally, if you set the immediate attribute to true as described in Step 3, you can add the af:checkUncommittedDataBehavior component as a child to the action component to display a warning message to the user if the page contains uncommitted data. Drag Check Uncommitted Data Behavior from the Behavior group in the Operations panel of the Components window and drop it as a child of the action component you added in Step 1.

   Note:

   You must have also set the document tag's uncommittedDataWarning attribute to on, as described in How to Configure the document Tag.

1. In the Components window, from the General Controls panel, drag and drop the component that you want to use onto the JSF page. More specifically, drag and drop a:

   • Button to create a button component.

   • Link to create a link component.

2. In the Properties window, expand the Common section and set the following:

   • Text: Specify the text to display.

     Tip:

     Instead, you can use the textAndAccessKey attribute to provide a single value that defines the label and the access key to use for the button or link. For information about how to define access keys, see How to Define Access Keys for an ADF Faces Component.

   • Icon: Set to the URI of the image file if you want to render an icon inside the component. If you render an icon, you can also set values for hoverIcon, disabledIcon, depressedIcon, and iconPosition in the Appearance section.

     Tip:

     You can use either the text attribute (or textAndAccessKey attribute) or the icon attribute, or both.

   • IconPosition: If you specified an icon, you can determine the position of the icon relative to the text by selecting a value from the dropdown list:

     • <default> (leading): Renders the icon before the text.

     • trailing: Renders the icon after the text.

     • top: Renders the icon above the text.

     • bottom: Renders the icon below the text.

   • Selected: Set to true so that the component appears as selected when the page renders.

   • Destination: Set to the URI of the page to navigate to.

     For example, set to the following to navigate to Oracle's web site:

     destination="http://www.oracle.com"
     

   • TargetFrame: Specify where the new page should display by selecting a value from the dropdown list:

     • _blank: The link opens the document in a new window.

     • _parent: The link opens the document in the window of the parent. For example, if the link appeared in a dialog, the resulting page would render in the parent window.

     • _self: The link opens the document in the same page or region.

     • _top: The link opens the document in a full window, replacing the entire page.

3. Expand the Behavior section and select true from the Disabled dropdown list if you want to show the component as a noninteractive button or link.

As described in Using Partial Page Navigation, you can configure an ADF Faces application to have navigation triggered through a partial page rendering request. When partial page navigation is turned on, partial page navigation for GET requests is automatically supported on the following components:

• af:button

• af:link

• af:goMenuItem (used within af:menu and af:menuBar)

• af:commandNavigationItem (used within af:navigationPane)

The only requirement is that the destination attribute on a supported component contain a relative URL of the application context root and begin with "/", such as "/faces/myPage.jsf", where faces is the URL mapping to the application's servlet defined in web.xml and myPage.jsf is the page to navigate. Because partial page navigation makes use of the hash ('#') portion of the URL, you cannot use the hash portion for navigation to anchors within a page.

If the targetFrame attribute on a supported component is set to open the link in a new window, the framework automatically reverts to full page navigation.

1. In the Applications window, expand the WEB-INF node and double-click web.xml.
2. In the overview editor, click the Application navigation tab and then click the Add icon next to the Context Initialization Parameters table to add an entry for the oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSION parameter and set it to no.
3. Save and close the web.xml file.

If you followed the procedure outlined in How to Configure a Browser's Context Menu for Command Links, JDeveloper writes a value to the web.xml file, as shown in Example 20-1.

For information about ADF Faces configuration options in your application's web.xml file, see Configuration in web.xml.

At runtime, end users can invoke a browser's context menu by right-clicking on the links rendered by certain components, as described in Configuring a Browser's Context Menu for Links.

<context-param>
    <param-name>oracle.adf.view.rich.ACTION_LINK_BROWSER_CONTEXT_SUPPRESSION</param-name>
    <param-value>no</param-value>
  </context-param>

You can create a way for users to download files by creating an action component such as a button and associating it with a fileDownloadActionListener tag. When the user selects or clicks the component, a popup dialog displays that allows the user to select different download options, as shown in Figure 20-9.

Figure 20-9 File Download Dialog

Description of "Figure 20-9 File Download Dialog "

Use the fileDownloadActionListener tag to allow an action component (for example, a button, link, or menu item) to send the contents of a file to an end user. You can also specify the content type or file name when you use this tag. Any value that you set for the action component's partialSubmit attribute is ignored at render time if you use the fileDownloadActionListener tag. The fileDownloadActionListener tag determines what type of submit the action component invokes based on the context. If you use the fileDownloadActionListener tag within a JSF portlet in your application, the action component invokes a partial submit (partialSubmit="true"). If you use the fileDownloadActionListener tag within an application that uses the ADF Faces servlet, the action component invokes a full submit (partialSubmit="false").

Tip:

For information about uploading a file to the server, see Using File Upload.

After the content has been sent to the browser, how that content is displayed or saved depends on the option that the end user selects in the dialog. If the end user selects the Open with option, the application associated with that file type will be invoked to display the content. For example, a text file may result in the Notepad application being started. If the end user selects the Save to Disk option, depending on the browser, a popup dialog may appear to select a file name and a location in which to store the content.

The following example shows the tags of a button with the fileDownloadActionListener tag to download the file named hello.txt to the user.

<af:button value="Say Hello">
  <af:fileDownloadActionListener filename="hello.txt"
      contentType="text/plain; charset=utf-8"
      method="#{bean.sayHello}"/>
</af:button>

The following example shows a managed bean method that processes the file download.

public void sayHello(FacesContext context, OutputStream out) throws IOException{
  OutputStreamWriter w = new OutputStreamWriter(out, "UTF-8");
  w.write("Hi there!");
   . . .
}

If you use the fileDownloadActionListener tag from within a JSF portlet in your application, you can optionally add the parameters described in Table 20-1 to the web.xml file of your application to configure the size and temporary location options for the file during download.

Table 20-1 Parameters to Add to web.xml File to Use fileDownloadActionListener in a Portlet

Parameter name	Data type	Description
oracle.adf.view.rich.portal.FILE_DOWNLOAD_MAX_MEM	Integer	Specify the maximum size in kilobytes of the file that the fileDownloadActionListener tag can store during a session. If the file exceeds the maximum size you specify, the application attempts to save the file to the hard drive in the location you specify for FILE_DOWNLOAD_TEMP_DIR. If you do not specify a value for this parameter in the web.xml file, it defaults to 100 kilobytes.
oracle.adf.view.rich.portal.FILE_DOWNLOAD_MAX_DISK_SPACE	Integer	Specify the maximum size in kilobytes of the file that the fileDownloadActionListener tag can download. If a file's size exceeds this value, an exception occurs and a log message is logged to the server's log file. If you do not specify a value for this parameter in the web.xml file, it defaults to 2000.
oracle.adf.view.rich.portal.FILE_DOWNLOAD_TEMP_DIR	String	Specify the temporary location where you store files during download. If you do not specify a value, it defaults to the directory specified by java.io.tempDir.

For information about configuring your web.xml file, see Configuration in web.xml.

Before you begin:

It may help to understand how a component's attributes affect functionality. See Using Buttons or Links to Invoke Functionality.

You may also find it helpful to understand functionality that can be added using other ADF Faces features. See Additional Functionality for Navigation Components.

You will need to complete this task:

• Create an action component, as described in Using Buttons and Links for Navigation.

To create a file download mechanism:

1. In the Components window, from the Operations panel, in the Listeners group, drag and drop the File Download Action Listener tag as a child to the action component.
2. In the Properties window set the following attributes:

   • ContentType: Specify the MIME type of the file, for example text/plain, text/csv, application/pdf, and so on.

   • Filename: Specify the proposed file name for the object. When the file name is specified, a Save File dialog will typically be displayed, though this is ultimately up to the browser. If the name is not specified, the content will typically be displayed inline in the browser, if possible.

   • Method: Specify the method that will download the file contents. The method takes two arguments, a FacesContext object and an OutputStream object. The OutputStream object will be automatically closed, so the sole responsibility of this method is to write all bytes to the OutputStream object.

   For example, entries in the JSF page for a button component that uses the fileDownloadActionListener tag would be similar to the following:

   <af:button text="Load File">
     <af:fileDownloadActionListener contentType="text/plain"
         filename="MyFile.txt"
         method="#(mybean.LoadMyFile"/>
   </af:button>

1. In the Components window, from the Operations panel, in the Listeners group, drag a Reset Listener and drop it inside the action component that you created.
2. In the Insert Reset Listener dialog, specify the type of event that the resetListener tag activates in response to. For example, enter action so that the resetListener tag responds to an actionEvent returned by the action component's actionListener attribute.

   Click Help in the Insert Reset Listener dialog to view a complete list of supported values.

1. In the Applications window, expand the WEB-INF node and double-click faces-config.xml.
2. Create one global JSF navigation rule that has the navigation cases for all the nodes in the page hierarchy.

   For example, the page hierarchy shown in Figure 20-10 has 10 nodes, including the global Help node. Thus, you would create 10 navigation cases within one global navigation rule in the faces-config.xml file, as shown in Example 20-2.

   For each navigation case, specify a unique outcome string, and the path to the JSF page that should be displayed when the navigation system returns an outcome value that matches the specified string.

   For information about creating navigation cases in JDeveloper, see Defining Page Flows.

<navigation-rule>
  <navigation-case>
    <from-outcome>goHome</from-outcome>
    <to-view-id>/home.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goHelp</from-outcome>
    <to-view-id>/globalhelp.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goEmp</from-outcome>
    <to-view-id>/empdata.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goBene</from-outcome>
    <to-view-id>/benefits.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goIns</from-outcome>
    <to-view-id>/insurance.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goPto</from-outcome>
    <to-view-id>/pto.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goView</from-outcome>
    <to-view-id>/viewdata.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goCreate</from-outcome>
    <to-view-id>/createemp.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goHealth</from-outcome>
    <to-view-id>/health.jsf</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>goDental</from-outcome>
    <to-view-id>/dental.jsf</to-view-id>
  </navigation-case>
</navigation-rule> 

The XMLMenuModel metadata file is a representation of a navigation menu for a page hierarchy in XML format. You can use one or more XMLMenuModel metadata files to represent an entire page hierarchy. In an XMLMenuModel metadata file, the page hierarchy is described within the menu element, which is the root element of the file. Every XMLMenuModel metadata file is required to have a menu element and only one menu element is allowed in each file.

The other elements in the XMLMenuModel metadata file or hierarchy can be made up of item nodes, group nodes, and shared nodes. Item nodes represent navigable nodes (or pages) in the hierarchy. For example, say you wanted to build the hierarchy depicted in Figure 20-13.

Figure 20-13 Sample Page Hierarchy

If you wanted each node in the hierarchy to have its own page to which a user can navigate, then in the metadata file you would create an item node for each page. You nest children nodes inside a parent node to create the hierarchy. However, say you did not need a page for the Employee Data node, but instead wanted the user to navigate directly to the View Employee page. You would then use a group node to represent the Employee Data page and use the group node's idref attribute to reference the page that opens (the View Employee page) when an end user clicks the Employee Data tab. The group node allows you to retain the hierarchy without needing to create pages for nodes that are simply aggregates for their children nodes.

The following example shows an XMLMenuModel metadata file that uses mostly item nodes and one group node to define the entire page hierarchy illustrated in Figure 20-13.

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
  <itemNode id="in01" focusViewId="/home.jsf" label="Home" action="goHome">
    <itemNode id="in1" focusViewId="/benefits.jsf" action="goBene"
              label="Benefits">
      <itemNode id="in11" focusViewId="/insurance.jsf" action="goIns"
                label="Insurance">
        <itemNode id="in111" focusViewId="/health.jsf" action="goHealth"
                  label="Health"/>
        <itemNode id="in112" focusViewId="/dental.jsf" action="goDental"
                  label="Dental"/>
      </itemNode>
      <itemNode id="in12" focusViewId="/pto.jsf" action="goPto"
                label="Paid Time Off">
        <itemNode id="in121" focusViewId="/vacation.jsf"
                  action="goVacation" label="Vacation"/>
        <itemNode id="in122" focusViewId="/sick.jsf" action="goSick"
                  label="Sick Pay"/>
      </itemNode>
    </itemNode>
    <groupNode id="gn2" idref="newEmp" label="Employee Data">
      <itemNode id="in21" focusViewId="/createemp.jsf" action="goCreate"
                label="Create New Employee"/>
      <itemNode id="in22" focusViewId="/viewdata.jsf" action="goView"
                label="View Data"/>
    </groupNode>
  </itemNode>
  <itemNode id="in02" focusViewId="/globalhelp.jsf" action="goHelp"
            label="Help"/>
  <itemNode id="in03" focusViewId="/preferences.jsf" action="goPref"
            label="Preferences"/>
</menu>

Within the root menu element, global nodes are any nodes that are direct children of the menu element. For example, the code in the previous example shows three global nodes, namely, Home, Help, and Preferences.

You can also nest menu models using shared nodes. Use this approach where you have sub trees in the hierarchy (for example, the Benefits tree) as it makes the page hierarchy easier to maintain. For example, you might create the entire Benefits tree as its own menu model metadata file (as shown in the following example) so that the menu model could be reused across an application.

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
  <itemNode id="in1" focusViewId="/benefits.jsf" action="goBene"
            label="Benefits">
    <itemNode id="in11" focusViewId="/insurance.jsf" action="goIns"
              label="Insurance">
      <itemNode id="in111" focusViewId="/health.jsf" action="goHealth"
                label="Health"/>
      <itemNode id="in112" focusViewId="/dental.jsf" action="goDental"
                label="Dental"/>
    </itemNode>
    <itemNode id="in12" focusViewId="/pto.jsf" action="goPto"
              label="Paid Time Off">
      <itemNode id="in121" focusViewId="/vacation.jsf"
                action="goVacation" label="Vacation"/>
      <itemNode id="in122" focusViewId="/sick.jsf" action="goSick"
                label="Sick Pay"/>
    </itemNode>
  </itemNode>
</menu> 

Once you have created the nodes as a separate menu model, then within the different hierarchies that need to use those nodes, you use a shared node to reference the Benefits menu model.

The following example shows an XMLMenuModel metadata file that uses item nodes, a shared node and a group node to define the same page hierarchy depicted in Figure 20-13.

<?xml version="1.0" encoding="windows-1252" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
  <itemNode id="in01" focusViewId="/home.jsf" label="Home" action="goHome">
    <sharedNode ref="#{benefits_menu}/>
    <groupNode id="gn2" idref="newEmp" label="Employee Data">
      <itemNode id="in21" focusViewId="/createemp.jsf" action="goCreate"
                label="Create New Employee"/>
      <itemNode id="in22" focusViewId="/viewdata.jsf" action="goView"
                label="View Data"/>
    </groupNode>
  </itemNode>
  <itemNode id="in02" focusViewId="/globalhelp.jsf" action="goHelp"
            label="Help"/>
  <itemNode id="in03" focusViewId="/preferences.jsf" action="goPref"
            label="Preferences"/>
</menu> 

The sharedNode element references the managed bean that is configured for the Benefits XMLMenuModel metadata file. Whenever you use the Create ADF Menu Model wizard to create a metadata file, JDeveloper automatically adds the managed bean configuration for you.

Before you begin:

It may help to understand how the attributes of navigation components affect functionality. SeeUsing a Menu Model to Create a Page Hierarchy.

You may also find it helpful to understand functionality that can be added using other ADF Faces features. See Additional Functionality for Navigation Components.

To create the XMLMenuModel metadata:

Note:

If your application uses ADF Controller, then this menu option will not be available to you. You need to instead use a bounded task flow to create the hierarchy. See Creating a Page Hierarchy Using Task Flowsin Developing Fusion Web Applications with Oracle Application Development Framework.

For information about the managed bean configuration that JDeveloper automatically adds for you in faces-config.xml, see What Happens When You Use the Create ADF Menu Model Wizard.

For information about using resource bundles, see Internationalizing and Localizing Pages.

1. In the Applications window, locate the project where you want to create the XMLMenuModel metadata file. Expand the WEB-INF node, right-click faces-config.xml and choose Create ADF Menu Model.
2. In the Create ADF Menu Model dialog, enter a file name for the XMLMenuModel metadata file, for example, root_menu.

   Tip:

   If you are using more than one XMLMenuModel metadata file to define the page hierarchy, use the name root_menu only for the topmost (root) metadata file that contains references to the other submenu metadata files.

3. Enter a directory for the metadata file. By default, JDeveloper saves the XMLMenuModel metadata file in the WEB-INF node of the application.

   When you click OK, JDeveloper displays a blank XMLMenuModel metadata file in the source editor, as shown in the following example.

   <?xml version="1.0" encoding="windows-1252" ?>
   <menu xmlns="http://myfaces.apache.org/trinidad/menu"></menu> 
   

4. Select the menu node in the Structure window and enter the appropriate information in the Properties window.

   Table 20-2 shows the attributes you can specify for the menu element.

   Table 20-2 Menu Element Attributes

   Attribute	Description
   resourceBundle	Optional. This is the resource bundle to use for the labels (visible text) of the navigation items at runtime. For example, org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundle.
   var	If using a resource bundle, specify an ID to use to reference the bundle in EL expressions for navigation item labels. For example, #{bundle.somelabel}. See the following example for a sample XMLMenuModel metadata file that uses a resource bundle.
   xmlns	Required. Set to http://myfaces.apache.org/trinidad/menu

   The following example shows sample XMLMenuModel metadata code that uses EL expressions to access a resource bundle for the navigation item labels.

   <?xml version="1.0" encoding="windows-1252" ?>
   <menu xmlns="http://myfaces.apache.org/trinidad/menu"
         resourceBundle="org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundle"
         var="bundle">
     <itemNode id="in1" label="#{bundle.somelabel1}" ../>
     <itemNode id="in2" label="#{bundle.somelabel2}" ../>
   </menu>
   

   Note:

   When you use a sharedNode element to create a submenu and you use resource bundles for the navigation item labels, it is possible that the shared menu model will use the same value for the var attribute on the root menu element. The XMLMenuModel class handles this possibility during parsing by ensuring that each resource bundle is assigned a unique hash key.

5. In the Structure window, right-click menu and choose Insert inside menu, and then choose the desired element (itemNode, groupNode, or sharedNode) from the subsequent context menu, as shown in Figure 20-14, to add to the nodes in your hierarchy.

   Figure 20-14 Context Menu for Inserting Elements into Menu

   

   The elements can be one of the following:

   • itemNode: Specifies a node that performs navigation upon user selection.

   • groupNode: Groups child components; the groupNode itself does no navigation. Child nodes node can be itemNode or another groupNode.

     For example, say you did not need a page for the Employee Data node, but instead, wanted the user to navigate directly to the View Employee page. You would then use a group node to represent the Employee Data page by specifying the id attribute of the desired child node as a value for the group node's idref attribute. The group node allows you to retain the hierarchy without needing to create pages for nodes that are simply aggregates for their children nodes.

   • sharedNode: References another XMLMenuModel instance. A sharedNode element is not a true node; it does not perform navigation nor does it render anything on its own.

     You can insert a sharedNode element anywhere within the hierarchy. The code shown in the following example demonstrates how the sharedNode element adds a submenu on the same level as the first-level Employee Data node.

     <?xml version="1.0" encoding="windows-1252" ?>
     <menu xmlns="http://myfaces.apache.org/trinidad/menu"
       <itemNode id="in0" label="Home" ..>
         <sharedNode ref="#{shared_menu}"/>
         <itemNode id="in1" label="Employee Data" ../>
       </itemNode>
       <itemNode id="in01" label="Help" ../>
     </menu>
     

   As you build the XMLMenuModel metadata file, the tree structure you see in the Structure window exactly mirrors the indentation levels of the menu metadata, as shown in Figure 20-15.

   Figure 20-15 Tree Structure of XMLMenuModel Metadata in Structure Window

   
6. For each element used to create a node, set the properties in the Properties window, as described in Table 20-3 for itemNode elements, Table 20-4 for groupNode elements, and Table 20-5 for sharedNode elements.

   Table 20-3 itemNode Element Attributes

   Attribute	Description
   action	Specify either an outcome string or an EL method binding expression that returns an outcome string. In either case, the outcome string must match the from-outcome value to the navigation case for that node as configured in the faces-config.xml file.
   destination	Specify the URI of the page to navigate to when the node is selected, for example, http://www.oracle.com. If the destination is a JSF page, the URI must begin with "/faces". Alternatively, specify an EL method expression that evaluates to the URI. If both action and destination are specified, destination takes precedence over action.
   focusViewId	Required. The URI of the page that matches the node's navigational result, that is, the to-view-id value of the navigation case for that node as specified in the faces-config.xml file. For example, if the action outcome of the node navigates to /page_one.jsf (as configured in the faces-config.xml file), then focusViewId must also be /page_one.jsf. The focusViewId does not perform navigation. Page navigation is the job of the action or destination attributes. The focusViewId, however, is required for the XMLMenuModel to determine the correct focus path.
   id	Required. Specify a unique identifier for the node. As previous examples show, it is good practice to use "inX" for the ID of each itemNode, where for example, "inX" could be in1, in11, in111, in2, in21, in 211, and so on.
   label	Specify the label text to display for the node. Can be an EL expression to a string in a resource bundle, for example, #{bundle.somelabel}, where bundle must match the root menu element's var attribute value.
   any	Specify any custom attribute for the itemNode.

   A groupNode element does not have the action or destination attribute that performs navigation directly, but it points to a child node that has the action outcome or destination URI, either directly by pointing to an itemNode child (which has the action or destination attribute), or indirectly by pointing to a groupNode child that will then point to one of its child nodes, and so on until an itemNode element is reached. Navigation will then be determined from the action outcome or destination URI of that itemNode element.

   Consider the groupNode code shown in the following example. At runtime, when users click groupNode id="gn1", or groupNode id="gn11", or itemNode id="in1", the navigation outcome is "goToSubTabOne", as specified by the first itemNode reached (that is itemNode id="id1"). Table 20-4 shows the attributes you must specify when you use a groupNode element.

   <?xml version="1.0" encoding="windows-1252" ?>
   <menu xmlns:"http://myfaces.apache.org/trinidad/menu">
     <groupNode id="gn1" idref="gn11" label="GLOBAL_TAB_0">
       <groupNode id="gn11" idref="in1" label="PRIMARY_TAB_0">
         <itemNode id="in1" label="LEVEL2_TAB_0" action="goToSubTabOne"
                   focusViewId="/menuDemo/subtab1.jsf"/>
         <itemNode id="in2" label="LEVEL2_TAB_1" action="goToSubTabTwo"
                   focusViewId="/menuDemo/subtab2.jsf"/>
       </groupNode>
       <itemNode id="in3" label="PRIMARY_TAB_1" focusViewId="/menuDemo/tab2.jsf"
                 destination="/faces/menuDemo/tab2.jsf"/>
     </groupNode>
     <itemNode id="gin1" label="GLOBAL_TAB_1" action="goToGlobalOne" 
               focusViewId="/menuDemo/global1.jsf"/>
     <itemNode id="gin2" label="GLOBAL_TAB_2" 
               destination="/faces/menuDemo/global2.jsf"
               focusViewId="/menuDemo/global2.jsf"/>
   </menu>
   

   Table 20-4 GroupNode Element Attribute

   Attribute	Description
   id	A unique identifier for the group node. As shown in the previous example, it is good practice to use gnX for the ID of each groupNode, where for example, gnX could be gn1, gn2, and so on.
   idref	Specify the ID of a child node, which can be an itemNode, or another groupNode. When adding a groupNode as a child node, that child in turn can reference another groupNode and so on, but eventually an itemNode child must be referenced as the last child. The idref attribute can contain more than one child ID, separated by spaces; the IDs are processed in the order they are listed.
   label	Specify the label text to display for the group node. Can be an EL expression to a string in a resource bundle, for example, #{bundle.somelabel}.
   any	Specify any custom attribute for the groupNode.

   Table 20-5 sharedNode Element Attribute

   Attribute	Description
   ref	Specify the managed bean name of another XMLMenuModel class, as configured in the faces-config.xml file, for example, #{shared_menu}. At runtime, the referenced navigation menu is created, inserted as a submenu into the main (root) menu, and rendered.

When you use the Create ADF Menu Model wizard to create an XMLMenuModel metadata file, JDeveloper automatically configures for you a managed bean for the menu metadata file in the faces-config.xml file, using the metadata file name you provide as the managed bean name.

The following example shows part of the faces-config.xml file that contains the configuration of one XMLMenuModel metadata file. By default, JDeveloper uses the oracle.adf.view.rich.model.MDSMenuModel class as the managed bean class, and request as the managed bean scope, which is required and cannot be changed.

<managed-bean> 
  <managed-bean-name>root_menu</managed-bean-name>
  <managed-bean-class>oracle.adf.view.
                      rich.model.MDSMenuModel</managed-bean-class>
  <managed-bean-scope>request</managed-bean-scope>
  <managed-property>
    <property-name>createHiddenNodes</property-name>
    <value>false</value>
  </managed-property>
  <managed-property>
    <property-name>source</property-name>
    <property-class>java.lang.String</property-class>
    <value>/WEB-INF/root_menu.xml</value>
  </managed-property>
</managed-bean>

In addition, the following managed properties are added by JDeveloper for the XMLMenuModel managed bean:

• createHiddenNodes: When true, specifies that the hierarchical nodes must be created even if the component's rendered attribute is false. The createHiddenNodes value is obtained and made available when the menu metadata source file is opened and parsed. This allows the entire hierarchy to be created, even when you do not want the actual component to be rendered.

• source: Specifies the menu metadata source file to use (for example, /WEB-INF/root_menu.xml).

For each XMLMenuModel metadata file that you create in a project using the wizard, JDeveloper configures a managed bean for it in the faces-config.xml file. For example, if you use a sharedNode element in an XMLMenuModel to reference another XMLMenuModel metadata file, you would have created two metadata files. And JDeveloper would have added two managed bean configurations in the faces-config.xml file, one for the main (root) menu model, and a second managed bean for the shared (referenced) menu model, as shown in the following example.

<!-- managed bean for referenced, shared menu model --> 
<managed-bean>
  <managed-bean-name>shared_menu</managed-bean-name>
  <managed-bean-class>
  <managed-bean-class>oracle.adf.view.
                      rich.model.MDSMenuModel</managed-bean-class>
  </managed-bean-class>
  <managed-bean-scope>request</managed-bean-scope>
  <managed-property>
    <property-name>createHiddenNodes</property-name>
    <value>false</value>
  </managed-property>
  <managed-property>
    <property-name>source</property-name>
    <property-class>java.lang.String</property-class>
    <value>/WEB-INF/shared_menu.xml</value>
  </managed-property>
</managed-bean>

This means, if you use shared nodes in your XMLMenuModel metadata files, the faces-config.xml file will have a root menu model managed bean, plus menu model managed beans for any menu models referenced through shared nodes.

<af:navigationPane var="menuNode" value="#{root_menu}" level="0"
                   hint="buttons">
  <f:facet name="nodeStamp">
    <af:commandNavigationItem text="#{menuNode.label}"
                              action="#{menuNode.doAction}"
                              icon="#{menuNode.icon}"
                              destination="#{menuNode.destination}"
                              visible="#{menuNode.visible}"
                              rendered="#{menuNode.rendered}"/>
  </f:facet>
</af:navigationPane>

1. In the Components window, from the Layout panel, in the Interactive Containers and Headers group, drag and drop a Navigation Pane onto the JSF page for each level of the hierarchy.

   For example, to create any of the pages as shown in the hierarchy in Figure 20-13, you drag and drop four navigationPane components onto the JSF page.

2. For each navigationPane component, in the Properties window, expand the Common section and select one of the following types of navigation items from the Hint dropdown list to determine how the navigationPane displays:

   • bar: Displays the navigation items separated by a bar, for example the Insurance and Paid Time Off links in Figure 20-17.

   • buttons: Displays the navigation items separated by a bar in a global area, for example the Home and Help links in Figure 20-17.

   • choice: Displays the navigation items in a popup list when the associated dropdown icon is clicked. You must include a value for the navigationPane component's icon attribute and you can associate a label to the dropdown list using the title attribute.

   • list: Displays the navigation items in a bulleted list, for example the Health and Dental links in Figure 20-17.

   • tabs: Displays the navigation items as tabs, for example the Benefits and Employee Data tabs in Figure 20-17.

3. In the Level field, enter a number for the appropriate level of metadata in the XMLMenuModel metadata file. The level attribute is a zero-based index number: Starting with global nodes in the metadata file (that is, direct children nodes under the menu element), the level attribute value is 0 (zero), followed by 1 for the next level (typically tabs), 2 for the next level after that (typically bars), and so on.

   The commandNavigationItem component is able to get its metadata from the metadata file through the level attribute on the parent navigationPane component. By default, if you do not specify a level attribute value, 0 (zero) is used, that means the navigationPane component will take the metadata from the first level under the menu element for rendering by the commandNavigationItem component.

4. In the Properties window, expand the Data section and set the following:

   • Value: Set to the menu model managed bean that is configured for the root XMLMenuModel class in the faces-config.xml file.

     Note:

     The value attribute can reference root menu models and menu models referenced by shared nodes. If you reference a shared node in the value attribute, the faces-config.xml file needs to have a new managed bean entry with a different managed bean name than the one which is used in a root menu model definition in the menu model metadata file. This promotes the menu model of a shared node to a root menu model which can then be referred to in the value attribute.

   • Var: Set to text that you will use in the commandNavigationItem components to get the needed data from the menu model.

     As the hierarchy is created at runtime, and each node is stamped, the data for the current node is copied into the var attribute, which can then be addressed using an EL expression. You specify the name to use for this property in the EL expression using the var property.

     Tip:

     You use the same value for the var attribute for every navigationPane component on the page or in the application.

5. In the Components window, from the Layout panel, in the Interactive Containers and Headers group, drag and drop a Navigation Item to the nodeStamp facet of the navigationPane component.
6. Set the values for the remaining attributes that have corresponding values in the metadata using EL expressions that refer to the menu model (whose metadata contains that information). You access these values using the value of the var attribute you set for the parent navigationPane component in Step 4 along with the name of the corresponding itemNode element that holds the value in the metadata. Table 20-6 shows the attributes on the navigation item that has corresponding values in the metadata.

   Table 20-6 Navigation Item Attributes and the Associated Menu Model Attributes

   Navigation Item Attribute	Associated Menu Model Element Attribute
   text	label
   action	doAction
   icon	icon
   destination	destination
   visible	visible
   rendered	rendered

   For example, if you had set the var attribute on the parent navigationPane component to menuNode, you would use #{menuNode.doAction} as the EL expression for the value of the action attribute. This would resolve to the action property set in the metadata for each node. Example 20-3 shows the JSF code for binding to a menu model that has four levels of hierarchical nodes.

<af:form>
  <af:navigationPane hint="buttons" level="0" value="#{root_menu}"
                     var="menuNode">
    <f:facet name="nodeStamp">
      <af:commandNavigationItem text="#{menuNode.label}"
                                action="#{menuNode.doAction}"
                                icon="#{menuNode.icon}"
                                destination="#{menuNode.destination}"/>
    </f:facet>
  </af:navigationPane>
  <af:navigationPane hint="tabs" level="1" value="#{root_menu}"
                     var="menuNode">
    <f:facet name="nodeStamp">
      <af:commandNavigationItem text="#{menuNode.label}"
                                action="#{menuNode.doAction}"
                                icon="#{menuNode.icon}"
                                destination="#{menuNode.destination}"/>
    </f:facet>
  </af:navigationPane>
  <af:navigationPane hint="bar" level="2" value="#{root_menu}"
                     var="menuNode">
    <f:facet name="nodeStamp">
      <af:commandNavigationItem text="#{menuNode.label}"
                                action="#{menuNode.doAction}"
                                icon="#{menuNode.icon}"
                                destination="#{menuNode.destination}"/>
    </f:facet>
  </af:navigationPane>
  <af:navigationPane hint="list" level="3" value="#{root_menu}"
                     var="menuNode">
    <f:facet name="nodeStamp">
      <af:commandNavigationItem text="#{menuNode.label}"
                                action="#{menuNode.doAction}"
                                icon="#{menuNode.icon}"
                                destination="#{menuNode.destination}"/>
    </f:facet>
  </af:navigationPane>
</af:form>

1. In the Components window, from the General Controls panel, in the Location group, drag and drop a BreadCrumbs onto the JSF page.
2. By default, breadcrumb links display in a horizontal line. To change the layout to be vertical, in the Properties window, expand the Common section and select vertical from the Orientation dropdown list.
3. In the Properties window, expand the Data section and the set the following:

   • Value: Set to the root XMLMenuModel managed bean as configured in the faces-config.xml file. This is the same bean to which the navigationPane component is bound.

     Note:

     The value attribute should reference only a root menu model and not any menu models referenced through shared nodes. For example, if you use a shared node in your main XMLMenuModel element, JDeveloper would have created managed bean configurations for the shared node and the root XMLMenuModel bean that consumes the shared model. The shared model managed bean is automatically incorporated into the root menu model managed bean as the menu tree is parsed at startup.

   • Var: Set to text that you will use in the commandNavigationItem components to get the needed data from the menu model.

     As the hierarchy is created at runtime, and each node is stamped, the data for the current node is copied into the var attribute, which can then be addressed using an EL expression. You specify the name to use for this property in the EL expression using the var property.

     Tip:

     You can use the same value for the var attribute for the breadCrumbs component as you did for the navigationPane components on the page or in the application.

4. In the Components window, from the Layout panel, in the Interactive Containers and Headers group, drag a Navigation Item and drop it inside the nodeStamp facet of the breadCrumbs component.

   Note:

   The nodeStamp facet of the breadCrumbs component determines what links appear according to the menu model that you specify for the value attribute of the breadCrumbs component. If you do not specify the menu model you want to render for the value attribute of the breadCrumbs component, no links appear at runtime. Do not use a nodeStamp facet for the breadCrumbs component if you do not use a menu model because no stamps will be required.

5. Set the values for the remaining attributes that have corresponding values in the metadata using EL expressions that refer to the menu model (whose metadata contains that information). You access these values using the value of the var attribute you set for the parent breadCrumbs component in Step 3 along with the name of the corresponding itemNode element that holds the value in the metadata. Table 20-6 shows the attributes on the navigation item that has corresponding values in the metadata.

   For example, if you had set the var attribute on the breadCrumbs component to menuNode, you would use #{menuNode.doAction} as the EL expression for the value of the action attribute. This would resolve to the action property set in the metadata for each node.

<af:breadCrumbs var="menuNode" value="#{root_menu}">
  <f:facet name="nodeStamp">
    <af:commandNavigationItem text="#{menuNode.label}"
                              action="#{menuNode.doAction}"/>
  </f:facet>
</af:breadCrumbs>

1. In the Components window, from the Menus and Toolbars panel, drag and drop a Menu Bar onto the JSF page.
2. In the Properties window, expand the Menu Model section and set the following values:

   • Value: Set to the root XMLMenuModel managed bean as configured in the faces-config.xml file. This is the same bean to which the breadCrumbs component is bound.

     Note:

     The value attribute should reference only a root menu model and not any menu models referenced through shared nodes. For example, if you use a shared node in your main XMLMenuModel element, JDeveloper would have created managed bean configurations for the shared node and the root XMLMenuModel bean that consumes the shared model. The shared model managed bean is automatically incorporated into the root menu model managed bean as the menu tree is parsed at startup.

   • Var: Set to the text that you will use in the commandNavigationItem components to get the needed data from the menu model.

     As the hierarchy is created at runtime, and each node is stamped, the data for the current node is copied into the var attribute, which can then be addressed using an EL expression. You specify the name to use for this property in the EL expression using the var property.

     Tip:

     You can use the same value for the var attribute for the menuBar component as you did for the breadCrumbs component on the page or in the application.

3. In the Components window, from the Layout panel, in the Interactive Containers and Headers group, drag and drop a Navigation Item to the nodeStamp facet of the menuBar component.

   Note:

   The nodeStamp facet of the menuBar component determines what links appear according to the menu model that you specify for the value attribute of the menuBar component. If you do not specify the menu model you want to render for the value attribute of the menuBar component, no menu items will appear at runtime.

4. Set the values for the remaining attributes that have corresponding values in the metadata using EL expressions that refer to the menu model (whose metadata contains that information). You access these values using the value of the var attribute you set for the parent menuBar component in Step 2 along with the name of the corresponding itemNode element that holds the value in the metadata. Table 20-6 shows the attributes on the navigation item that has corresponding values in the metadata.

   For example, if you had set the var attribute on the menuBar component to menuNode, you would use #{menuNode.doAction} as the EL expression for the value of the action attribute. This would resolve to the action property set in the metadata for each node.

<af:menuBar var="menuNode" value="#{root_menu}">
  <f:facet name="nodeStamp">
    <af:commandNavigationItem text="#{menuNode.label}"
                              action="#{menuNode.doAction}"/>
  </f:facet>
</af:menuBar>

The value attribute of the menu model bound component (navigationPane, breadCrumbs, or menuBar) references the managed bean for the XMLMenuModel element. When that managed bean is requested, the following takes place:

• The setSource() method of the XMLMenuModel class is called with the location of the model's metadata, as specified in the managed-property element in the faces-config.xml file.

• An InputStream object to the metadata is made available to the parser (SAXParser); the metadata for the navigation items is parsed, and a call to MenuContentHandler method is made.

• The MenuContentHandler builds the navigation menu tree structure as a List object in the following manner:

  • The startElement() method is called at the start of processing a node in the metadata.

  • The endElement() method is called at the end of processing the node.

  • As each node is processed, a List of navigation menu nodes that make up the page hierarchy of the menu model is created.

• A TreeModel object is created from the list of navigation menu nodes.

• The XMLMenuModel object is created from the TreeModel object.

If a groupNode element has more than one child id in its idref attribute, the following occurs:

• The IDs are processed in the order they are listed. If no child node is found with the current ID, the next ID is used, and so on.

• Once a child node is found that matches the current ID in the idref list, then that node is checked to see if its rendered attribute is set to true, its disabled attribute is set to false, its readOnly attribute is set to false, and its visible attribute is set to true. If any of the criteria is not met, the next ID in the idref list is used, and so on.

• The first child node that matches the criteria is used to obtain the action outcome or destination URI. If no child nodes are found that match the criteria, an error is logged. However, no error will be shown in the UI.

• If the first child node that matches the criteria is another groupNode element, the processing continues into its children. The processing stops when an itemNode element that has either an action or destination attribute is encountered.

• When the itemNode element has an action attribute, the user selection initiates a POST action and the navigation is performed through the action outcome. When the itemNode element has a destination attribute, the user selection initiates a GET action and navigation is performed directly using the destination value.

The XMLMenuModel class provides the model that correctly highlights and enables the items on the navigation menus (such as tabs and bars) as you navigate through the navigation menu system. The model is also instantiated with values for label, doAction, and other properties that are used to dynamically generate the navigation items.

The XMLMenuModel class does no rendering; the model bound component uses the return value from the call to the getFocusRowKey() method to render the navigation menu items for a level on a page.

The commandNavigationItem component housed within the nodeStamp facet of the menu model bound component provides the label text and action outcome for each navigation item. Each time the nodeStamp facet is stamped, the data for the current navigation item is copied into an EL-reachable property, the name of which is defined by the var attribute on the navigationPane component that houses the nodeStamp facet. The nodeStamp displays the data for each item by getting further properties from the EL-reachable property. Once the navigation menu has completed rendering, this property is removed (or reverted back to its previous value). When users select a navigation item, the default JSF actionListener mechanism uses the action outcome string or destination URI to handle the page navigation.

The XMLMenuModel class, in conjunction with nodeStamp facet also controls whether or not a navigation item is rendered as selected. As described earlier, the XMLMenuModel object is created from a tree model, which contains viewId attribute information for each node. The XMLMenuModel class has a method getFocusRowKey() that determines which page has focus, and automatically renders a node as selected if the node is on the focus path. The getFocusRowKey() method in its most simplistic fashion does the following:

• Gets the current viewId attribute.

• Compares the viewId attribute value with the IDs in internal maps used to resolve duplicate viewId values and in the viewIdFocusPathMap object that was built by traversing the tree when the menu model was created.

• Returns the focus path to the node with the current viewId attribute or returns null if the current viewId attribute value cannot be found.

The viewId attribute of a node is used to determine the focus rowKey object. Each item in the model is stamped based on the current rowKey object. As the user navigates and the current viewId attribute changes, the focus path of the model also changes and a new set of navigation items is accessed.

Custom attributes that you have created can be displayed, but only for itemNode and groupNode elements.

Consider the groupNode code shown in the following example. Here, the cardIcon custom attribute is used in groupNode that can be bound to an alternate UI Widget. This model can be used by two UI Widget screens displaying the same model and using two different properties such as, icon and cardIcon.

Example 20-4 shows an example of cardIcon custom attribute in groupNode.

<groupNode
        id="groupNode_risk_management_tools"
        idref="_groupNode_risk_management_tools_"
        label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].RISK_MANAGEMENT_TOOLS}">
				<itemNode id="itemNode_risk_management_tools_setup_and_administration"
            label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].SETUP_AND_ADMINISTRATION}"
            icon="/images/qual_gears_16.png"
            cardIcon="gears.png"
            taskMenuSource="/WEB-INF/oracle/apps/grc/fuseplus/ui/menu/SetupAndAdministration_taskmenu.xml"
            securedResourceName="/WEB-INF/oracle/apps/grc/ui/setup/view/setup/flow/SetupMaintenancePGFlow.xml#SetupMaintenancePGFlow"
            focusViewId="/FuseOverview"
            webApp="GrcCore"
            applicationStripe="fscm"
            showOnHomeGrid="true"/>
				<itemNode id="itemNode_risk_management_tools_perspectives"
            label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PERSPECTIVES}"
            icon="/images/qual_folio_16.png"
            cardIcon="folio.png"
            taskMenuSource="/WEB-INF/oracle/apps/grc/fuseplus/ui/menu/PerspectiveManagement_taskmenu.xml"
            securedResourceName="/WEB-INF/oracle/apps/grc/ui/perspective/view/flow/ManagePerspectivesPGFlow.xml#ManagePerspectivesPGFlow"
            focusViewId="/FuseOverview"
            webApp="GrcCore"
            applicationStripe="fscm"
            showOnHomeGrid="true"/>
				<itemNode id="itemNode_risk_management_tools_surveys"
            label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].SURVEYS}"
            icon="/images/qual_peopleconnect_16.png"
......................

1. In the Applications window, expand the WEB-INF node and double-click faces-config.xml.
2. In the source editor, create one global JSF navigation rule that has the navigation cases for all the nodes (that is, pages) in the page hierarchy.

   For example, the page hierarchy shown in Figure 20-10 has 10 nodes, including the global Help node. Thus, you would create 10 navigation cases within one global navigation rule in the faces-config.xml file, as shown in the following example.

   For each navigation case, specify a unique outcome string, and the path to the JSF page that should be displayed when the navigation system returns an outcome value that matches the specified string.

   <navigation-rule>
     <navigation-case>
       <from-outcome>goHome</from-outcome>
       <to-view-id>/home.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goHelp</from-outcome>
       <to-view-id>/globalhelp.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goEmp</from-outcome>
       <to-view-id>/empdata.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goBene</from-outcome>
       <to-view-id>/benefits.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goIns</from-outcome>
       <to-view-id>/insurance.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goPto</from-outcome>
       <to-view-id>/pto.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goView</from-outcome>
       <to-view-id>/viewdata.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goCreate</from-outcome>
       <to-view-id>/createemp.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goHealth</from-outcome>
       <to-view-id>/health.jsf</to-view-id>
     </navigation-case>
     <navigation-case>
       <from-outcome>goDental</from-outcome>
       <to-view-id>/dental.jsf</to-view-id>
     </navigation-case>
   </navigation-rule>
   

   For information about creating navigation cases in JDeveloper, see Defining Page Flows.

3. Create the JSF pages for all the hierarchical nodes. If you want the navigation tabs to be styled, create a decorativeBox component by dragging and dropping a Decorative Box from the Layout panel of the Components window to each page. Set the theme to determine how you want the tabs to appear. Valid values are:

   • default

   • light

   • medium

   • dark

   Each value describes the look and feel applied to the application when you specify the theme value for the component. The application must use the Skyros skin or a skin that extends from the Skyros skin. The Alta skin does not use themes. You can change how the themes display. See Customizing the Appearance Using Styles and Skins. To consider using a page template to achieve the positioning and visual styling of your JSF pages, see Using Page Templates.

4. In the Components window, from the Layout panel, in the Interactive Containers and Headers group, drag and drop a Navigation Pane to each page. Drag and drop a navigationPane component for each level of the hierarchy on the page.

   For example, to create the Health page, as shown in Figure 20-17, drag and drop four navigationPane components. In the Health page, the components are dropped into specific areas of a template that already contains layout components to create the look and feel of the page.

5. For each navigationPane component, in the Properties window, expand the Common section and select one of the following types of navigation items from the Hint dropdown list to determine how the navigationPane component displays:

   • bar: Displays the navigation items separated by a bar, for example the Insurance and Paid Time Off links in Figure 20-17.

   • buttons: Displays the navigation items separated by a bar in a global area, for example the Home and Help links in Figure 20-17.

   • choice: Displays the navigation items in a popup list when the associated dropdown icon is clicked. You must include a value for the navigationPane component's icon attribute and you can associate a label to the dropdown list using title attribute.

   • list: Displays the navigation items in a bulleted list, for example the Health and Dental links in Figure 20-17.

   • tabs: Displays the navigation items as tabs, for example the Benefits and Employee Data tabs in Figure 20-17.

6. For each navigationPane component, add the needed commandNavigationItem components to represent the different links by dragging and dropping a Navigation Item from the Interactive Containers and Headers group in the Layout panel of the Components window. Drop a Navigation Item as a child to the navigationPane component for each link needed.

   For example, to create the Health page as shown in Figure 20-17, you would use a total of eight commandNavigationItem components, two for each navigationPane component.

   Performance Tip:

   At runtime, when available browser space is less than the space needed to display the contents in a tab or bar of a navigation pane, or the contents of the breadcrumb, ADF Faces automatically displays overflow icons that enable users to select and navigate to those items that are out of view. The number of child components within a navigationPane or breadCrumbs component, and the complexity of the children, will affect the performance of the items within the overflow. You should set the size of the navigationPane or breadCrumbs component to avoid overflow when possible.

7. For each commandNavigationItem component, set the navigation to the desired page. In the Properties window, expand the Common section and provide a static string outcome of an action or use an EL expression to reference an action method in the Action field. If you use a string, it must match the navigation metadata set up in the navigation rules for the page created in Step 2. If referencing a method, that method must return the required string.
8. In the Properties window, expand the Behavior section and select true from the Selected dropdown list if the commandNavigationItem component should be displayed as selected when the page is first rendered, and false if it should not.

   At runtime, when a navigation item is selected by the user, that component's selected attribute changes to selected="true" and the appearance changes to indicate to the user that the item has been selected. For example, in Figure 20-17 the Benefits tab, Insurance bar, and Health list item are shown as selected by a change in either background color or font style. You do not have to write any code to show the selected status; the selected attribute on the commandNavigationItem component for that item takes care of turning on the selected status when the attribute value is true.

<!--  JSF Page Code ----->
<af:navigationPane hint="tabs">
  <af:commandNavigationItem text="Benefits"
                            actionListener="#{myBean.navigationItemAction}"
                            partialSubmit="true"../>
  .
</af:navigationPane>

<!-- Managed Bean Code ----->
public void navigationItemAction(ActionEvent event)
{
  UIComponent actionItem = event.getComponent();
  UIComponent parent = actionItem.getParent();
  while (! (parent instanceof UIXNavigationHierarchy) )
  {
    parent = parent.getParent();
    if (parent == null)
    {
      System.err.println(
       "Unexpected component hierarchy, no UIXNavigationHierarchy found.");
      return;
    }
  }

  List<UIComponent> children = parent.getChildren();
  for (UIComponent child : children)
  {
    FacesBean childFacesBean = ((UIXComponent) child).getFacesBean();
    FacesBean.Type type = childFacesBean.getType();
    PropertyKey selectedKey = type.findKey("selected");
    if (selectedKey != null)
    {
      childFacesBean.setProperty(selectedKey, child==actionItem);
    }
  }
  RequestContext adfContext = RequestContext.getCurrentInstance();
  adfContext.addPartialTarget(parent);
}

<af:navigationPane hint="buttons">
  <af:commandNavigationItem text="Home" action="goHome"/>
  <af:commandNavigationItem text="Help" action="goHelp"/>
</af:navigationPane>
...
<af:navigationPane hint="tabs">
  <af:commandNavigationItem text="Benefits" action="goBene"
                            selected="true"/>
  <af:commandNavigationItem text="Employee Data" action="goEmp"/>
</af:navigationPane>
...
<af:navigationPane hint="bar">
  <af:commandNavigationItem text="Insurance" action="goIns"
                            selected="true"/>
  <af:commandNavigationItem text="Paid Time Off" action="goPto"/>
</af:navigationPane>
...
<af:navigationPane hint="list">
  <af:commandNavigationItem text="Health" action="goHealth"
                            selected="true"/>
  <af:commandNavigationItem text="Dental" action="goDental"/>
</af:navigationPane>

1. In the Components window, from the General Controls panel, in the Location group, drag and drop a BreadCrumbs onto the JSF page.
2. By default, breadcrumb links are displayed in a horizontal line. To change the layout to be vertical, in the Properties window, expand the Common section and select vertical from the Orientation dropdown list.
3. For each link in the breadcrumb, create a commandNavigationItem component by dragging and dropping a Navigation Item from the Interactive Containers and Headers group in the Layout panel of the Components window as a child to the breadCrumbs component. The last item should represent the current page.

   Tip:

   Depending on the renderer or client device type, the last link in the breadcrumb may not be displayed, but you still must add the commandNavigationItem component for it. On clients that do display the last breadcrumb link, the link is always disabled automatically because it corresponds to the current page.

4. For each commandNavigationItem component (except the last), set the navigation to the desired page. In the Properties window, expand the Common section and provide a static string outcome of an action or use an EL expression to reference an action method in the Action field. If you use a string, it must match the navigation metadata set up in the navigation rule for the page created in Step 2 as described in How to Create a Simple Page Hierarchy. If referencing a method, that method must return the required string.

<af:breadCrumbs>
  <af:commandNavigationItem text="Home" action="goHome"/>
  <af:commandNavigationItem text="Benefits" action="goBene"/>
  <af:commandNavigationItem text="Insurance" action="goIns"/>
  <af:commandNavigationItem text="Health"/>
</af:breadCrumbs>

By default, the size of the tabs rendered by a navigationPane component that has its hint attribute value set to tabs is determined by the length of the text used as the label. You can configure the size of these tabs by configuring the following attributes for the navigationPane component:

• maxTabSize: Set to a size in pixels. The tabs will never be larger than this size.

• minTabSize: Set to a size in pixels. The tabs will never be smaller than this size.

• truncationStyle: Set to ellipsis if you want an ellipses to display after truncated text that cannot fit, based on the maxTabSize. If set to none, then if the text does not fit on the tab, it will simply be truncated.

You can use the -tr-layout-type skinning key to configure the type of indicator that the navigationPane component renders in an application window that is in a compressed layout. That is, the application window is not wide enough to display all the navigation tabs.

Figure 20-18 shows an overflow indicator that renders a dropdown list where the user can choose the navigation tab to navigate to.

Figure 20-18 Overflow Indicator for a navigationPane Component in Compressed Layout

Example 20-8 shows how you configure the -tr-layout-type skinning key so that the navigationPane component displays an overflow indicator.

Rather than display overflow indicators, as shown in Figure 20-18, you can configure the -tr-layout-type skinning key for the navigationPane component so that the component renders a conveyor belt where users can scroll left or right to tabs that are not currently visible. Configuring the -tr-layout-type skinning key also renders all navigation tabs in one dropdown list, as shown in Figure 20-19. This configuration only takes effect if the navigationPane component's hint attribute is set to tabs. If the navigationPane component's hint attribute is set to another value, set the -tr-layout-type skinning key to overflow.

Example 20-9 shows how you configure the -tr-layout-type skinning key so that the navigationPane component renders a conveyor belt.

Figure 20-19 shows the navigationPane component rendering a conveyor belt in a compressed layout.

Figure 20-19 Conveyor Belt for a navigationPane Component in Compressed Layout

See Customizing the Appearance Using Styles and Skins.

af|navigationPane {
  -tr-layout-type: overflow;
}

af|navigationPane {
  -tr-layout-type: conveyor;
}  

1. Create a train stop model class. A train stop model object holds the row data for stamping each train stop. The train stop model implementation you create should set and get the properties for each stop in the train, and define the methods required to render a train stop. The properties of a train stop correspond to the properties of the commandNavigationItem component. This will allow you to use the simplified binding (<af:train value="#{simpleTrainModel}"/>).

   Alternatively, you can extend the abstract class TrainStopModel, and implement the abstract methods in the subclass.

   The properties on the commandNavigationItem component that will be automatically EL bound are:

   • action: A static action outcome or a reference to an action method that returns an action outcome. The outcome is used for page navigation through the default ActionListener mechanism in JSF.

   • disabled: A boolean value that indicates whether or not the train stop should be noninteractive. Note that the train behavior you elect to use affects the value of this property. See Step 2.

   • immediate: A boolean value that determines whether or not data validations should be performed. Note that the train behavior you elect to use affects the value of this property. See Step 2.

   • messageType: A value that specifies a message alert icon over the train stop image. Possible values are none, error, warning, and info, and complete. For information about messages, see Displaying Tips, Messages, and Help.

   • shortDesc: A value that is commonly used by client user agents to display as tooltip help text for the train stop.

   • showRequired: A boolean value that determines whether or not to display an asterisk next to the train stop to indicate that required values are contained in that train stop page.

   • textAndAccessKey: A single value that sets both the label text to display for the train stop, as well as the access key to use.

   • visited: A boolean value that indicates whether or not the train stop has already been visited. Note that the train behavior you elect to use affects the value of this property. See Step 2.

2. Create a class based on the MenuModel class to facilitate the construction of a train model.

   The MenuModel implementation of your train model must have a specific train behavior. The ProcessMenuModel class in the org.apache.myfaces.trinidad.model package is a reference implementation of the MenuModel class that supports the two train behaviors: Plus One and Max Visited. To implement a train behavior for a train model, you can either extend the ProcessMenuModel class, or create your own.

   In your train model class, you override the getFocusRowKey() method (see the MenuModel class) and implement a train behavior (see the ProcessMenuModel and ProcessUtils classes).

   The train behaviors provided in the ProcessMenuModel class have an effect on the visited, immediate, and disabled properties of the commandNavigationItem component.

   The visited attribute is set to true only if that page in the train has been visited. The ProcessMenuModel class uses the following logic to determine the value of the visited attribute:

   • Max Visited: A max visited stop is the farthest stop the user has visited in the current session. The visited attribute is set to true for any stop if it is before a max visited stop, or if it is the max visited stop itself.

   • Plus One: A plus one stop does not keep track of the farthest stop that was visited. The visited attribute is set to true for the current stop, or a stop that is before the current stop.

   When the data on the current page does not have to be validated, the immediate attribute should be set to true. Suppose page 4 in the Plus One behavior described earlier has data that must be validated. If the user has advanced to page 4 and then goes back to page 2, the user has to come back to page 4 again later to proceed on to page 5. This means the data on page 4 does not have to be validated when going back to page 1, 2, or 3 from page 4, but the data should be validated when going ahead to page 5. For information about how the immediate attribute works, see Using the Immediate Attribute.

   The ProcessMenuModel class uses the following logic to determine the value of the immediate attribute:

   • Plus One: The immediate attribute is set to true for any previous step, and false otherwise.

   • Max Visited: When the current page and the maximum page visited are the same, the behavior is the same as the Plus One scenario. If the current page is before the maximum page visited, then the immediate attribute is set to false.

     Note:

     In an application that uses the ADF Model layer, the pageDefinition element in a page definition file supports an attribute (SkipValidation) that, when set to true, skips data validation for the page. Set SkipValidation to true if you want users to navigate from the page without invoking data validation. See pageNamePageDef.xml in Developing Fusion Web Applications with Oracle Application Development Framework.

   The disabled attribute is set to true only if that page in the train cannot be reached from the current page. The ProcessMenuModel class uses the following logic to determine the value of the disabled attribute:

   • Plus One: The disabled attribute will be true for any page beyond the next available page.

   • Max Visited: When the current stop and the maximum page visited are the same, the behavior is the same as the Plus One behavior. If the current page is before the maximum page visited, then disabled is set to true for any page beyond the maximum page visited.

1. Configure a managed bean for each stop in the train, with values for the properties that require setting at instantiation, to create the train stops to pass into an ArrayList.

   If a train stop has subprocess train children, there should be a managed bean for each subprocess train stop as well.

   Each bean should be an instance of the train stop model class created in How to Create the Train Model. Example 20-10 shows sample managed bean code for train stops in the faces-config.xml file.

   The managed properties set the values to the train stop model object (the class created in Step 1 in How to Create the Train Model).

   The viewId value is the path and file name to the page that is navigated to when the user clicks a train stop.

   The outcome property value is the action outcome string that matches a JSF navigation case. The default JSF ActionListener mechanism is used to choose the page associated with the train stop as the view to navigate to when the train stop is selected.

   The label property value is the train stop label text that displays beneath the train stop image. The value can be static or an EL expression that evaluates to a string in a resource bundle.

   The model property value is the managed bean name of the train model (see Example 20-14).

   If a train stop has subprocess train children, the managed bean configuration should also include the property (for example, children) that lists the managed bean names of the subprocess train stops in value expressions (for example, #{train4a}), as shown in Example 20-11.

2. Configure a managed bean that is an instance of an ArrayList object to create the list of train stops to pass into the train tree model.

   Example 20-12 shows sample managed bean code for creating the train stop list.

   The list-entries element contains the managed bean names for the train stops (excluding subprocess train stops) in value expressions (for example, #{train1}), listed in the order that the stops should appear on the train.

3. Configure a managed bean to create the train tree model from the train list.

   The train tree model wraps the entire train list, including any subprocess train lists. The train model managed bean should be instantiated with a childProperty value that is the same as the property name that represents the list of subprocess train children (see Example 20-11).

   The childProperty property defines the property name to use to get the child list entries of each train stop that has a subprocess train.

   The wrappedData property value is the train list instance to wrap, created by the managed bean in Step 2.

4. Configure a managed bean to create the train model from the train tree model.

   This is the bean to which the train component on each page is bound. The train model wraps the train tree model. The train model managed bean should be instantiated with a viewIdProperty value that is the same as the property name that represents the pages associated with the train stops.

   Example 20-14 shows sample managed bean code for a train model.

   The viewIdProperty property value is set to the property that is used to specify the page to navigate to when the user clicks the train stop.

   The wrappedData property value is the train tree instance to wrap, created by the managed bean in Step 3.

   The maxPathKey property value is the value to pass into the train model for using the Max Visited train behavior. ADF Faces uses the Max Visited behavior when a non-null maxPathKey value is passed into the train model. If the maxPathKey value is null, then ADF Faces uses the Plus One behavior.

<!-- First train stop -->
<managed-bean>
  <managed-bean-name>train1</managed-bean-name>
  <managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
  <managed-bean-scope>none</managed-bean-scope>
  <managed-property>
    <property-name>viewId</property-name>
    <value>/train.jsf</value>
  </managed-property>
  <managed-property>
    <property-name>outcome</property-name>
    <value>guide.train</value>
  </managed-property>
  <managed-property>
    <property-name>label</property-name>
    <value>First Step</value>
  </managed-property>
  <managed-property>
    <property-name>model</property-name>
    <value>trainMenuModel</value>
  </managed-property>
</managed-bean>
...
<!-- Second train stop -->
<managed-bean>
  <managed-bean-name>train2</managed-bean-name>
  <managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
  <managed-bean-scope>none</managed-bean-scope>
  <managed-property>
    <property-name>viewId</property-name>
    <value>/train2.jsf</value>
  </managed-property>
  <managed-property>
    <property-name>outcome</property-name>
    <value>guide.train2</value>
  </managed-property>
  <managed-property>
    <property-name>label</property-name>
    <value>Second Step</value>
  </managed-property>
  <managed-property>
    <property-name>model</property-name>
    <value>trainMenuModel</value>
  </managed-property>
</managed-bean>
...
<!-- And so on -->
...

<managed-bean>
  <managed-bean-name>train4</managed-bean-name>
  <managed-bean-class>project1.DemoTrainStopModel</managed-bean-class>
  <managed-bean-scope>none</managed-bean-scope>
  <managed-property>
    <property-name>viewId</property-name>
    <value>/train4.jsf</value>
  </managed-property>
  <managed-property>
    <property-name>outcome</property-name>
    <value>guide.train4</value>
  </managed-property>
  <managed-property>
    <property-name>label</property-name>
    <value>Fourth Step</value>
  </managed-property>
  <managed-property>
    <property-name>children</property-name>
    <list-entries>
      <value-class>project1.DemoTrainStopModel</value-class>
      <value>#{train4a}</value>
      <value>#{train4b}</value>
      <value>#{train4c}</value>
    </list-entries>
  </managed-property>
  <managed-property>
    <property-name>model</property-name>
    <value>trainMenuModel</value>
  </managed-property>
</managed-bean>

<managed-bean>
  <managed-bean-name>trainList</managed-bean-name>
  <managed-bean-class>
    java.util.ArrayList
  </managed-bean-class>
  <managed-bean-scope>
    none
  </managed-bean-scope>
  <list-entries>
    <value-class>project1.DemoTrainStopModel</value-class>
    <value>#{train1}</value>
    <value>#{train2}</value>
    <value>#{train3}</value>
    <value>#{train4}</value>
    <value>#{train5}</value>
  </list-entries>
</managed-bean>

<managed-bean>
  <managed-bean-name>trainTree</managed-bean-name>
    <managed-bean-class>
     org.apache.myfaces.trinidad.model.ChildPropertyTreeModel
    </managed-bean-class>
  <managed-bean-scope>none</managed-bean-scope>
  <managed-property>
    <property-name>childProperty</property-name>
    <value>children</value>
  </managed-property>
  <managed-property>
    <property-name>wrappedData</property-name>
    <value>#{trainList}</value>
  </managed-property>
</managed-bean>

<managed-bean>
  <managed-bean-name>trainMenuModel</managed-bean-name>
    <managed-bean-class>
     org.apache.myfaces.trinidad.model.ProcessMenuModel
    </managed-bean-class>
  <managed-bean-scope>session</managed-bean-scope>
  <managed-property>
    <property-name>viewIdProperty</property-name>
    <value>viewId</value>
  </managed-property>
  <managed-property>
    <property-name>wrappedData</property-name>
    <value>#{trainTree}</value>
  </managed-property>
  <!-- to enable plusOne behavior instead, comment out the maxPathKey property -->
  <managed-property>
    <property-name>maxPathKey</property-name>
    <value>TRAIN_DEMO_MAX_PATH_KEY</value>
  </managed-property>
</managed-bean>

1. In the Components window, from the General Controls panel, in the Location group, drag and drop a Train onto the JSF page. Optionally drag and drop a Train Button Bar.
2. Bind the component. If your MenuModel implementation for a train model returns a rowData object similar to the public abstract class oracle.adf.view.rich.model.TrainStopModel, you can use the simplified form of train binding in the train components, as shown in Example 20-15.

<af:train value="#{trainMenuModel}"/>
<af:trainButtonBar value="#{trainMenuModel}"/>

<af:train value="#{aTrainMenuModel}" var="stop">
  <f:facet name="nodeStamp">
    <af:commandNavigationItem
      text="#{stop.label}"
      action="#{stop.outcome}"
      ...
    </af:commandNavigationItem>
  </f:facet>
</af:train>