6.8.2. < rich:dropDownMenu > available since 3.0.0

### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.8.2. < rich:dropDownMenu > available since 3.0.0

expand all

#### 6.8.2.1. Description

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

Figure 6.57. <rich:dropDownMenu> component

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

#### 6.8.2.3. 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="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:

Figure 6.58. 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.59. 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.8.2.4. Reference Data

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

You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.

#### 6.8.2.5. Relevant Resources Links

On the component LiveDemo page you can see the example of <rich:dropDownMenu> usage and sources for the given example.

- Prev6.8.1. < rich:contextMenu > ...
- Top of page
- Front page
- Next6.8.3. < rich:menuGroup > ...