Chapter 14. Menus and toolbars

⁠Chapter 14. Menus and toolbars

Read this chapter for details on menu and toolbar components.

⁠14.1. `<rich:dropDownMenu>`

The <rich:dropDownMenu> component is used for creating a drop-down, hierarchical menu. It can be used with the <rich:toolbar> component to create menus in an application's toolbar.

⁠

Figure 14.1. <rich:dropDownMenu>

⁠14.1.1. Basic usage

The <rich:dropDownMenu> component only requires the label attribute for basic usage. Use the label attribute to define the text label that appears as the title of the menu. Clicking on the title drops the menu down.

Alternatively, use the label facet to define the menu title. If the label facet is used, the label attribute is not necessary.

⁠14.1.2. Menu content

To set the content of the drop-down menu and any sub-menus, use the <rich:menuItem>, <rich:menuGroup>, and <rich:menuSeparator> components. These components are detailed in Section 14.3, “Menu sub-components”.

⁠14.1.3. Appearance

Use the jointPoint and direction attributes to determine the direction and location of the menu when it appears. The jointPoint and direction attributes both use the following settings:

topLeft, topRight, bottomLeft, bottomRight: When used with the jointPoint attribute, the menu is attached to the top-left, top-right, bottom-left, or bottom-right of the control as appropriate.
When used with the direction attribute, the menu appears to the top-left, top-right, bottom-left, or bottom-right of the joint location as appropriate.
auto: The direction or joint location is determined automatically.
autoLeft, autoRight, topAuto, bottomAuto: When used with the jointPoint attribute, the joint location is determined automatically, but defaults to either the left, right, top, or bottom of the control as appropriate.
When used with the direction attribute, the menu direction is determined automatically, but defaults to either the left, right, top, or bottom of the joint location as appropriate.

⁠14.1.4. Expanding and collapsing the menu

By default, the menu drops down when the title is clicked. To drop down with a different event, use the showEvent attribute to define the event instead.

Menus can be navigated using the keyboard. Additionally, menus can be navigated programmatically using the JavaScript API. The JavaScript API allows the following methods:

show(): The show() method shows the menu.
hide(): The hide() method hides the menu.
activateItem(menuItemId): The activateItem(menuItemId) activates the menu item with the menuItemId identifier.

Use the mode attribute to determine how the menu requests are submitted:

server, the default setting, submits the form normally and completely refreshes the page.
ajax performs an Ajax form submission, and re-renders elements specified with the render attribute.
client causes the action and actionListener items to be ignored, and the behavior is fully defined by the nested components or custom JavaScript instead of responses from submissions.

⁠14.1.5. Reference data

component-type: org.richfaces.DropDownMenu
component-class: org.richfaces.component.UIDropDownMenu
component-family: org.richfaces.DropDownMenu
renderer-type: org.richfaces.DropDownMenuRenderer

⁠14.1.6. Style classes and skin parameters

⁠

Table 14.1. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-ddm-lbl` This class defines styles for the label of the drop-down menu.	`headerFamilyFont`	font-family
`.rf-ddm-dis` This class defines styles for the drop-down menu when it is disabled.	`tabDisabledTextColor`	color
`.rf-ddm-lbl-dis` This class defines styles for the label of the drop-down menu when it is disabled.	`headerFamilyFont`	font-family
`.rf-ddm-pos` This class defines the positioning of the drop-down menu.	No skin parameters.
`.rf-ddm-lbl-unsel` This class defines styles for the label of the drop-down menu when it is unselected.	No skin parameters.
`.rf-ddm-lst` This class defines styles for the drop-down list.	`panelBorderColor`	border-color
	`additionalBackgroundColor`	background-color
`.rf-ddm-lst-bg` This class defines styles for the background of the drop-down list.	`additionalBackgroundColor`	border-color
`.rf-ddm-sublst` This class defines the positioning of the menu when used as a sub-menu.	No skin parameters.
`.rf-ddm-itm` This class defines styles for a menu item.	`generalFamilyFont`	font-family
`.rf-ddm-itm` This class defines styles for a menu item.	`generalSizeFont`	font-size
`.rf-ddm-itm-sel` This class defines styles for a menu item when it is selected.	`headerBackgroundColor`	border-color
	`tabBackgroundColor`	background-color
`.rf-ddm-itm-unsel` This class defines styles for a menu item when it is unselected.	No skin parameters.
`.rf-ddm-itm-dis` This class defines styles for a menu item when it is disabled.	`tabDisabledTextColor`	color
`.rf-ddm-itm-lbl` This class defines styles for the label in a menu item.	`generalTextColor`	color
`.rf-ddm-itm-ic` This class defines styles for the icon in a menu item.	No skin parameters.
`.rf-ddm-emptyIcon` This class defines styles for an empty icon in a menu item.	No skin parameters.
`.rf-ddm-sep` This class defines styles for a menu separator.	`panelBorderColor`	border-top-color
`.rf-ddm-nd` This class defines styles for a menu node.	No skin parameters.