6.68.  < rich:panelMenu >

6.68.1. Description

The <rich:panelMenu> component is used to define an in line vertical menu on a page.

<rich:panelMenu> component

Figure 6.173.  <rich:panelMenu> component


6.68.2. Key Features

  • Highly customizable look and feel

  • Different submission modes

  • Collapsing/expanding sublevels with optional request sending

  • Custom and predefined icons support

  • Disablement support

Table 6.345. rich : panelMenu attributes

Attribute NameDescription
bindingThe attribute takes a value-binding expression for a component property of a backing bean
converterId of Converter to be used or reference to a Converter
converterMessageA ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
disabledIf true sets state of the item to disabled state. false is default.
disabledGroupClassSpace-separated list of CSS style class(es) that are be applied to disabled group of this component
disabledGroupStyleCSS style(s) is/are to be applied to disabled group when this component is rendered
disabledItemClassSpace-separated list of CSS style class(es) that are be applied to disabled item of this component
disabledItemStyleCSS style(s) is/are to be applied to disabled item when this component is rendered.
eventDefines the event on the representation element that triggers the submenu's expand/collapse. (default=onclick)
expandModeSet the submission mode for all panel menu groups after expand/collapse except ones where this attribute redefined. (ajax, server, none(Default))
expandSingleWhether only one panel menu node on top level can be opened at a time. If the value of this attribute is true, the previously opened node on the top level is closed. If the value is false, the node is left opened. The default value is false.
groupClassSpace-separated list of CSS style class(es) that are be applied to group of this component
groupStyleCSS style(s) is/are to be applied to group when this component is rendered
hoveredGroupClassSpace-separated list of CSS style class(es) that are be applied to hovered group of this component
hoveredGroupStyleCSS style(s) is/are to be applied to hovered group when this component is rendered
hoveredItemClassSpace-separated list of CSS style class(es) that are be applied to hovered item of this component
hoveredItemStyleCSS style(s) is/are to be applied to hovered item when this component is rendered
iconCollapsedGroupPath to the icon to be displayed for the collapsed Group state
iconCollapsedTopGroupPath to the icon to be displayed for the collapsed top group state
iconDisabledGroupPath to the icon to be displayed for the disabled group state
iconDisabledItemPath to the icon to be displayed for the disabled item state
iconExpandedGroupPath to the icon to be displayed for the expanded Group state
iconExpandedTopGroupPath to the icon to be displayed for the expanded top group state
iconGroupPositionPosition of the icon (left, right none (default) ) for the group icon
iconGroupTopPositionPosition of the icon (left, right none (default) ) for the top group icon
iconItemPath to the icon to be displayed for the enabled item state
iconItemPositionPosition of the icon (left, right none (default) ) for the item icon
iconItemTopPositionPosition of the icon (left, right none (default) ) for the top item icon
iconTopDisabledItemPath to the icon to be displayed for the disabled top item state
iconTopDisableGroupPath to the icon to be displayed for the disabled top Group state
iconTopItemPath to the icon to be displayed for the enabled top item state
idEvery component may have a unique id that is automatically created if omitted
immediateA flag indicating that this component value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until a Process Validations phase
itemClassSpace-separated list of CSS style class(es) that are be applied to item of this component
itemStyleCSS style(s) is/are to be applied to item when this component is rendered.
labelA localized user presentable name for this component.
modeSet the submission mode for all panel menu items on the panel menu except ones where this attribute redefined. (ajax, server,(Default), none)
onclickHTML: a script expression; a pointer button is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
ongroupcollapseHTML: script expression; some group was closed
ongroupexpandHTML: script expression; some group was activated
onitemhoverHTML: script expression; some item was hovered
onkeydownHTML: a script expression; a key is pressed down
onkeypressHTML: a script expression; a key is pressed and released
onkeyupHTML: a script expression; a key is released
onmousedownHTML: script expression; a pointer button is pressed down
onmousemoveHTML: script expression; a pointer was moved within.
onmouseoutHTML: script expression; a pointer was moved away.
onmouseoverHTML: script expression; a pointer was moved onto.
onmouseupHTML: script expression; a pointer button is released
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
requiredMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validation message for the "required" facility, if the "required" facility is used
selectedChildcontain the name or the clientId of any of the item or group, the child defined in this attribute should be highlighted on PanelMenu rendering
styleThe CSS style for the panel menu.
styleClassThe CSS class for the panel menu.
topGroupClassSpace-separated list of CSS style class(es) that are be applied to top group of this component
topGroupStyleCSS style(s) is/are to be applied to top group when this component is rendered
topItemClassSpace-separated list of CSS style class(es) that are be applied to top item of this component
topItemStyleCSS style(s) is/are to be applied to top item when this component is rendered
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
valueThe current value of this component
valueChangeListenerListener for value changes
widthSet minimal width for the menu.

Table 6.346. Component identification parameters

NameValue
component-typeorg.richfaces.PanelMenu
component-classorg.richfaces.component.html.HtmlPanelMenu
component-familyorg.richfaces.PanelMenu
renderer-typeorg.richfaces.PanelMenuRenderer
tag-classorg.richfaces.taglib.PanelMenuTag

