The <rich:panelMenu> component is used to define an in line vertical menu on a page.
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. false is default. |
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=onclick) |
expandMode | Set the submission mode for all panel menu groups after expand/collapse except ones where this attribute redefined. (ajax, server, none(Default)) |
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. The 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 |
iconCollapsedTopGroup | Path to the icon to be displayed for the collapsed top group state |
iconDisabledGroup | Path to the icon to be displayed for the disabled group state |
iconDisabledItem | Path to the icon to be displayed for the disabled item state |
iconExpandedGroup | Path to the icon to be displayed for the expanded Group state |
iconExpandedTopGroup | Path to the icon to be displayed for the expanded top group state |
iconGroupPosition | Position of the icon (left, right none (default) ) for the group icon |
iconGroupTopPosition | Position of the icon (left, right none (default) ) for the top group icon |
iconItem | Path to the icon to be displayed for the enabled item state |
iconItemPosition | Position of the icon (left, right none (default) ) for the item icon |
iconItemTopPosition | Position of the icon (left, right none (default) ) for the top item icon |
iconTopDisabledItem | Path to the icon to be displayed for the disabled top item state |
iconTopDisableGroup | Path to the icon to be displayed for the disabled top Group state |
iconTopItem | Path to the icon to be displayed for the enabled top item state |
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. (ajax, server,(Default), none) |
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. |
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 |
To create the simplest variant on a page use the following syntax:
Example:
...
<rich:panelMenu event="onmouseover">
<!--Nested panelMenu components-->
</rich:panelMenu>
...
Example:
import org.richfaces.component.html.HtmlPanelMenu;
...
HtmlPanelMenu myPanelMenu = new HtmlPanelMenu();
...
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>
...
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.
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”.
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 |
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.
Table 6.348. Classes names that define a component appearance
Class name | Class description |
---|---|
rich-panel-menu | 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-group-self-label{
font-style:italic;
}
...
This is a result:
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:
As it could be seen on the picture above,background color for hovered item was changed.
Here you can see the example of <rich:panelMenu> usage and sources for the given example.