14.4. <rich:panelMenu>

⁠14.4. `<rich:panelMenu>`

The <rich:panelMenu> component is used in conjunction with <rich:panelMenuItem> and <rich:panelMenuGroup> to create an expanding, hierarchical menu. The <rich:panelMenu> component's appearance can be highly customized, and the hierarchy can stretch to any number of sub-levels.

⁠

Example 14.2. richpanelMenu

<rich:panelMenu mode="ajax" 
                topGroupExpandedRightIcon="chevronUp"
                topGroupCollapsedRightIcon="chevronDown"
                groupExpandedLeftIcon="disc"
                groupCollapsedLeftIcon="disc">
   <rich:panelMenuGroup label="Group 1">
      <rich:panelMenuItem label="Item 1.1"/>
      <rich:panelMenuItem label="Item 1.2"/>
      <rich:panelMenuItem label="Item 1.3"/>
   </rich:panelMenuGroup>
   <rich:panelMenuGroup label="Group 2">
      <rich:panelMenuItem label="Item 2.1"/>
      <rich:panelMenuItem   label="Item 2.2"/>
      <rich:panelMenuItem label="Item 2.3"/>
      <rich:panelMenuGroup label="Group 2.4">
         <rich:panelMenuItem label="Item 2.4.1"/>
         <rich:panelMenuItem label="Item 2.4.2"/>
         <rich:panelMenuItem label="Item 2.4.3"/>
      </rich:panelMenuGroup>
      <rich:panelMenuItem label="Item 2.5"/>
   </rich:panelMenuGroup>
   <rich:panelMenuItem label="Item 3"/>
</rich:panelMenu>

⁠14.4.1. Basic usage

The <rich:panelMenu> component does not need any extra attributes declared for basic usage. However, it does require child <rich:panelMenuGroup> and <rich:panelMenuItem> components. Refer to Section 14.4.9, “<rich:panelMenuGroup>” and Section 14.4.10, “<rich:panelMenuItem>” for details on these child components.

⁠14.4.2. Interactivity options

The activeItem attribute is used to point to the name of the currently selected menu item.

By default, the event to expand the menu is a mouse click. Set the expandEvent attribute to specify a different event to expand menus. Multiple levels of sub-menus can be expanded in one action. Set expandSingle="true" to only expand one sub-menu at a time.

Similarly, the default event to collapse the menu is a mouse click. Set the collapseEvent attribute to specify a different event to collapse menus.

As with other control components, set disabled="true" to disable the <rich:panelMenu> comonent. Child menu components can be disabled in the same way.

⁠14.4.3. Appearance

Icons for the panel menu can be chosen from a set of standard icons. Icons can be set for the top panel menu, child panel menus, and child item. There are three different menu states that the icon represents, as well as icons for both the left and right side of the item title.

topGroupExpandedLeftIcon, topGroupExpandedRightIcon: These attributes determine the icons for the top level menu when it is expanded.
topGroupCollapsedLeftIcon, topGroupCollapsedRightIcon: These attributes determine the icons for the top level menu when it is collapsed.
topGroupDisabledLeftIcon, topGroupDisabledRightIcon: These attributes determine the icons for the top level menu when it is disabled.
topItemLeftIcon, topItemRightIcon: These attributes determine the icons for a top level menu item.
topItemDisabledLeftIcon, topItemDisabledRightIcon: These attributes determine the icons for a top level menu item when it is disabled.
groupExpandedLeftIcon, groupExpandedRightIcon: These attributes determine the icons for sub-menus that are not the top-level menu when they are expanded.
groupCollapsedLeftIcon, groupCollapsedRightIcon: These attributes determine the icons for sub-menus that are not the top-level menu when they are collapsed.
groupDisabledLeftIcon, groupDisabledRightIcon: These attributes determine the icons for sub-menus that are not the top-level menu when they are disabled.
itemLeftIcon, itemRightIcon: These attributes determine the icons for items in the menus.
itemDisabledLeftIcon, itemDisabledRightIcon: These attributes determine the icons for items in the menus when they are disabled.

Example 14.2, “richpanelMenu” demonstrates the use of icon declaration at the panel menu level. The standard icons are shown in Figure 14.3, “<Standard icons>”.

⁠

Figure 14.3. <Standard icons>

Alternatively, point the icon attributes to the paths of image files. The image files are then used as icons.

Any icons specified by child <rich:panelMenuGroup> and <rich:panelMenuItem> components overwrite the relevant icons declared with the parent <rich:panelMenu> component.

⁠14.4.4. Submission modes

The itemMode attribute defines the submission mode for normal menu items that link to content, and the groupMode attribute defines the submission mode for menu items that expand and collapse. The settings for these attributes apply to the entire menu unless a menu item defines its own individual itemMode or groupMode. The possible values for itemMode and groupMode are as follows:

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

