How to Create and Use Menus in a Menu Bar

14-10 Web User Interface Developers Guide for Oracle Application Development Framework Figure 14–15 Grouped commandMenuItem Components in a Menu You can also insert another menu component into an existing menu component to create a submenu as shown in Figure 14–3 . 9. For each commandMenuItem component, expand the Common section in the Property Inspector 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: – check : In the default FusionFX skin, toggles a square 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. – 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. – default : Assigns no type to this menu item. The menu item is displayed in the same manner whether or not it is chosen. ■ 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 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. For more information, see Chapter 20, Customizing the Appearance Using Styles and Skins. 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. Using Menus, Toolbars, and Toolboxes 14-11 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. ■ 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. Example 14–3 shows the Special menu with one group of menu items configured to use radio buttons and another group of menu items configured to show blue squares when chosen. The last group contains a menu item configured to be the antonym Open when it is first displayed, and then it toggles to Closed. Example 14–3 Using the Type Attribute in a commandMenuItem Component af:menu text=Special af:group af:commandMenuItem text=Radio 1 type=radio selected=true af:commandMenuItem text=Radio 2 type=radio af:commandMenuItem text=Radio 3 type=radio af:group af:group af:commandMenuItem text=Check 1 type=check selected=true af:commandMenuItem text=Check 2 type=check af:group af:commandMenuItem text=Open antonym type=antonym selectedText=Close antonym af:menu Figure 14–16 shows how the menu will be displayed when it is first accessed. Figure 14–16 Menu Items Using the Type Attribute 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. Note: By default, ADF Faces components use the FusionFX skin, which displays the check type as a square. You can change this by creating your own skin. For more information, see Chapter 20, Customizing the Appearance Using Styles and Skins. 14-12 Web User Interface Developers Guide for Oracle Application Development Framework ■ Accelerator : Enter the keystroke that will activate this menu item’s command when the item is chosen, for example, Control O. ADF Faces converts the keystroke and displays a text version of the keystroke for example, Ctrl+O next to the menu item label, as shown in Figure 14–3 . ■ TextAndAccessKey : Enter the menu item label and access key, using conventional ampersand notation. For example, amp;Save sets the menu item label to Save, and at the same time sets the menu item access key to the letter S. For more information about access keys and the ampersand notation, see Section 22.3, 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 more information about configuring navigation in your application, see Section 2.3, 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 Go Menu Item from the Component Palette as a child to the menu.

13. In the Property Inspector, expand the Other section and set the following

attributes: ■ 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. ■ 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. Note: Because alternative text cannot be provided for this icon, in order to create an accessible product, this icon must only be used when the use is purely decorative. You must provide the meaning of this icon using another accessible manner. 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. Using Menus, Toolbars, and Toolboxes 14-13 ■ TargetFrame : Use the dropdown list to specify where the new page should display. Values are – _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. ■ Text : Enter the text for the link. 14. If you want a menu bar to stretch so that it equals the width of the containing parent component, 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 Example 14–7 . Example 14–4 Using a Spacer to Justify menuBar Components 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=Oamp;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 Gamp;uide action=guide id=cmi9 af:menuBar

14.3 Using Toolbars

