Menu components are used to create menus that allow users to add or edit items, search data, change the view, or launch help. For example, the ADF Faces Components Demo application contains both a menu bar and a toolbar, as shown in Figure 15-2.

Figure 15-2 Menu Bar and Toolbar in File Explorer Application

When a user chooses a menu item in the menu bar, the menu component displays a list of menu items, as shown in Figure 15-3.

Figure 15-3 Menu in the File Explorer Application

Description of "Figure 15-3 Menu in the File Explorer Application"

As shown in Figure 15-4, menus can be nested.

Figure 15-4 Nested Menu Items

Description of "Figure 15-4 Nested Menu Items"

Buttons in a toolbar also allow a user to invoke some sort of action on an application or to open a context menu that behaves the same as a standard menu.

You can organize toolbars and menu bars using a toolbox. The toolbox gives you the ability to define relative sizes for the toolbars on the same line and to define several layers of toolbars and menu bars vertically.

1. If you plan on using more than one menu bar or a combination of toolbars and menu bars, create a toolbox component by dragging and dropping a Toolbox from the Menus and Toolbars panel of the Components window.

   Tip:

   The panelHeader, showDetailHeader, and showDetailItem components support a toolbar facet for adding toolboxes and toolbars to section headers and accordion panel headers.

2. Create a menu bar by dragging and dropping a Menu Bar from the Components window. If you are using a toolbox component, the Menu Bar should be dropped as a direct child of the toolbox component.

   Tip:

   Toolboxes also allow you to use the iterator, switcher, and group components as direct children, providing these components wrap child components that would usually be direct children of the toolbox. For information about toolboxes, see Using Toolbars.

3. If grouping more than one menu bar within a toolbox, for each menu bar, expand the Appearance section and set the flex attribute to determine the relative sizes of each of the menu bars. The higher the number given for the flex attribute, the longer the toolbox will be. For the set of menu bars shown in the following example, menuBar2 will be the longest, menuBar4 will be the next longest, and because their flex attributes are not set, the remaining menu bars will be the same size and shorter than menuBar4.

   <af:toolbox>
     <af:menuBar id="menuBar1" flex="0">
       <af:menu text="MenuA"/>
     </af:menBar>
     <af:menuBar id="menuBar2" flex="2">
       <af:menu text="MenuB"/>
     </af:menuBar>
     <af:menuBar id="menuBar3" flex="0">
       <af:menu text="MenuC"/>
     </af:menuBar>
     <af:menuBar id="menuBar4" flex="1">
       <af:menu text="MenuD"/>
     </af:toolbar>
   </af:toolbox>
   

   Performance Tip:

   At runtime, when available browser space is less than the space needed to display the contents of the toolbox, 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 toolbox component, and the complexity of the children, will affect the performance of the overflow. You should set the size of the toolbox component to avoid overflow when possible. See What Happens at Runtime: How the Size of Menu Bars and Toolbars Is Determined.

   Tip:

   You can use the group component to group menu bars (or menu bars and toolbars) that you want to appear on the same row. If you do not use the group component, the menu bars will appear on subsequent rows.

   For information about how the flex attribute works, see What Happens at Runtime: How the Size of Menu Bars and Toolbars Is Determined.

4. Insert the desired number of menu components into the menu bar by dragging a Menu from the Components window, and dropping it as a child to the menuBar component.

   You can also insert commandMenuItem components directly into a menu bar by dragging and dropping a Menu Item from the Menus and Toolbars panel of the Components window. Doing so creates a commandMenuItem component that renders similar to a toolbar button.

   Tip:

   Menu bars also allow you to use the iterator, switcher, and group components as direct children, providing these components wrap child components that would usually be direct children of the menu bar.

5. For each menu component, expand the Appearance section in the Properties window and set the following attributes:

   • Text: Enter text for the menu's label. If you want to also provide an access key (a letter a user can use to access the menu using the keyboard), then leave this attribute blank and enter a value for textAndAccessKey instead.

   • TextAndAccessKey: Enter the menu label and access key, using conventional ampersand notation. For example, &File sets the menu label to File, and at the same time sets the menu access key to the letter F. For information about access keys and the ampersand notation, see Specifying Component-Level Accessibility Properties.

   • Icon: Use the dropdown list to select the icon. If the icon does not display in this menu, use the dropdown menu to the right of the list to choose Edit, and browse to select the icon.

