Using Navigation Items for a Page Hierarchy

Working with Navigation Components 18-13 Figure 18–6 First-Level Page As you can see, with large hierarchies, this process can be very time consuming and error prone. Instead of creating each of the separate commandNavigationItem components on each page, for larger hierarchies you can use an XMLMenuModel implementation and managed beans to dynamically generate the navigation items on the pages. The XMLMenuModel class, in conjunction with a metadata file, contains all the information for generating the appropriate number of hierarchical levels on each page, and the navigation items that belong to each level. Instead of using multiple commandNavigationItem components within each navigationPane component and marking the current items as selected on each page, you declaratively bind each navigationPane component to the same XMLMenuModel implementation, and use one commandNavigationItem component in the nodeStamp facet to provide the navigation items. The commandNavigationItem component acts as a stamp for navigationPane component, stamping out navigation items for nodes at every level held in the XMLMenuModel object. The JSF navigation model, through the default ActionListener mechanism, is used to choose the page to navigate to when users select a navigation item. For more information about the menu model, see Section 18.6, Using a Menu Model to Create a Page Hierarchy . On any page, to show the user’s current position in relation to the entire page hierarchy, you use the breadCrumbs component with a series of commandNavigationItem components or one commandNavigationItem component as a nodeStamp, to provide a path of links from the current page back to the root page that is, the current nodes in the focus path. For more information about creating a navigational hierarchy using the XMLMenuModel, see Section 18.6, Using a Menu Model to Create a Page Hierarchy . For more information about manually creating a navigational hierarchy, see Section 18.7, Creating a Simple Navigational Hierarchy . Note: If you want to create menus that can be used to cause some sort of change in an application for example, a File menu that contains the commands Open and Delete, then see Chapter 14, Using Menus, Toolbars, and Toolboxes . 18-14 Web User Interface Developers Guide for Oracle Application Development Framework

18.6 Using a Menu Model to Create a Page Hierarchy

Section 18.5, Using Navigation Items for a Page Hierarchy describes how you can create a navigation menu for a very simple page hierarchy using navigationPane components with multiple commandNavigationItem children components. Using the same method for more complex page hierarchies would be time consuming and error prone. It is inefficient and tedious to manually insert and configure individual commandNavigationItem components within navigationPane and breadCrumbs components on several JSF pages to create all the available items for enabling navigation. It is also difficult to maintain the proper selected status of each item, and to deduce and keep track of the breadcrumb links from the current page back to the root page. For more complex page hierarchies and even for simple page hierarchies, a more efficient method of creating a navigation menu is to use a menu model. A menu model is a special kind of tree model. A tree model is a collection of rows indexed by row keys. In a tree, the current row can contain child rows for more information about a tree model, see Section 10.5, Displaying Data in Trees . A menu model is a tree model that knows how to retrieve the rowKey of the node that has the current focus the focus node. The menu model has no special knowledge of page navigation and places no requirements on the nodes that go into the tree. The XMLMenuModel class creates a menu model from a navigation tree model. But XMLMenuModel class has additional methods that enable you to define the hierarchical tree of navigation in XML metadata. Instead of needing to create Java classes and configuring many managed beans to define and create the menu model as you would if you used one of the other ADF Faces menu model classes, you create one or more XMLMenuModel metadata files that contain all the node information needed for XMLMenuModel class to create the menu model. To create a page hierarchy using a menu model, you do the following: ■ Create the JSF navigation rule and navigation cases for the page hierarchy and then create the XMLMenuModel metadata. See Section 18.6.1, How to Create the Menu Model Metadata . ■ Configure the managed bean for the XMLMenuModel class. The application uses the managed bean to build the hierarchy. This configuration is automatically done for you when you use the Create ADF Menu Model dialog in JDeveloper to create Note: If your application uses the Fusion technology stack or the ADF Controller, then you should use ADF task flows and an XMLMenuModel implementation to create the navigation system for your application page hierarchy. For details, see the Creating a Page Hierarchy section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Performance Tip: Using the navigationPane component with the menu model results in a full page refresh every time the user switches the tab. Instead, you can use the panelTabbed component see Section 8.9, Displaying or Hiding Contents in Accordion Panels and Tabbed Panels . This component has built-in support for partial page rendering of the tabbed content. However, it cannot bind to any navigational model and the whole content must be available from within the page, so it has limited applicability. Working with Navigation Components 18-15 the XMLMenuModel metadata file. See Section 18.6.2, What Happens When You Use the Create ADF Menu Model Wizard . ■ Create a JSF page for each of the hierarchical nodes including any global nodes. ■ On each page, bind the navigationPane and breadCrumbs components to the XMLMenuModel class. See Section 18.6.3, How to Bind to the XMLMenuModel in the JSF Page and Section 18.6.4, How to Use the breadCrumbs Component .

