Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.4.0) B31973-06 |
|
![]() Previous |
![]() Next |
This chapter describes how to create menu bars and toolbars that contain tool buttons.
For information about creating navigation menus, that is, menus that allow you to navigate through a hierarchy of pages, see Section 18.5, "Using Navigation Items for a Page Hierarchy."
This chapter includes the following sections:
Menus and toolbars allow users to choose from a specified list of options (in the case of a menu) or to click buttons (in the case of a toolbar) to effect some change to the application. The File Explorer application contains both a menu bar and a toolbar, as shown in Figure 14-1.
When a user chooses a menu item in the menu bar, the menu
component displays a list of menu items, as shown in Figure 14-2.
Note that as shown in Figure 14-3, menus can be nested.
Buttons in a toolbar also allow a user to invoke some sort of action on an application or to open a popup 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.
Note: If you want to create menus and toolbars in a table, then follow the procedures in Section 10.8, "Displaying Table Menus, Toolbars, and Status Bars."If you want to create a context menu for a component (that is a menu that launches when a user right-clicks the component), follow the procedures in Section 13.2.3, "How to Create a Context Menu." |
Use the menuBar
component to render a bar that contains the menu bar items (such as File in the File Explorer application). Each item on a menu bar is rendered by a menu
component, which holds a vertical menu. Each vertical menu consists of a list of commandMenuItem
components that can invoke some operation on the application. You can nest menu components inside menu components to create submenus. The different components used to create a menu are shown in Figure 14-4.
You can use more than one menu bar by enclosing them in a toolbox. Enclosing them in a toolbox stacks the menu bars so that the first menu bar in the toolbox is displayed at the top, and the last menu bar is displayed at the bottom. When you use more than one menu bar in a single toolbox row (by having them grouped inside the toolbox), then the flex
attribute will determine which menu bar will take up the most space.
If you wish menu bars to be displayed next to each other (rather than being stacked), you can enclose them in a group
component.
Tip: You can also use thetoolbox component to group menu bars with toolbars, or to group multiple menu bars. Use the group component to group menu bars and toolbars on the same row. |
Within a menu bar, you can set one component to stretch so that the menu bar will always be the same size as its parent container. For example, in Figure 14-5, the menu bar is set to stretch a spacer component that is placed between the Disabled GMI menu and the Component Guide button. When the window is resized, that spacer component either stretches or shrinks so that the menu bar will always be the same width as the parent. Using a spacer component like this also ensures that any components to the right of the spacer will remain right-justified in the menu bar.
When a window is resized such that all the components within the menu bar can no longer be displayed, the menu bar displays an overflow icon, identified by the arrow cursor as shown in Figure 14-6.
Clicking that overflow icon displays the remaining components in a popup window, as shown in Figure 14-7.
Menus and submenus can be made to be detachable and to float on the browser window. Figure 14-8 shows the New submenu in the File menu configured to be detachable. The top of the menu is rendered with a bar to denote that it can be detached.
The user can drag the detachable menu to anywhere within the browser. When the mouse button is released, the menu stays on top of the application until the user closes it, as shown in Figure 14-9.
Tip: Consider using detachable menus when you expect users to:
|
The menu
and commandMenuItem
components can each include an icon image. Figure 14-10 shows the Delete menu item configured to display a delete icon.
Note: Because alternative text cannot be provided for this icon, in order to create an accessible product, use this icon only when it is purely decorative. You must provide the meaning of this icon in some accessible manner. |
You can configure commandMenuItem
components to be specific types that change how they are displayed when the menu item is chosen. For example, you can configure a commandMenuItem
component to display a checkmark or a radio button next to the label when the item is chosen. Figure 14-11 shows the View menu with the Folders menu item configured to use a checkmark when chosen. The Table, Tree Table, and List menu items are configured to be radio buttons, and allow the user to choose only one of the group.
You can also configure a commandMenuItem
component to have an antonym. Antonyms display different text when the user chooses a menu item. Figure 14-12 shows an Undo menu item in the Edit menu (added to the File Explorer application for this example).
By configuring the commandMenuItem
component for the Undo menu item to be an antonym and to have alternate text to display, when a user chooses Undo, the next time the user returns to the menu, the menu item will display the antonym Restore, as shown in Figure 14-13.
Because an action is expected when a user chooses a menu item, you must bind the action
or actionListener
attribute of the commandMenuItem
component to some method that will execute the needed functionality.
Along with commandMenuItem
components, a menu can also include one or more goMenuItem
components. These are navigation components similar to the goLink
component, in that they perform direct page navigation, without delivering an ActionEvent
event. Figure 14-14 shows three goMenuItem
components used to navigate to external web sites.
Aside from menus that are invoked from menu bars, you can also create context menus that are invoked when a user right-clicks a UI component, and popup menus that are invoked when a user clicks a command component. For more information, see Section 13.2.3, "How to Create a Context Menu."
Note: ADF Faces provides a button with built-in functionality that allows a user to view a printable version of the current page. Menus and menu bars do not render on these pages. For more information, see Section 5.6, "Using Client Behavior Tags.". |
By default, the contents of the menu are delivered immediately, as the page is rendered. If you plan on having a large number of children in a menu (multiple menu
and commandMenuItem
components), you can choose to configure the menu to use lazy content delivery. This means that the child components are not retrieved from the server until the menu is accessed.
Note: Content delivery for menus used as popup context menus is determined by the parent popup dialog, and not the menu itself. |
You can also create menus that mainly provide navigation throughout the application, and are not used to cause any change on a selected item in an application. To create this type of menu, see Section 18.6, "Using a Menu Model to Create a Page Hierarchy."
To create a menu, you first have to create a menu bar to hold the menus. You then add and configure menu
and commandMenuItem
components as needed.
Note: If you want to create menus in a table, follow the procedures outlined in Section 10.8, "Displaying Table Menus, Toolbars, and Status Bars." |
To create and use menus in a menu bar:
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 component from the Layout panel of the Component Palette.
Tip: ThepanelHeader , showDetailHeader , and showDetailItem components support a toolbar facet for adding toolboxes and toolbars to section headers and accordion panel headers. |
Create a menu bar by dragging and dropping a Panel Menu Layout from the Layout panel of the Component Palette. If you are using a toolbox
component, the Panel Menu layout 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 more information about toolboxes, see Section 14.3, "Using Toolbars." |
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 Example 14-5, 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
.
Example 14-1 Flex Attribute Determines Length of Toolbars
<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 atoolbox 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 thegroup 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 Section 14.3.2, "What Happens at Runtime: Determining the Size of Menu Bars and Toolbars."
Insert the desired number of menu
components into the menu bar by dragging a Menu from the Component Palette, 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. Doing so creates a commandMenuItem
component that renders similar to a toolbar button.
Tip: Menu bars also allow you to use theiterator , switcher , and group components as direct children, providing these components wrap child components that would usually be direct children of the menu bar. |
For each menu
component, expand the Appearance section in the Property Inspector and set the following attributes:
Text: Enter text for the menu's label. If you wish 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 more information about access keys and the ampersand notation, see Section 22.3, "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.
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. |
If you want the menu to be detachable (as shown in Figure 14-8), expand the Behavior section in the Property Inspector 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 14-9).
If you want the menu to use lazy content delivery, expand the Other section in the Property Inspector and set the ContentDelivery attribute to lazy
.
Note: If you use lazy content delivery, any accelerators set on the childcommandMenuItem 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 toimmediate , because the popup dialog or window will determine the content delivery for the menu. |
To create a menu item that invoke some sort of action along with navigation, drag a MenuItem from the Component Palette 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. Example 14-2 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.
Example 14-2 Grouping Menu Items
<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 14-15 shows how the menu is displayed.
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 theaf|menu {-tr-visible-items } skinning key. For more information, see Chapter 20, "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 14-3).
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. |
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 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.
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." |
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: 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. |
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.
Note: If you choose to use lazy content delivery, any accelerators set on the childcommandMenuItem 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 more information about access keys and the ampersand notation, see Section 22.3, "Specifying Component-Level Accessibility Properties."
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
.
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.
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. |
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.
Tip: Instead, you can use thetextAndAccessKey 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." |
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="O&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&uide" action="guide" id="cmi9"/> </af:menuBar>
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 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.
Tip: Toolbars can also include command buttons and command links (including thecommandImageLink 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 |
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.
Tip: You can also use thetoolbox 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. |
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.
Clicking that overflow icon displays the remaining components in a popup window, as shown in Figure 14-19.
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.
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.
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. |
To create and use toolbars:
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.
Tip: ThepanelHeader , showDetailHeader , and showDetailItem components support a toolbar facet for adding toolboxes and toolbars to section headers and accordion panel headers. |
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: 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. |
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>
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 atoolbox 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 thegroup 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 Section 14.3.2, "What Happens at Runtime: Determining the Size of Menu Bars and Toolbars."
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: You can use thegroup component to wrap related buttons on the bar. Doing so inserts a separator between the groups, as shown surrounding the group for the Select Skin dropdown list and Refresh button in Figure 14-17.
Toolbars 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 toolbar. |
Tip: You can place other components, such as command 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. |
For each commandToolbarButton
component, expand the Common section of the Property Inspector and set the following attributes:
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:
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 toradio , you must wrap the toolbar button in a group tag that includes other toolbar buttons whose types are set to radio as well. |
default: Assigns no type to this toolbar button.
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: 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. |
Text: Enter the label for this toolbar button.
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 more information about configuring navigation, see Section 2.3, "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
.
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.
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
To have a toolbar button invoke a popup menu, insert a menu
component into the popup
facet of the commandToolbarButton
component. For information, see Section 14.2.1, "How to Create and Use Menus in a Menu Bar."
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 Example 14-6.
Example 14-6 Using the stretchId Attribute
<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 Example 14-7.
Example 14-7 Using a Spacer to Justify Toolbar Components
<af:toolbar flex="1" stretchId="stretch1"> <af:commandToolbarButton text="Forward" icon="/images/fwdarrow_gray.gif" disabled="true"></af:commandToolbarButton> <af:commandToolbarButton icon="/images/uplevel.gif" /> <!-- Insert a stretched spacer to push subsequent buttons to the right --> <af:spacer id="stretch1" clientComponent="true"/> <af:commandToolbarButton text="Reports" /> <af:commandToolbarButton 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.
Note: If the application is configured to read right to left, the toolbars will be placed right to left. For more information, see Section A.6.2.6, "Language Reading Direction." |
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.