⁠14.4.5. `<rich:panelMenu>` server-side events

The <rich:panelMenu> component fires the ItemChangeEvent event on the server side when the menu is changed. The event only fires in the server and ajax submission modes. The event provides the itemChangeListener attribute to reference the event listener. Refer to Section 11.6.6, “<rich:itemChangeListener>” for details on the <rich:itemChangeListener> tag.

⁠14.4.6. JavaScript API

The <rich:panelMenu> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

expandAll(): Expand all the panel menu groups in the component.
collapseAll(): Collapse all the panel menu groups in the component.
selectItem(id): Select the menu item with the id identifier.

⁠14.4.7. Reference data

component-type: org.richfaces.PanelMenu
component-class: org.richfaces.component.UIPanelMenu
component-family: org.richfaces.PanelMenu
renderer-type: org.richfaces.PanelMenuRenderer
handler-class: org.richfaces.view.facelets.html.PanelMenuTagHandler

⁠14.4.8. Style classes and skin parameters

⁠

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

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-pm` This class defines styles for the panel menu itself.	No skin parameters.
`.rf-pm-gr` This class defines styles for a panel menu group.	`panelBorderColor`	border-top-color
`.rf-pm-exp`, `.rf-pm-colps` These classes define styles for the panel menu when it is expanded or collapsed.	No skin parameters.
`.rf-pm-ico` This class defines styles for the panel menu icons.	No skin parameters.
`.rf-pm-ico-exp`, `.rf-pm-ico-colps` These classes define styles for the panel menu icons when they are expanded or collapsed.	No skin parameters.
`.rf-pm-hdr-exp`, `.rf-pm-hdr-colps` These classes define styles for the panel menu headers when they are expanded or collapsed.	No skin parameters.
`.rf-pm-itm` This class defines styles for a panel menu item.	`panelBorderColor`	border-top-color
	`generalTextColor`	color
`.rf-pm-itm-gr` This class defines styles for a panel menu item as part of a panel menu group.	No skin parameters.
`.rf-pm-itm:hover` This class defines styles for a panel menu item when the mouse hovers over it.	`additionalBackgroundColor`	background-color
`.rf-pm-itm-sel` This class defines styles for a panel menu item when it is selected.	No skin parameters.
`.rf-pm-itm-dis` This class defines styles for a panel menu item when it is disabled.	`tabDisabledTextColor`	color
`.rf-pm-itm-ico` This class defines styles for the icon in a panel menu item.	No skin parameters.
`.rf-pm-itm-exp-ico` This class defines styles for the icon in a panel menu item when it is expanded.	No skin parameters.
`.rf-pm-itm-lbl` This class defines styles for the label in a panel menu item.	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-pm-gr` This class defines styles for a panel menu group.	`panelBorderColor`	border-top-color
`.rf-pm-gr-gr` This class defines styles for a panel menu group as part of another panel menu group.	No skin parameters.
`.rf-pm-gr-sel` This class defines styles for a panel menu group when it is selected.	No skin parameters.
`.rf-pm-gr-hdr` This class defines styles for the header of a panel menu group.	`generalTextColor`	color
`.rf-pm-gr-hdr:hover` This class defines styles for the header of a panel menu group when the mouse hovers over it.	`additionalBackgroundColor`	background
`.rf-pm-gr-hdr-dis` This class defines styles for the header of a panel menu group when it is disabled.	`tabDisabledTextColor`	color
`.rf-pm-gr-ico` This class defines styles for the icon in a panel menu group.	No skin parameters.
`.rf-pm-gr-exp-ico` This class defines styles for the icon in a panel menu group when it is expanded.	No skin parameters.
`.rf-pm-gr-lbl` This class defines styles for the label in a panel menu group.	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-pm-gr-cnt` This class defines styles for the content of a panel menu group.	No skin parameters.
`.rf-pm-top-itm` This class defines styles for the top panel menu item.	`panelBorderColor`	border-color
	`generalTextColor`	color
`.rf-pm-top-itm-gr` This class defines styles for the top panel menu item as part of a panel menu group.	No skin parameters.
`.rf-pm-top-itm:hover` This class defines styles for the top panel menu item when the mouse hovers over it.	`headerTextColor`	color
`.rf-pm-top-itm-sel` This class defines styles for the top panel menu item when it is selected.	No skin parameters.
`.rf-pm-top-itm-dis` This class defines styles for the top panel menu item when it is disabled.	`tabDisabledTextColor`	color
`.rf-pm-top-itm-ico` This class defines styles for the icon in the top panel menu item.	No skin parameters.
`.rf-pm-top-itm-exp-ico` This class defines styles for the icon in the top panel menu item when it is expanded.	No skin parameters.
`.rf-pm-top-itm-lbl` This class defines styles for the label in the top panel menu item.	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-pm-top-gr` This class defines styles for the top panel menu group.	`panelBorderColor`	border-color
`.rf-pm-top-gr-gr` This class defines styles for the top panel menu group as part of another panel menu group.	No skin parameters.
`.rf-pm-top-gr-sel` This class defines styles for the top panel menu group when it is selected.	No skin parameters.
`.rf-pm-top-gr-hdr` This class defines styles for the header of the top panel menu group.	`headerTextColor`	color
	`headerBackgroundColor`	background-color