6. If you want the menu to be detachable (as shown in Figure 15-10), expand the Behavior section in the Properties window and set the Detachable attribute to true. At runtime, the user can drag the menu to detach it, and drop it anywhere on the screen (as shown in Figure 15-11).
7. If you want the menu to use lazy content delivery, set the ContentDelivery attribute to lazy.

   Note:

   If you use lazy content delivery, any accelerators set on the child commandMenuItem components will not work because the contents of the menu are not known until the menu is accessed. If your menu must support accelerators, then ContentDelivery must be set to immediate.

   Note:

   If the menu will be used inside a popup dialog or window, leave ContentDelivery set to immediate, because the popup dialog or window will determine the content delivery for the menu.

8. To create a menu item that invokes some sort of action along with navigation, drag a Menu Item from the Components window and drop it as a child to the menu component to create a commandMenuItem component. Create a number of commandMenuItem components to define the items in the vertical menu. If necessary, you can wrap the commandMenuItem components within a group component to display the items as a group.

   The following example shows simplified code for grouping the Folders and Search menu items in one group, the Table, Tree Table and List menu items in a second group, and the Refresh menu item by itself at the end.

   <af:menu id="viewMenu"
     <af:group>
       <af:commandMenuItem type="check" text="Folders"/>
       <af:commandMenuItem type="check" text="Search"/>
     </af:group>
     <af:group>
       <af:commandMenuItem type="radio" text="Table"/>
       <af:commandMenuItem type="radio" text="Tree Table"/>
       <af:commandMenuItem type="radio" text="List"/>
     </af:group>
     <af:commandMenuItem text="Refresh"/>
   </menu>
   

   Figure 15-17 shows how the menu will be displayed when it is first accessed.

   Note:

   You can change the skin that ADF Faces components use. See Customizing the Appearance Using Styles and Skins.

   Figure 15-17 Grouped Menu Items Using the Type Attribute

   
   Description of "Figure 15-17 Grouped Menu Items Using the Type Attribute"

   Tip:

   By default, only up to 14 items are displayed in the menu. If more than 14 items are added to a menu, the first 14 are displayed along with a scrollbar, which can be used to access the remaining items. If you wish to change the number of visible items, edit the af|menu {-tr-visible-items} skinning key. See Customizing the Appearance Using Styles and Skins.

   You can also insert another menu component into an existing menu component to create a submenu (as shown in Figure 15-4).

   Tip:

   Menus also allow you to use the iterator and switcher components as direct children, providing these components wrap child components that would usually be direct children of the menu.

9. For each commandMenuItem component, expand the Common section in the Properties window and set the following attributes:

   • Type: Specify a type for this menu item. When a menu item type is specified, ADF Faces adds a visual indicator (such as a radio button) and a toggle behavior to the menu item. At runtime, when the user selects a menu item with a specified type (other than the default), ADF Faces toggles the visual indicator or menu item label. Use one of the following acceptable type values:

     • default: Assigns no type to this menu item. The menu item is displayed in the same manner whether or not it is chosen.

     • antonym: Toggles the menu item label. The value set in the SelectedText attribute is displayed when the menu item is chosen, instead of the menu item defined by the value of text or textAndAccessKey attribute (which is what is displayed when the menu item is not chosen). If you select this type, you must set a value for SelectedText.

     • check: Depending on the skin, toggles a square or check mark next to the menu item label. The square is displayed as solid blue when the menu item is chosen, and greyed out when not.

     • radio: Toggles a radio button next to the menu item label. The radio button is displayed as a solid blue circle when the menu item is chosen, and greyed out when not.

   • Text: Enter text for the menu item's label. If you wish to also provide an access key (a letter a user can use to access the item using the keyboard), then leave this attribute blank and enter a value for TextAndAccessKey instead. Or, you can set the access key separately using the accessKey attribute.

   • Selected: Set to true to have this menu item appear to be chosen. The selected attribute is supported for check-, radio-, and antonym-type menu items only.

     Note:

     You may use an EL expression that evaluates to an action method in a managed bean to determine the initial selection state of the commandMenuItem. However, at runtime, the selected state of the menu item is managed through the component and therefore requires an action listener to update the selected state property of the managed bean. For example, your managed bean might define the action listener as:

     public void actLsn(ActionEvent ae) {
       RichCommandMenuItem menuItem = (RichCommandMenuItem) ae.getComponent();
       val1 = menuItem.isSelected();
     } 

   • SelectedText: Set the alternate label to display for this menu item when the menu item is chosen. This value is ignored for all types except antonym.

