Create new RichFaces Documentation Jira issue
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.
JBoss.orgCommunity Documentation
The <rich:dropDownMenu> component is used for creating multilevel drop-down menus.
Highly customizable look-and-feel
Pop-up appearance event customization
Different submission modes
Ability to define a complex representation for elements
Support for disabling
Smart user-defined positioning
All attributes except "value" are optional. The "value" attribute defines text to be represented. If you can use the "label" facet, you can even not use the "value" attribute.
Here is an example:
Example:
...
<f:facet name="label">
<h:graphicImage value="/images/img1.png"/>
</f:facet>
...
Use the "event" attribute to define an event for the represented element that triggers a menu appearance. An example of a menu appearance on a click can be seen below.
Example:
...
<rich:dropDownMenu event="onclick" value="Item1">
<!--Nested menu components-->
</rich:dropDownMenu>
...
The <rich:dropDownMenu> "submitMode" attribute can be set to three possible parameters:
Server (default)
Regular form submission request is used.
Ajax
Ajax submission is used for switching.
None
The "action" and "actionListener" item's attributes are ignored. Menu items don't fire any submits themselves. The behavior is fully defined by the components nested into items.
As the <rich:dropDownMenu> component doesn't provide its own form, use it between <h:form> and </h:form> tags.
The "direction" and "jointPoint" attributes are used for defining aspects of menu appearance.
Possible values for the "direction" attribute are:
"top-left" - a menu drops to the top and left
"top-right" - a menu drops to the top and right
"bottom-left" - a menu drops to the bottom and left
"bottom-right" - a menu drops to the bottom and right
"auto" - smart positioning activation
Possible values for the "jointPoint" attribute are:
"tr" - a menu is attached to the top-right point of the button element
"tl" - a menu is attached to the top-left point of the button element
"br" - a menu is attached to the bottom-right point of the button element
"bl" - a menu is attached to the bottom-left point of the button element
"auto" - smart positioning activation
By default, the "direction" and "jointPoint" attributes are set to "auto".
Here is an example:
Example:
...
<rich:dropDownMenu value="File" direction="bottom-right" jointPoint="bl">
<rich:menuItem submitMode="ajax" value="New" action="#{ddmenu.doNew}"/>
<rich:menuItem submitMode="ajax" value="Open" action="#{ddmenu.doOpen}"/>
<rich:menuGroup value="Save As...">
<rich:menuItem submitMode="ajax" value="Text File" action="#{ddmenu.doSaveText}"/>
<rich:menuItem submitMode="ajax" value="PDF File" action="#{ddmenu.doSavePDF}"/>
</rich:menuGroup>
<rich:menuItem submitMode="ajax" value="Close" action="#{ddmenu.doClose}"/>
<rich:menuSeparator id="menuSeparator11"/>
<rich:menuItem submitMode="ajax" value="Exit" action="#{ddmenu.doExit}"/>
</rich:dropDownMenu>
...
This is the result:
You can correct an offset of the pop-up list relative to the label using the following attributes: "horizontalOffset" and "verticalOffset" .
Here is an example:
Example:
...
<rich:dropDownMenu value="File" direction="bottom-right" jointPoint="tr" horizontalOffset="-15" verticalOffset="0">
<rich:menuItem submitMode="ajax" value="New" action="#{ddmenu.doNew}"/>
<rich:menuItem submitMode="ajax" value="Open" action="#{ddmenu.doOpen}"/>
<rich:menuGroup value="Save As...">
<rich:menuItem submitMode="ajax" value="Text File" action="#{ddmenu.doSaveText}"/>
<rich:menuItem submitMode="ajax" value="PDF File" action="#{ddmenu.doSavePDF}"/>
</rich:menuGroup>
<rich:menuItem submitMode="ajax" value="Close" action="#{ddmenu.doClose}"/>
<rich:menuSeparator id="menuSeparator11"/>
<rich:menuItem submitMode="ajax" value="Exit" action="#{ddmenu.doExit}"/>
</rich:dropDownMenu>
...
This is the result:
The "disabled" attribute is used for disabling whole <rich:dropDownMenu> component. In this case it is necessary to define "disabled" attribute as "true". An example is placed below.
Example:
...
<rich:dropDownMenu value="File" disabled="true">
...
</rich:dropDownMenu>
...
Table of <rich:dropDownMenu> attributes.
Table 6.77. Component Identification Parameters
| Name | Value |
|---|---|
| component-type | org.richfaces.DropDownMenu |
| component-class | org.richfaces.component.html.HtmlDropDownMenu |
| component-family | org.richfaces.DropDownMenu |
| renderer-type | org.richfaces.DropDownMenuRenderer |
| tag-class | org.richfaces.taglib.DropDownMenuTag |
Table 6.78. Facets
| Facet | Description |
|---|---|
| label | Redefines the content set of label |
| labelDisabled | Redefines the content set of disabled label |
Table 6.79. Classes names that define a label
| Class name | Description |
|---|---|
| rich-label-text-decor | Defines text style for a representation element |
| rich-ddmenu-label | Defines styles for a wrapper <div> element of a representation element |
| rich-ddmenu-label-select | Defines styles for a wrapper <div> element of a selected representation element |
| rich-ddmenu-label-unselect | Defines styles for a wrapper <div> element of an unselected representation element |
| rich-ddmenu-label-disabled | Defines styles for a wrapper <div> element of a disabled representation element |
Table 6.80. Classes names that define a popup element
| Class name | Description |
|---|---|
| rich-menu-list-border | Defines styles for borders |
| rich-menu-list-bg | Defines styles for a general background list |
| rich-menu-list-strut | Defines styles for a wrapper <div> element for a strut of a popup list |
On the component LiveDemo page you can see the example of <rich:dropDownMenu> usage and sources for the given example.