Along with menus, you can create toolbars in your application that contain toolbar buttons used to initiate some operation in the application. The buttons can display Note: Because alternative text cannot be provided for this icon, in order to create an accessible product, this icon must only be used when the use is purely decorative. You must provide the meaning of this icon using another accessible manner. 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 Section 22.3.4, How to Define Access Keys for an ADF Faces Component. 14-14 Web User Interface Developers Guide for Oracle Application Development Framework text, an icon, or a combination of both. Toolbar buttons can also open menus in a popup window. Along with toolbar buttons, other UI components, such as dropdown lists, can be displayed in toolbars. Figure 14–17 shows the toolbar from the File Explorer application. Figure 14–17 Toolbar in the File Explorer Application The toolbar component can contain many different types of components, such as inputText components, LOV components, selection list components, and command components. ADF Faces also includes a commandToolbarButton component that has a popup facet, allowing you to provide popup menus from a toolbar button. You can configure your toolbar button so that it only opens the popup dialog and does not fire an action event. As with menus, you can group related toolbar buttons on the toolbar using the group component. You can use more than one toolbar by enclosing them in a toolbox. Enclosing toolbars in a toolbox stacks them so that the first toolbar on the page is displayed at the top, and the last toolbar is displayed on the bottom. For example, in the File Explorer application, the currently selected folder name is displayed in the Current Location toolbar, as shown in Figure 14–17 . When you use more than one toolbar, you can set the flex attribute on the toolbars to determine which toolbar should take up the most space. In this case, the Current Location toolbar is set to be the longest. If you wish toolbars to be displayed next to each other rather than stacked, you can enclose them in a group component. Within a toolbar, you can set one component to stretch so that the toolbar will always be the same size as its parent container. For example, in the File Explorer application, the lower toolbar that displays the current location contains the component that shows the selected folder. This component is set to stretch so that when the window is resized, that component and the toolbar will always be the same width as the parent. However, because no component in the top toolbar is set to stretch, it does not change size when the window is resized. When a window is resized such that all the components within the toolbar can no longer be displayed, the toolbar displays an overflow icon, identified by an arrow cursor in the upper right-hand corner, as shown in Figure 14–18 . Tip: Toolbars can also include command buttons and command links including the commandImageLink component instead of toolbar buttons. However, toolbar buttons provide additional functionality, such as opening popup menus. Toolbar buttons can also be used outside of a toolbar component Tip: You can also use the toolbox component to group menu bars with toolbars, or to group multiple menu bars. As with grouping toolbars, use the group component to group menu bars and toolbars on the same row. Using Menus, Toolbars, and Toolboxes 14-15 Figure 14–18 Overflow Icon in a Toolbar Clicking that overflow icon displays the remaining components in a popup window, as shown in Figure 14–19 . Figure 14–19 Toolbar Component in an Overflow Popup Window When you expect overflow to occur in your toolbar, it is best to wrap it in a toolbox that has special layout logic to help in the overflow.

14.3.1 How to Create and Use Toolbars

If you are going to use more than one toolbar component on a page, or if you plan to use menu bars with toolbars, you first create the toolbox component to hold them. You then create the toolbars, and last, you create the toolbar buttons. To create and use toolbars: 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 Layout panel of the Component Palette. 2. In the Component Palette, from the Common Components panel, 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: If you encounter layout issues with single toolbars or menu bars, consider wrapping them in a toolbox component, because this component can handle overflow and layout issues. Tip: The panelHeader, showDetailHeader, and showDetailItem components support a toolbar facet for adding toolboxes and toolbars to section headers and accordion panel headers. 14-16 Web User Interface Developers Guide for Oracle Application Development Framework 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 Example 14–5 , 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. Example 14–5 Flex Attribute Determines Length of Toolbars af:toolbox af:toolbar id=toolbar1 flex=0 af:commandToolbarButton text=ButtonA af:toolbar af:toolbar id=toolbar2 flex=2 af:commandToolbarButton text=ButtonB af:toolbar af:toolbar id=toolbar3 flex=0 af:commandToolbarButton text=ButtonC af:toolbar af:toolbar id=toolbar4 flex=1 af:commandToolbarButton text=ButtonD af:toolbar af:toolbox For information about how the flex attribute works, see Section 14.3.2, What Happens at Runtime: Determining the Size of Menu Bars and Toolbars.

4. Insert components into the toolbar as needed. To create a

commandToolbarButton drag a ToolbarButton from the Component Palette and drop it as a direct child of the toolbar 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. 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. For more information, see Section 14.3.2, What Happens at Runtime: Determining the Size of Menu Bars and Toolbars. 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.