6.45.  < rich:dropDownMenu >

6.45.1. Description

The <rich:dropDownMenu> component is used for creating multilevel drop-down menus.

<rich:dropDownMenu> component

Figure 6.75.  <rich:dropDownMenu> component


6.45.2. Key Features

  • 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

Table 6.162. rich : dropDownMenu attributes

Attribute NameDescription
bindingThe attribute takes a value-binding expression for a component property of a backing bean
directionDefines direction of the popup list to appear (top-right, top-left bottom-right, bottom-left, auto(default))
disabledAttribute 'disabled' provides possibility to make the whole menu disabled if its value equals to "true".
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.
disabledLabelClassSpace-separated list of CSS style class(es) that are be applied to disabled label of DD menu
eventDefines the event on the representation element that triggers the menu's appearance.
hideDelayDelay between losing focus and menu closing.
horizontalOffsetSets the horizontal offset between popup list and label element conjunction point
idEvery component may have a unique id that is automatically created if omitted
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.
jointPointSet the corner of the label for the popup to be connected with. (auto(default), tr, tl, bl, br, where tr top-right)
oncollapseEvent must occurs on menu closure
onexpandEvent must occurs on menu opening
ongroupactivateHTML: script expression; some group was activated.
onitemselectHTML: script expression; some item was selected.
onmousemoveHTML: script expression; a pointer was moved within.
onmouseoutHTML: script expression; a pointer was moved away.
onmouseoverHTML: script expression; a pointer was moved onto.
popupWidthSet minimal width for the all of the lists that will appear.
renderedIf "false", this component is not rendered
selectedLabelClassSpace-separated list of CSS style class(es) that are be applied to selected label of DD menu
selectItemClassSpace-separated list of CSS style class(es) that are be applied to selected item of this component.
selectItemStyleCSS style(s) is/are to be applied to selected item when this component is rendered.
showDelayDelay between event and menu showing.
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
submitModeSet the submission mode for all menu items of the menu except ones where this attribute redefined. (ajax,server(Default),none)
valueDefines representation text for Label used for menu calls.
verticalOffsetSets the vertical offset between popup list and label element conjunction point

Table 6.163. Component identification parameters

NameValue
component-typeorg.richfaces.DropDownMenu
component-classorg.richfaces.component.html.HtmlDropDownMenu
component-familyorg.richfaces.DropDownMenu
renderer-typeorg.richfaces.DropDownMenuRenderer
tag-classorg.richfaces.taglib.DropDownMenuTag

6.45.3. Creating the Component with a Page Tag

Here is a simple example as it could be used on a page:

Example:


...
<rich:dropDownMenu value="Item1">
    <!--Nested menu components-->
</rich:dropDownMenu>
...

6.45.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlDropDownMenu;   
...
HtmlDropDownMenu myDropDownMenu = new HtmlDropDownMenu();
...

6.45.5. Details of Usage

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.

Note:

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="tr">
    <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:

Using the "direction" and "joinPoint" attributes

Figure 6.76. Using the "direction" and "joinPoint" attributes


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:

Using the "horizontalOffset" and "verticalOffset" attributes

Figure 6.77. Using the "horizontalOffset" and "verticalOffset" attributes


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

6.45.6. Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:dropDownMenu> components at once:

  • Redefine the corresponding skin parameters

  • Add to your style sheets style classes used by a <rich:dropDownMenu> component

6.45.7.  Skin Parameters Redefinition

Table 6.164. Skin parameters redefinition for a label <div> element

Skin parametersCSS properties
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.165. Skin parameters redefinition for a selected label

Skin parametersCSS properties
panelBorderColorborder-color
controlBackgroundColorbackground-color
generalTextColorbackground-colorcolor

Table 6.166. Skin parameters redefinition for a border

Skin parametersCSS properties
panelBorderColorborder-color
additionalBackgroundColorbackground-color

Table 6.167. Skin parameters redefinition for a background

Skin parametersCSS properties
additionalBackgroundColorborder-top-color
additionalBackgroundColorborder-left-color
additionalBackgroundColorborder-right-color

6.45.8. Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

Classes names

Figure 6.78. Classes names


Table 6.168. Classes names that define a label

Class nameDescription
rich-label-text-decorDefines text style for a representation element
rich-ddmenu-labelDefines styles for a wrapper <div> element of a representation element
rich-ddmenu-label-selectDefines styles for a wrapper <div> element of a selected representation element
rich-ddmenu-label-unselectDefines styles for a wrapper <div> element of an unselected representation element
rich-ddmenu-label-disabledDefines styles for a wrapper <div> element of a disabled representation element

On the screenshot there are classes names that define styles for component elements.

Classes names

Figure 6.79. Classes names


Table 6.169. Classes names that define a popup element

Class nameDescription
rich-menu-list-borderDefines styles for borders
rich-menu-list-bgDefines styles for a general background list
rich-menu-list-strutDefines styles for a wrapper <div> element for a strut of a popup list

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

Example:


...
.rich-ddmenu-label-select{
    
background-color:  #fae6b0;
    
border-color: #e5973e;
}
...

This is a result:

Redefinition styles with predefined classes

Figure 6.80. Redefinition styles with predefined classes


In the example a label select background color and border color were changed.

6.45.9. Relevant Resources Links

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