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.