10. Expand the Appearance section and set the following attributes:

    • Icon: Use the dropdown list to select the icon. If the icon does not display in this menu, use the dropdown menu to the right of the list to choose Edit, and browse to select the icon.

    • Accelerator: Enter the keystroke that will activate this menu item's command when the item is chosen, for example, Control N. ADF Faces converts the keystroke and displays a text version of the keystroke (for example, Ctrl+N) next to the menu item label, as shown in Figure 15-4.

      Note:

      If you choose to use lazy content delivery, any accelerators set on the child commandMenuItem components will not work because the contents of the menu are not known until it is accessed. If your menu must support accelerator keys, then the contentDelivery attribute must be set to immediate.

    • TextAndAccessKey: Enter the menu item label and access key, using conventional ampersand notation. For example, &Save sets the menu item label to Save, and at the same time sets the menu item access key to the letter S. For information about access keys and the ampersand notation, see Specifying Component-Level Accessibility Properties.

11. Expand the Behavior section and set the following attributes:

    • Action: Use an EL expression that evaluates to an action method in an object (such as a managed bean) that will be invoked when this menu item is chosen. The expression must evaluate to a public method that takes no parameters, and returns a java.lang.Object object.

      If you want to cause navigation in response to the action generated by commandMenuItem component, instead of entering an EL expression, enter a static action outcome value as the value for the action attribute. You then must either set the partialSubmit attribute to false, or use a redirect. For information about configuring navigation in your application, see Defining Page Flows.

    • ActionListener: Specify the expression that refers to an action listener method that will be notified when this menu item is chosen. This method can be used instead of a method bound to the action attribute, allowing the action attribute to handle navigation only. The expression must evaluate to a public method that takes an ActionEvent parameter, with a return type of void.

12. To create a menu item that simply navigates (usually to an external site), drag and drop a Menu Item (Go) from the Components window as a child to the menu.
13. In the Properties window, expand the Common section and set the following attributes:

    • Text: Enter the text for the link.

      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 link. For information about how to define access keys, see How to Define Access Keys for an ADF Faces Component.

    • Destination: Enter the URI of the page to which the link should navigate. For example, to navigate to the Oracle Corporation Home Page, you would enter http://www.oracle.com.

    • TargetFrame: Use the dropdown list to specify where the new page should display. Choose one of the following values:

      • _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.

14. If you want a menu bar to stretch so that it equals the width of the containing parent component, select the menuBar component in the Structure window, then expand the Appearance section in the Properties window and set StretchId to be the ID of the component within the menu bar that should be stretched so that the menu bar is the same size as the parent. This one component will stretch, while the rest of the components in the menu bar remain a static size.

    You can also use the stretchId attribute to justify components to the left and right by inserting a spacer component, and setting that component ID as the stretchId for the menu bar, as shown in the following example.

    <af:menuBar binding="#{editor.component}" id="menuBar1" stretchId="stretch1">
      <af:menu text="File" id="m1">
    . . .
      </af:menu>
    . . . 
      <af:commandMenuItem text="Disabled CMI"/>
      <af:goMenuItem textAndAccessKey="O&amp;racle destination="http://www.oracle.com"
                     id="gmi1"/>
      <af:goMenuItem text="Disabled GMI" destination="http://www.gizmo.com" 
                     shortDesc="disabled goMenuItem" id="gmi2"/>
      <af:spacer id="stretch1" clientComponent="true"/>
      <af:commandMenuItem textAndAccessKey="Component G&amp;uide" 
                          action="guide" id="cmi9"/>
    </af:menuBar>

