Keywords: rich:dropDownMenu

JBoss.org Community Documentation

- Prev
- Next

## 6.45. < rich:dropDownMenu >

### 6.45.1. Description

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

Figure 6.87. <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 Name | Description
--- | ---
binding | The attribute takes a value-binding expression for a component property of a backing bean
direction | Defines direction of the popup list to appear. Possible values are "top-right", "top-right", "top-left", "bottom-right", "bottom-left", "auto". Default value is "auto".
disabled | Attribute 'disabled' provides possibility to make the whole menu disabled if its value equals to "true".
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.
disabledLabelClass | Space-separated list of CSS style class(es) that are be applied to disabled label of DD menu
event | Defines the event on the representation element that triggers the menu's appearance.
hideDelay | Delay between losing focus and menu closing. Default value is "800".
horizontalOffset | Sets the horizontal offset between popup list and label element. Default value is "0". conjunction point
id | Every component may have a unique id that is automatically created if omitted
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.
jointPoint | Sets the corner of the label for the pop-up to be connected with. Possible values are "tr", "tl", "bl", "br", "bottom-left", "auto". Default value is "auto". "tr" stands for top-right.
oncollapse | Event must occurs on menu closure
onexpand | Event must occurs on menu opening
ongroupactivate | HTML: script expression; some group was activated.
onitemselect | HTML: script expression; some item was selected.
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.
popupWidth | Sets minimal width for all lists that will appear.
rendered | If "false", this component is not rendered
selectedLabelClass | Space-separated list of CSS style class(es) that are be applied to selected label of DD menu
selectItemClass | Space-separated list of CSS style class(es) that are be applied to selected item of this component.
selectItemStyle | CSS style(s) is/are to be applied to selected item when this component is rendered.
showDelay | Delay between event and menu showing. Default value is "50".
style | CSS style(s) is/are to be applied when this component is rendered
styleClass | Corresponds to the HTML class attribute
submitMode | Sets the submission mode for all menu items of the menu except ones where this attribute redefined. Possible values are "ajax","server","none". Default value is "sever".
value | Defines representation text for Label used for menu calls.
verticalOffset | Sets the vertical offset between popup list and label element. Default value is "0". conjunction point

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

### 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:

Figure 6.88. 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:

Figure 6.89. 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 parameters | CSS properties
--- | ---
generalFamilyFont | font-family
generalSizeFont | font-size

Table 6.165. Skin parameters redefinition for a selected label

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color
controlBackgroundColor | background-color
generalTextColor | background-colorcolor

Table 6.166. Skin parameters redefinition for a border

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color
additionalBackgroundColor | background-color

Table 6.167. Skin parameters redefinition for a background

Skin parameters | CSS properties
--- | ---
additionalBackgroundColor | border-top-color
additionalBackgroundColor | border-left-color
additionalBackgroundColor | border-right-color

### 6.45.8. Definition of Custom Style Classes

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

Figure 6.90. Classes names

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

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

Figure 6.91. Classes names

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

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:

Figure 6.92. Redefinition styles with predefined classes

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

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

Example:

    ...

    .myClass{

        font-style: italic;

    }

    ...

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

Example:

    <rich:dropDownMenu ... itemClass="myClass"/>

This is a result:

Figure 6.93. Redefinition styles with own classes and styleClass attributes

As it could be seen on the picture above, the font style for items was changed.

### 6.45.9. Relevant Resources Links

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

- Prev6.44. < rich:dropListener >
- Top of page
- Front page
- Next6.46. < rich:menuGroup >