18.6.1 How to Create the Menu Model Metadata

The XMLMenuModel metadata file is a representation of a navigation menu for a page hierarchy in XML format. In the XMLMenuModel metadata file, the entire 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. The remaining nodes in the 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 as depicted in Figure 18–7 . Figure 18–7 Sample Page Hierarchy If you wanted each node in the hierarchy to have its own page to which a user can navigate, then you would create an item node in the metadata for each page. You nest the children nodes inside the 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 nodes 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. You can also nest menu models using the shared nodes. This approach is recommended 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 model so that it could be reused across an application. Instead of creating the nodes for each use, you could instead create the Tip: Typically, you would use a page template that contains a facet for each level of items including global items and breadcrumbs to create each JSF page. For example, the navigationPane component representing global items might be wrapped in a facet named navigationGlobal, and the navigationPane component representing first level tabs might be wrapped in a navigation1 facet. For information about creating page templates, see Chapter 19, Creating and Reusing Fragments, Page Templates, and Components . 18-16 Web User Interface Developers Guide for Oracle Application Development Framework nodes once as a separate menu and then within the different hierarchies, use a shared node to reference the Benefits menu model. Example 18–4 shows an XMLMenuModel metadata file for defining a page hierarchy illustrated in Figure 18–7 . Example 18–4 XMLMenuModel Metadata File Sample ?xml version=1.0 encoding=windows-1252 ? menu xmlns=http:myfaces.apache.orgtrinidadmenu itemNode id=Home focusViewId=home.jspx label=Home action=goHome itemNode id=benefits focusViewId=benefits.jspx action=goBene label=Benefits itemNode id=insurance focusViewId=insurance.jspx action=goIns label=Insurance itemNode id=health focusViewId=health.jspx action=goHealth label=Health itemNode id=dental focusViewId=dental.jspx action=goDental label=Dental itemNode itemNode id=pto focusViewId=pto.jspx action=goPto label=Paid Time Off itemNode id=vacation focusViewId=vacation.jspx action=goVacation label=Vacation itemNode id=sick focusViewId=sick.jspx action=goSick label=Sick Pay itemNode itemNode groupNode id=empData idref=newEmp label=Employee Data itemNode id=newEmp focusViewId=createemp.jspx action=goCreate label=Create New Employee itemNode id=viewdata focusViewId=viewdata.jspx action=goView label=View Data groupNode itemNode itemNode id=Help focusViewId=globalhelp.jspx action=goHelp label=Help itemNode id=Preferences focusViewId=preferences.jspx action=goPref label=Preferences menu Within the root menu element, global nodes are any types of nodes that are direct children of the menu element; in other words, the first level of elements under the menu element are global nodes. For example, the code in Example 18–4 shows three global nodes, namely, Home, Help, and Preferences. Within a first-level child node, nodes can be nested to provide more levels of navigation. For example, the code in Example 18–4 shows two second-level nodes under Home, namely, Benefits and Employee Data. Within Benefits, there are two third-level nodes, Insurance and Paid Time Off, and so on. JDeveloper simplifies creating metadata for an XMLMenuModel class by providing the Create ADF Menu Model wizard. To create the XMLMenuModel metadata: 1. 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 18–4 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 18–5 . Working with Navigation Components 18-17 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. Example 18–5 Global Navigation Rule for a Page Hierarchy in faces-config.xml navigation-rule navigation-case from-outcomegoHomefrom-outcome to-view-idhome.jspxto-view-id navigation-case navigation-case from-outcomegoHelpfrom-outcome to-view-idglobalhelp.jspxto-view-id navigation-case navigation-case from-outcomegoEmpfrom-outcome to-view-idempdata.jspxto-view-id navigation-case navigation-case from-outcomegoBenefrom-outcome to-view-idbenefits.jspxto-view-id navigation-case navigation-case from-outcomegoInsfrom-outcome to-view-idinsurance.jspxto-view-id navigation-case navigation-case from-outcomegoPtofrom-outcome to-view-idpto.jspxto-view-id navigation-case navigation-case from-outcomegoViewfrom-outcome to-view-idviewdata.jspxto-view-id navigation-case navigation-case from-outcomegoCreatefrom-outcome to-view-idcreateemp.jspxto-view-id navigation-case navigation-case from-outcomegoHealthfrom-outcome to-view-idhealth.jspxto-view-id navigation-case navigation-case from-outcomegoDentalfrom-outcome to-view-iddental.jspxto-view-id navigation-case ... navigation-rule For more information about creating navigation cases in JDeveloper, see Section 2.3, Defining Page Flows . 2. In the Application Navigator, locate the project where you wish to create the XMLMenuModel metadata file. Under the project’s Web Content - WEB-INF folder, right-click the faces-config.xml file, and choose Create ADF Menu from the context menu.