1. If you plan on using more than one toolbar or a combination of toolbars and menu bars, create a toolbox component by dragging and dropping a Toolbox component from the Menus and Toolbars panel of the Components window.

   Tip:

   The panelHeader, showDetailHeader, and showDetailItem components support a toolbar facet for adding toolboxes and toolbars to section headers and accordion panel headers.

2. Drag and drop a Toolbar onto the JSF page. If you are using a toolbox component, the Toolbar should be dropped as a direct child of the toolbox component.

   Tip:

   Toolboxes also allow you to use the iterator, switcher, and group components as direct children, providing these components wrap child components that would usually be direct children of the toolbox.

3. If grouping more than one toolbar within a toolbox, for each toolbar, select the toolbar, expand the Appearance section and set the Flex attributes to determine the relative sizes of each of the toolbars. The higher the number given for the flex attribute, the longer the toolbox will be. For the set of toolbars shown in the following example, toolbar2 will be the longest, toolbar4 will be the next longest, and because their flex attributes are not set, the remaining toolbars will be the same size and shorter than toolbar4.

   <af:toolbox>
     <af:toolbar id="toolbar1" flex="0">
       <af:button text="ButtonA"/>
     </af:toolbar>
     <af:toolbar id="toolbar2" flex="2">
       <af:button text="ButtonB"/>
     </af:toolbar>
     <af:toolbar id="toolbar3" flex="0">
       <af:button text="ButtonC"/>
     </af:toolbar>
     <af:toolbar id="toolbar4" flex="1">
       <af:button text="ButtonD"/>
     </af:toolbar>
   </af:toolbox>
   

   Performance Tip:

   At runtime, when available browser space is less than the space needed to display the contents of the toolbox, 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 toolbox component, and the complexity of the children, will affect the performance of the overflow. You should set the size of the toolbox component to avoid overflow when possible. See What Happens at Runtime: How the Size of Menu Bars and Toolbars Is Determined.

   Tip:

   You can use the group component to group toolbars (or menu bars and toolbars) that you want to appear on the same row. If you do not use the group component, the toolbars will appear on subsequent rows.

   For information about how the flex attribute works, see What Happens at Runtime: How the Size of Menu Bars and Toolbars Is Determined.

4. Insert components into the toolbar as needed. To create a button on the toolbar, drag a Button from the General Controls section of the Components window and drop it as a direct child of the toolbar component.

   Tip:

   You can use the group component to wrap related buttons on the bar. Doing so inserts a separator between the groups, as shown in Figure 15-17.

   Toolbars also allow you to use the iterator and switcher components as direct children, as long as these components wrap child components that would usually be direct children of the toolbar.

   Tip:

   You can place other components, such as buttons and links, input components, and select components in a toolbar. However, they may not have the capability to stretch. For details about stretching the toolbar, see Step 9.

5. For each button component, expand the Common section of the Properties window and set the following attributes:

   • Text: Enter the label for this toolbar button.

   • Type: Specify a type for this toolbar button. When a toolbar button type is specified, an icon can be displayed when the button is clicked. Use one of the following acceptable type values:

     • default: Assigns no type to this toolbar button.

     • check: Toggles to the depressedIcon value if selected or to the default icon value if not selected.

     • radio: When used with other toolbar buttons in a group, makes the button currently clicked selected, and toggles the previously clicked button in the group to unselected.

       Note:

       When setting the type to radio, you must wrap the toolbar button in a group tag that includes other toolbar buttons whose types are set to radio as well.

   • Selected: Set to true to have this toolbar button appear as selected. The selected attribute is supported for checkmark- and radio-type toolbar buttons only.

   • 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.

   • Action: Use an EL expression that evaluates to an action method in an object (such as a managed bean) that will be invoked when a user presses this button. The expression must evaluate to a public method that takes no parameters, and returns a java.lang.Object object.

     If you want to cause navigation in response to the action generated by the button, instead of entering an EL expression, enter a static action outcome value as the value for the action attribute. You then must set either partialSubmit to false, or use a redirect. For information about configuring navigation, see Defining Page Flows.

   • ActionListener: Specify the expression that refers to an action listener method that will be notified when a user presses this button. This method can be used instead of a method bound to the action attribute, allowing the action attribute to handle navigation only. The expression must evaluate to a public method that takes an ActionEvent parameter, with a return type of void.

