JBoss.orgCommunity Documentation

6.50.  < rich:dropDownMenu >

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


Table 6.197. 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. Possible values are "top-right", "top-right", "top-left", "bottom-right", "bottom-left", "auto". Default value is "auto".
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) applied to dropdown menu label when it is disabled.
eventDefines the event on the representation element that triggers the menu's appearance.
hideDelayDelay between losing focus and menu closing. Default value is "800".
horizontalOffsetSets the horizontal offset between popup list and label element. Default value is "0". 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.
jointPointSets 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.
labelClassSpace-separated list of CSS style class(es) applied to dropdown menu label in it normal (neither selected nor disabled) sate.
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.
popupWidthSets minimal width for all lists that will appear.
renderedIf "false", this component is not rendered
selectedLabelClassSpace-separated list of CSS style class(es) applied to dropdown menu label when it is selected.
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. Default value is "50".
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
submitModeSets 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".
valueDefines representation text for Label used for menu calls.
verticalOffsetSets the vertical offset between popup list and label element. Default value is "0". conjunction point

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

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

Example:


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

Example:

import org.richfaces.component.html.HtmlDropDownMenu;   

...
HtmlDropDownMenu myDropDownMenu = new HtmlDropDownMenu();
...

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:

Regular form submission request is used.

Ajax submission is used for switching.

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.

The "direction" and "jointPoint" attributes are used for defining aspects of menu appearance.

Possible values for the "direction" attribute are:

Possible values for the "jointPoint" attribute are:

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:


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

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:





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



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



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:


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:


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

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