Keywords: rich:panelMenu

JBoss.org Community Documentation

- Prev
- Next

## 6.68. < rich:panelMenu >

### 6.68.1. Description

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

Figure 6.197. <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 Name | Description
--- | ---
binding | The attribute takes a value-binding expression for a component property of a backing bean
converter | Id of Converter to be used or reference to a Converter
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
disabled | If true sets state of the item to disabled state. Default value is "false".
disabledGroupClass | Space-separated list of CSS style class(es) that are be applied to disabled group of this component
disabledGroupStyle | CSS style(s) is/are to be applied to disabled group when this component is rendered
disabledItemClass | Space-separated list of CSS style class(es) that are be applied to disabled item of this component
disabledItemStyle | CSS style(s) is/are to be applied to disabled item when this component is rendered.
event | Defines the event on the representation element that triggers the submenu's expand/collapse. Default value is "onclick".
expandMode | Set the submission mode for all panel menu groups after expand/collapse except ones where this attribute redefined. Possible values are "ajax", "server", "none". Default value is "none".
expandSingle | Whether 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. Default value is "false".
groupClass | Space-separated list of CSS style class(es) that are be applied to group of this component
groupStyle | CSS style(s) is/are to be applied to group when this component is rendered
hoveredGroupClass | Space-separated list of CSS style class(es) that are be applied to hovered group of this component
hoveredGroupStyle | CSS style(s) is/are to be applied to hovered group when this component is rendered
hoveredItemClass | Space-separated list of CSS style class(es) that are be applied to hovered item of this component
hoveredItemStyle | CSS style(s) is/are to be applied to hovered item when this component is rendered
iconCollapsedGroup | Path to the icon to be displayed for the collapsed Group state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconCollapsedTopGroup | Path to the icon to be displayed for the collapsed top group state.\ You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconDisabledGroup | Path to the icon to be displayed for the disabled group state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconDisabledItem | Path to the icon to be displayed for the disabled item state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconExpandedGroup | Path to the icon to be displayed for the expanded Group state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconExpandedTopGroup | Path to the icon to be displayed for the expanded top group state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconGroupPosition | Position of the icon for the group icon. Possible values are "left","right","none". Default value is "left".
iconGroupTopPosition | Position of the icon for the top group icon. Possible values are "left","right","none". Default value is "left".
iconItem | Path to the icon to be displayed for the enabled item state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconItemPosition | Position of the icon for the item icon. Possible values are "left","right","none". Default value is "left".
iconItemTopPosition | Position of the icon for the top item icon. Possible values are "left","right","none". Default value is "left".
iconTopDisabledItem | Path to the icon to be displayed for the disabled top item state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconTopDisableGroup | Path to the icon to be displayed for the disabled top Group state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
iconTopItem | Path to the icon to be displayed for the enabled top item state. You can also use predefined icons, setting the attribute to one of these possible values: "triangle", "triangleUp", "triangleDown", "disc", "chevron", "chevronUp", "chevronDown", "grid". Default value is "grid".
id | Every component may have a unique id that is automatically created if omitted
immediate | A 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
itemClass | Space-separated list of CSS style class(es) that are be applied to item of this component
itemStyle | CSS style(s) is/are to be applied to item when this component is rendered.
label | A localized user presentable name for this component.
mode | Set the submission mode for all panel menu items on the panel menu except ones where this attribute redefined. Possible values are "ajax", "server", "none". Default value is "server".
onclick | HTML: a script expression; a pointer button is clicked
ondblclick | HTML: a script expression; a pointer button is double-clicked
ongroupcollapse | HTML: script expression; some group was closed
ongroupexpand | HTML: script expression; some group was activated
onitemhover | HTML: script expression; some item was hovered
onkeydown | HTML: a script expression; a key is pressed down
onkeypress | HTML: a script expression; a key is pressed and released
onkeyup | HTML: a script expression; a key is released
onmousedown | HTML: script expression; a pointer button is pressed down
onmousemove | HTML: script expression; a pointer was moved within.
onmouseout | HTML: script expression; a pointer was moved away.
onmouseover | HTML: script expression; a pointer was moved onto.
onmouseup | HTML: script expression; a pointer button is released
rendered | If "false", this component is not rendered
required | If "true", this component is checked for non-empty input
requiredMessage | A 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
selectedChild | contain the name or the clientId of any of the item or group, the child defined in this attribute should be highlighted on PanelMenu rendering
style | The CSS style for the panel menu.
styleClass | The CSS class for the panel menu.
topGroupClass | Space-separated list of CSS style class(es) that are be applied to top group of this component
topGroupStyle | CSS style(s) is/are to be applied to top group when this component is rendered
topItemClass | Space-separated list of CSS style class(es) that are be applied to top item of this component
topItemStyle | CSS style(s) is/are to be applied to top item when this component is rendered
validator | MethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
value | The current value of this component
valueChangeListener | Listener for value changes
width | Set minimal width for the menu. Default value is "100%".

Table 6.346. Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.PanelMenu
component-class | org.richfaces.component.html.HtmlPanelMenu
component-family | org.richfaces.PanelMenu
renderer-type | org.richfaces.PanelMenuRenderer
tag-class | org.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.

Figure 6.198. 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

Function | Description
--- | ---
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 name | Class description
--- | ---
rich-pmenu | Defines 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{

        font-style:italic;

    }

    ...

This is a result:

Figure 6.199. Redefinition styles with predefined classes

In the example the font style 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: #ecf4fe;

    }

    ...

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:

Figure 6.200. 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.

- Prev6.67. < rich:panelBarItem >
- Top of page
- Front page
- Next6.69. < rich:panelMenuGroup >