6. Expand the Appearance section and set the following properties:

   • HoverIcon: Use the dropdown list to select the icon to display when the mouse cursor is directly on top of this toolbar button. If the icon is not in this menu, use the dropdown menu to the right of the list to choose Edit, and browse to select the icon.

   • DepressedIcon: Use the dropdown list to select the icon to display when the toolbar button is activated. If the icon is not in this menu, use the dropdown menu to the right of the list to choose Edit, and browse to select the icon.

7. Expand the Behavior section and set ActionDelivery to none if you do not want to fire an action event when the button is clicked. This is useful if you want the button to simply open a popup window. If set to none, you must have a popup component in the popup facet of the toolbar button (see Step 8), and you cannot have any value set for the action or actionListener attributes. Set to clientServer attribute if you want the button to fire an action event as a standard command component.
8. To have a toolbar button invoke a popup menu, insert a menu component into the popup facet of the button component. For information, see How to Create and Use Menus in a Menu Bar.
9. If you want a toolbar to stretch so that it equals the width of the containing parent component, set stretchId to be the ID of the component within the toolbar that should be stretched. This one component will stretch, while the rest of the components in the toolbar remain a static size.

   For example, in the File Explorer application, the inputText component that displays the selected folder's name is the one that should stretch, while the outputText component that displays the words "Current Folder" remains a static size, as shown in the following example.

   <af:toolbar id="headerToolbar2" flex="2" stretchId="pathDisplay">
     <af:outputText id="currLocation" noWrap="true"
                    value="#{explorerBundle['menuitem.location']}"/>
     <af:inputText id="pathDisplay" simple="true" inlineStyle="width:100%"
                   contentStyle="width:100%"
                   binding="#{explorer.headerManager.pathDisplay}"
                   value="#{explorer.headerManager.displayedDirectory}"
                   ="true"
                   validator="#{explorer.headerManager.validatePathDisplay}"/>
   </af:toolbar>
   

   You can also use the stretchId attribute to justify components to the left and right by inserting a spacer component, and setting that component ID as the stretchId for the toolbar, as shown in the following example.

   <af:toolbar flex="1" stretchId="stretch1">
     <af:button text="Forward"
                              icon="/images/fwdarrow_gray.gif"
                              disabled="true"></af:button>
     <af:button icon="/images/uplevel.gif" />
     
   <!-- Insert a stretched spacer to push subsequent buttons to the right -->
   
     <af:spacer id="stretch1" clientComponent="true"/>
     
     <af:button text="Reports" />
     <af:button id="toggleRefresh"
                              text="Refresh:OFF" />
   </af:toolbar>
   

When a page with a menu bar or toolbar is first displayed or resized, the space needed for each bar is based on the value of the bar's flex attribute. The percentage of size allocated to each bar is determined by dividing its flex attribute value by the sum of all the flex attribute values. For example, say you have three toolbars in a toolbox, and those toolbars are grouped together to display on the same line. The first toolbar is given a flex attribute value of 1, the second toolbar also has a flex attribute value of 1, and the third has a flex attribute value of 2, giving a total of 4 for all flex attribute values. In this example, the toolbars would have the following allocation percentages:

• Toolbar 1: 1/4 = 25%

• Toolbar 2: 1/4 = 25%

• Toolbar 3: 2/4 = 50%

Once the allocation for the bars is determined, and the size set accordingly, each element within the toolbars are placed left to right. Any components that do not fit are placed into the overflow list for the bar, keeping the same order as they would have if displayed, but from top to bottom instead of left to right.

Toolbars are supported and rendered by parent components such as panelHeader, showDetailHeader, and showDetailItem, which have a toolbar facet for adding toolbars and toolbar buttons to section headers and accordion panel headers.

Note the following points about toolbars at runtime:

• A toolbar and its buttons do not display on a header if that header is in a collapsed state. The toolbar displays only when the header is in an expanded state.

• When the available space on a header is less than the space needed by a toolbar and all its buttons, ADF Faces automatically renders overflow icons that allow users to select hidden buttons from an overflow list.

• Toolbars do not render on printable pages.