How to Create the Menu Model Metadata

18-18 Web User Interface Developers Guide for Oracle Application Development Framework 3. In the Create ADF Menu Model dialog, enter a file name for the XMLMenuModel metadata file, for example, root_menu. 4. Enter a directory for the metadata file. By default, JDeveloper will save the XMLMenuModel metadata file in the WEB-INF directory of the application. When you click OK, JDeveloper automatically does the following for you: ■ Creates a managed bean for the model in the faces-config.xml file, using the name specified in Step 3 for the managed bean name. ■ Sets the value of the managed beans source managed property to the XMLMenuModel metadata file, specified in Step 3, for example, WEB-INFroot_menu.xml. ■ Displays the source file that is, WEB-INFroot_menu.xml as a blank XMLMenuModel metadata file in the source editor, as shown in Example 18–6 . Example 18–6 Blank XMLMenuModel Metadata File ?xml version=1.0 encoding=windows-1252 ? menu xmlns=http:myfaces.apache.orgtrinidadmenumenu For more information about the managed bean configuration JDeveloper automatically adds for you, see Section 18.6.2, What Happens When You Use the Create ADF Menu Model Wizard .

5. Select the menu node in the Structure window and enter the appropriate

information in the Property Inspector. Table 18–1 shows the attributes you can specify for the menu element. Example 18–7 shows sample XMLMenuModel metadata code that uses EL expressions to access a resource bundle for the navigation item labels. Example 18–7 XMLMenuModel Using Resource Bundle ?xml version=1.0 encoding=windows-1252 ? menu xmlns=http:myfaces.apache.orgtrinidadmenu 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 the Creating a Page Hierarchy section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Table 18–1 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.MenuBu ndle. 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 Example 18–7 for a sample XMLMenuModel metadata file that uses a resource bundle. xmlns Required. Set to http:myfaces.apache.orgtrinidadmenu Working with Navigation Components 18-19 resourceBundle=org.apache.myfaces.demo.xmlmenuDemo.resource.MenuBundle var=bundle itemNode id=in1 label={bundle.somelabel1} .. itemNode id=in2 label={bundle.somelabel2} .. menu For more information about using resource bundles, see Chapter 21, Internationalizing and Localizing Pages . 6. In the Structure window, add the desired elements for the nodes in your hierarchy, using itemNode, groupNode, or sharedNode as needed. To begin, right-click menu and choose Insert inside menu, and then choose the desired element from the context menu, as shown in Figure 18–8 . Figure 18–8 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. For example, in the code shown in Example 18–8 , the sharedNode element adds a submenu on the same level as the global nodes. Note: When you use a sharedNode element to create a submenu and you use resource bundles for the navigation item labels, it is quite 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. 18-20 Web User Interface Developers Guide for Oracle Application Development Framework Example 18–8 SharedNode Sample Code ?xml version=1.0 encoding=windows-1252 ? menu xmlns=http:myfaces.apache.orgtrinidadmenu itemNode id=in1 label=Home .. sharedNode ref={shared_menu} itemNode id=in6 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 18–9 . Figure 18–9 Tree Structure of XMLMenuModel Metadata in Structure Window

7. For each element used to create a node, set the properties in the Property

Inspector, as described in Table 18–2 for itemNode elements, Table 18–3 for groupNode elements, and Table 18–4 for sharedNode elements. Table 18–2 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. Working with Navigation Components 18-21 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 Example 18–9 . 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 18–3 shows the attributes you must specify when you use a groupNode element. Example 18–9 groupNode Elements ?xml version=1.0 encoding=windows-1252 ? menu xmlns:http:myfaces.apache.orgtrinidadmenu 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=menuDemosubtab1.jspx itemNode id=in2 label=LEVEL2_TAB_1 action=goToSubTabTwo focusViewId=menuDemosubtab2.jspx groupNode itemNode id=in3 label=PRIMARY_TAB_1 focusViewId=menuDemotab2.jspx destination=facesmenuDemotab2.jspx groupNode itemNode id=gin1 label=GLOBAL_TAB_1 action=goToGlobalOne focusViewId=menuDemoglobal1.jspx itemNode id=gin2 label=GLOBAL_TAB_2 destination=facesmenuDemoglobal2.jspx focusViewId=menuDemoglobal2.jspx menu 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.jspx as configured in the faces-config.xml file, then focusViewId must also be page_one.jspx. 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 shown in Example 18–4 , 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. Table 18–2 Cont. itemNode Element Attributes Attribute Description 18-22 Web User Interface Developers Guide for Oracle Application Development Framework