`.rf-pm-top-gr-hdr-dis` This class defines styles for the header of the top panel menu group when it is disabled.	`tabDisabledTextColor`	color
	`additionalBackgroundColor`	background-color
`.rf-pm-top-gr-ico` This class defines styles for the icon in the top panel menu group.	No skin parameters.
`.rf-pm-top-gr-exp-ico` This class defines styles for the icon in the top panel menu group when it is expanded.	No skin parameters.
`.rf-pm-top-gr-lbl` This class defines styles for the label in the top panel menu group.	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-pm-top-gr-cnt` This class defines styles for the content of the top panel menu group.	No skin parameters.

⁠14.4.9. `<rich:panelMenuGroup>`

The <rich:panelMenuGroup> component defines a group of <rich:panelMenuItem> components inside a <rich:panelMenu>.

⁠14.4.9.1. Basic usage

The <rich:panelMenuGroup> component needs the label attribute declared, which specifies the text to show for the menu entry. Alternatively, the label facet can be used to specify the menu text.

In addition, the <rich:panelMenuGroup> component at least one <rich:panelMenuGroup> or <rich:panelMenuItem> components as child elements.

⁠14.4.9.2. Appearance

Icons for the menu group are inherited from the parent <rich:panelMenu> component. Refer to Section 14.4.3, “Appearance” for details on icon attributes and facets. Alternatively, the menu group's icons can be re-defined at the <rich:panelMenuGroup> component level, and these settings will be used instead of the parent component's settings.

⁠14.4.9.3. Submission modes

If the mode attribute is unspecified, the submission behavior for the group is inherited from the parent <rich:panelMenu>. Otherwise, the groupMode setting of the panel menu is used instead of the parent's behavior. Refer to Section 14.4.4, “Submission modes” for submission mode settings.

⁠14.4.9.4. `<rich:panelMenuGroup>` server-side events

The <rich:panelMenuGroup> component fires the ActionEvent event on the server side when the menu group receives a user action. The event only fires in the server and ajax submission modes. The event provides the action attribute to specify the user action method, and the actionListener attribute to reference the event listener.

⁠14.4.9.5. JavaScript API

The <rich:panelMenuGroup> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

expand(): Expand this panel menu group.
collapse(): Collapse this panel menu group.
select(id): Select the menu item with the id identifier.

⁠14.4.9.6. Reference data

component-type: org.richfaces.PanelMenuGroup
component-class: org.richfaces.component.UIPanelMenuGroup
component-family: org.richfaces.PanelMenuGroup

⁠14.4.10. `<rich:panelMenuItem>`

The <rich:panelMenuItem> component represents a single item inside a <rich:panelMenuGroup> component, which is in turn part of a <rich:panelMenu> component.

⁠14.4.10.1. Basic usage

The <rich:panelMenuItem> component needs the label attribute declared, which specifies the text to show for the menu entry. Alternatively, the label facet can be used to specify the menu text.

⁠14.4.10.2. Appearance

Icons for the menu item are inherited from the parent <rich:panelMenu> or <rich:panelMenuGroup> component. Refer to Section 14.4.3, “Appearance” for details on icon attributes and facets. Alternatively, the menu item's icons can be re-defined at the <rich:panelMenuItem> component level, and these settings will be used instead of the parent component's settings.

⁠14.4.10.3. Submission modes

If the mode is unspecified, the submission behavior for the item is inherited from the parent <rich:panelMenu>. Otherwise, the itemMode setting from the panel menu is used instead of the parent's behavior.

⁠14.4.10.4. `<rich:panelMenuItem>` server-side events

The <rich:panelMenuItem> component fires the ActionEvent event on the server side when the menu item receives a user action. The event only fires in the server and ajax submission modes. The event provides the action attribute to specify the user action performed, and the actionListener attribute to reference the event listener.

⁠14.4.10.5. JavaScript API

The <rich:panelMenuItem> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

select(): Select this menu item.

⁠14.4.10.6. Reference data

component-type: org.richfaces.PanelMenuItem
component-class: org.richfaces.component.UIPanelMenuItem
component-family: org.richfaces.PanelMenuItem