6.68.3. Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:


...
      <rich:panelMenu event="onmouseover">
            <!--Nested panelMenu components-->
      </rich:panelMenu>
...

6.68.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlPanelMenu;  
...
HtmlPanelMenu myPanelMenu = new HtmlPanelMenu();
...

6.68.5. Details of Usage

All attributes are not required.

Use "event" attribute to define an event for appearance of collapsing/expanding sublevels. Default value is "onclick" . An example could be seen below.

Example:


...
      <rich:panelMenu event="onmouseover">
            <!--Nested panelMenu components-->
      </rich:panelMenu>
...

Switching mode could be chosen with the "mode" attribute for all panelMenu items except ones where this attribute was redefined. By default all items send traditional request.

The "expandMode" attribute defines the submission modes for all collapsing/expanding panelMenu groups except ones where this attribute was redefined.

The "mode" and "expandMode" attributes could be used with three possible parameters. The "mode" attribute defines parameters for all included <rich:panelMenuItem> elements.

  • Server (default)

The common submission of the form is performed and a page is completely refreshed.

Example:


...
      <rich:panelMenu mode="server">
          <rich:panelMenuGroup label="test Group" action="#{bean.action}"> 
              <rich:panelMenuItem label="test" action="#{capitalsBean.action}"> 
                  <f:param value="test value" name="test"/> 
              </rich:panelMenuItem> 
          </rich:panelMenuGroup>
      </rich:panelMenu>
...
  • Ajax

An Ajax form submission is performed, and additionally specified elements in the "reRender" attribute are reRendered.

Example:


...
      <rich:panelMenu mode="ajax">
           <rich:panelMenuGroup label="test Group" action="#{bean.action}"> 
               <rich:panelMenuItem label="test" reRender="test" action="#{capitalsBean.action}"> 
                   <f:param value="test value" name="test"/> 
               </rich:panelMenuItem> 
          </rich:panelMenuGroup>
      </rich:panelMenu>
...
  • None

"Action" and "ActionListener" item's attributes are ignored. Items don't fire any submits itself. Behavior is fully defined by the components nested into items.

Example:


...
      <rich:panelMenu event="onclick" submitMode="none">
            <rich:panelMenuItem label="Link to external page">
                  <h:outputLink ... >
            <rich:panelMenuItem>
      </rich:panelMenu>
...

Note:

As the <rich:panelMenu> component doesn't provide its own form, use it between <h:form> and </h:form> tags.

The "expandSingle" attribute is defined for expanding more than one submenu on the same level. The default value is "false" . If it's true the previously opened group on the top level closes before opening another one. See the picture below.

Using the "expandSingle" attribute

Figure 6.174. Using the "expandSingle" attribute


The "selectedChild" attribute is used for defining the name of the selected group or item. An example for group is placed below:

Here is an example:

Example:


...
      <rich:panelMenu selectedChild="thisChild">
        <rich:panelMenuGroup label="Group1" name="thisChild">
          <!--Nested panelMenu components-->
        </rich:panelMenuGroup>
      </rich:panelMenu>
      ...

The "label" attribute is a generic attribute. The "label" attribute provides an association between a component, and the message that the component (indirectly) produced. This attribute defines the parameters of localized error and informational messages that occur as a result of conversion, validation, or other application actions during the request processing lifecycle. With the help of this attribute you can replace the last parameter substitution token shown in the messages. For example, {1} for “DoubleRangeValidator.MAXIMUM”, {2} for “ShortConverter.SHORT”.

6.68.6. JavaScript API

In Java Script code for expanding/collapsing group element creation it's necessary to use expand()/collapse() function.

Table 6.347. JavaScript API

FunctionDescription
expand()Expands group element
collapse()Collapses group element

6.68.7. Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method.

There are no skin parameters. To redefine the appearance of all <rich:panelMenu> components at once, you should add to your style sheets the style class used by a <rich:panelMenu> component.

6.68.8. Definition of Custom Style Classes

Table 6.348. Classes names that define a component appearance

Class nameClass description
rich-panel-menuDefines styles for a wrapper <div> element of a component

In order to redefine styles for all <rich:panelMenu> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:


...
.rich-pmenu-group-self-label{
    
font-style:italic;
}
...

This is a result:

Redefinition styles with predefined classes

Figure 6.175. Redefinition styles with predefined classes


In the example the font style for mask was changed.

Also it’s possible to change styles of particular <rich:panelMenu> component. In this case you should create own style classes and use them in corresponding <rich:panelMenu> styleClass attributes. An example is placed below:

Example:


...
.myClass{
    
background-color:#ffead9;
}
...

The "hoveredItemClass" attribute for <rich:panelMenu> is defined as it’s shown in the example below:

Example:


<rich:panelMenu ... hoveredItemClass="myClass"/>

This is a result:

Redefinition styles with own classes and "styleClass" attributes

Figure 6.176. Redefinition styles with own classes and "styleClass" attributes


As it could be seen on the picture above,background color for hovered item was changed.

6.68.9. Relevant Resources Links

Here you can see the example of <rich:panelMenu> usage and sources for the given example.