18.6.2 What Happens When You Use the Create ADF Menu Model Wizard

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 metadata file in the faces-config.xml file, using the metadata file name you provide as the managed bean name. Example 18–10 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. Example 18–10 Managed Bean Configuration for XMLMenuModel in faces-config.xml managed-bean managed-bean-nameroot_menumanaged-bean-name managed-bean-classoracle.adf.view.rich.model. MDSMenuModelmanaged-bean-class managed-bean-scoperequestmanaged-bean-scope managed-property property-namecreateHiddenNodesproperty-name valuefalsevalue managed-property managed-property property-namesourceproperty-name property-classjava.lang.Stringproperty-class valueWEB-INFroot_menu.xmlvalue managed-property managed-bean Table 18–3 GroupNode Element Attribute Attribute Description id A unique identifier for the group node. As shown in Example 18–4 , 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}. Table 18–4 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. Working with Navigation Components 18-23 In addition, the following managed properties are added by JDeveloper for each 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 source menu metadata 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. The createHiddenNodes property must be placed before the source property, which JDeveloper does for you when the managed bean is automatically configured. The XMLMenuModel managed bean must have this value already set to properly parse and create the menus XML metadata from the source managed property. ■ source: Specifies the source metadata file to use. 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 as shown in Example 18–8 , 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 Example 18–11 . Example 18–11 Managed Bean for Shared Menu Model in faces-config.xml -- managed bean for referenced, shared menu model -- managed-bean managed-bean-nameshared_menumanaged-bean-name managed-bean-class managed-bean-classoracle.adf.view. rich.model.MDSMenuModelmanaged-bean-class managed-bean-class managed-bean-scoperequestmanaged-bean-scope managed-property property-namecreateHiddenNodesproperty-name valuetruevalue managed-property managed-property property-namesourceproperty-name property-classjava.lang.Stringproperty-class valueWEB-INFshared_menu.xmlvalue managed-property managed-bean This means, if you use shared nodes in your XMLMenuModel metadata file, 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.

18.6.3 How to Bind to the XMLMenuModel in the JSF Page

Each node in the page hierarchy corresponds to one JSF page. On each page, you use one navigationPane component for each level of navigation items that you have defined in your XMLMenuModel metadata file, including global items. Levels are defined by a zero-based index number: Starting with global nodes in the metadata file that is, direct children nodes under the menu element as shown in Example 18–4 , the 18-24 Web User Interface Developers Guide for Oracle Application Development Framework 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. For example, if you had a page hierarchy like the one shown in Figure 18–7 and Example 18–4 , you would use three navigationPane components on a page such as Home for the three levels of navigation under the Home node, plus one more navigationPane component for the global nodes. As described in Section 18.7.1, How to Create a Simple Page Hierarchy , you use the hint attribute to specify the type of navigation item you want to use for each hierarchical level for example, buttons, tabs, or bar. But instead of manually adding multiple commandNavigationItem components yourself to provide the navigation items, you bind each navigationPane component to the XMLMenuModel managed bean, and insert only one commandNavigationItem component into the nodeStamp facet of each navigationPane component, as shown in Example 18–12 . Example 18–12 navigationPane Component Bound to XMLMenuModel Managed Bean af:navigationPane var=menuNode value={root_menu} level=1 hint=tabs 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 The nodeStamp facet and its single commandNavigationItem component, in conjunction with the XMLMenuModel managed bean, are responsible for: ■ Stamping out the correct number of navigation items in a level. ■ Displaying the correct label text and other properties as defined in the metadata. For example, the EL expression {menuNode.label} retrieves the correct label text to use for a navigation item, and {menuNode.doAction} evaluates to the action outcome defined for the same item. ■ Marking the current items in the focus path as selected. You should not specify the selected attribute at all for the commandNavigationItem components. Tip: Because the menu model dynamically determines the hierarchy that is, the links that appear in each navigationPane component and also sets the current nodes in the focus path as selected, you can practically reuse the same code for each page. You need to change only the page’s document title, and add the specific page contents to display on that page. Because of this similar code, you can create a single page fragment that has just the facets containing the navigationPane components, and include that fragment in each page, where you change the page’s document title and add the page contents. Note: If there is no node information in the XMLMenuModel object for a particular hierarchical level for example, level 3 lists, ADF Faces does not display those items on the page even though the page contains the navigationPane code for that level. Working with Navigation Components 18-25 To bind to the XMLMenuModel managed bean: 1. If you want the menu tabs to be styled, create a decorativeBox component by dragging and dropping a Decorative Box from the Layout section of the Component Palette to the JSF page. Set the theme to determine how you want the tabs to appear. Valid values are: ■ default: Body is white with a blue border. Top-left corner is rounded. ■ light: Body is light blue. Top-left corner is rounded. ■ medium: Body is medium blue. Top-left corner is rounded. ■ dark: Body is dark blue. Top-left corner is rounded. You can change how the themes are displayed. For more information, see Chapter 20, Customizing the Appearance Using Styles and Skins .

2. Create a navigationPane component by dragging and dropping a Navigation

Pane from the Component Palette to the JSF page. Add a navigationPane component for each level of the hierarchy. For example, to create any of the pages as shown in the hierarchy in Figure 18–5 , you would drag and drop four navigationPane components. 3. For each navigationPane component, in the Property Inspector, expand the Common section and set the Hint attribute to one of the following types of navigation items to determine how the navigationPane will display the following: ■ bar: Displays the navigation items separated by a bar, for example the Insurance and Paid Time Off links in Figure 18–11 . ■ buttons: Displays the navigation items separated by a bar in a global area, for example the Home and Help links in Figure 18–11 . ■ 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 18–11 . ■ tabs: Displays the navigation items as tabs, for example the Benefits and Employee Data tabs in Figure 18–11 . 4. Set the level attribute to point to 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 as shown in Example 18–4 , 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. Tip: The Navigation Pane component can be found in the Layout pane of the Component Palette.