dropdownButton

dropdownButton presents a main button, which, when clicked, reveals a dropdown menu containing a list of items.

XML Element

dropdownButton

Java Class

DropdownButton

Basics

LIVE DEMO

The main button displays the primary text, or icon (or both) for the component. Users click this button to access the dropdown menu.

The dropdown menu contains a list of actions, each represented by a clickable item.

Each item in the dropdown menu can represent an action. When a user clicks on an action, the corresponding event handler is triggered.

Here’s an example of defining a dropdownButton with a text, an icon and a tooltip (using the title attribute) retrieved from the message bundle:

XML
<layout classNames="horizontal-layout">
    <dropdownButton id="dropdownButton1" text="Save">
        <items>
            <textItem id="docSaveItem" text="Save as DOC"/>
            <textItem id="pdfSaveItem" text="Save as PDF"/>
        </items>
    </dropdownButton>
    <dropdownButton id="dropdownButton2" text="Save" icon="ARCHIVE">
        <items>
            <componentItem id="docSaveItem">
                <hbox padding="false">
                    <icon icon="FILE"/>
                    <span text="Save as DOC"/>
                </hbox>
            </componentItem>
            <componentItem id="pdfSaveItem">
                <hbox padding="false">
                    <icon icon="FILE"/>
                    <span text="Save as PDF"/>
                </hbox>
            </componentItem>
        </items>
    </dropdownButton>
    <dropdownButton id="dropdownButton3" icon="ARCHIVE"/>
</layout>
Java
@ViewComponent
private DropdownButton dropdownButton3;
@Subscribe
public void onInit(InitEvent event) {
    dropdownButton3.addItem(
            "docSaveItem",
            new BaseAction<>("docSave")
                    .withText("Save as DOC")
                    .withHandler(e -> saveAsDoc())
    );
    dropdownButton3.addSeparator();
    dropdownButton3.addItem(
            "docPdfItem",
            new BaseAction<>("pdfSave")
                    .withText("Save as PDF")
                    .withHandler(e -> saveAsPdf())
    );
}

Theme Variants

LIVE DEMO

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

primary

Applies the primary button style.

Aura, Lumo

success

Applies the success style.

Aura, Lumo

warning

Applies the warning style.

Aura, Lumo

error

Applies the error style.

Aura, Lumo

contrast

Applies the contrast style.

Lumo

large

Makes the button larger.

Aura, Lumo

small

Makes the button smaller.

Aura, Lumo

icon

Applies the icon-button style.

Aura, Lumo

tertiary

Applies a lower-emphasis button style.

Aura, Lumo

tertiary-inline

Applies an inline button style intended for use inside text content.

Lumo

Attributes

The following attributes are specific to dropdownButton:

Name Description Default

dropdownIndicatorVisible

Sets the visibility of the dropdown indicator.

true

icon

Sets the icon.

—

openOnHover

If the openOnHover attribute is true, the drop-down list of items is opened automatically when the field is focused using a mouse or touch.

false

overlayClass

Adds CSS class names to the component overlay.

—

The following shared attributes are supported by dropdownButton:

id - alignSelf - classNames - colspan - css - enabled - focusShortcut - height - maxHeight - maxWidth - minHeight - minWidth - tabIndex - text - themeNames - title - visible - whiteSpace - width

Handlers

The following shared handlers are supported by dropdownButton:

AttachEvent - BlurEvent - DetachEvent - FocusEvent

Elements

dropdownButton defined in the XML descriptor can contain nested elements:

actionItem

The actionItem element creates a link between a dropdown menu item and a specific action that should be executed when that item is clicked.

Use the ref attribute to point to the id of a defined action.

<actions>
    <action id="callAction" text="Call Us" icon="PHONE"/>
</actions>
<layout>
    <dropdownButton icon="MAILBOX" title="msg://contact" id="callBtn">
        <items>
            <actionItem id="callUsItem" ref="callAction"/>
        </items>
    </dropdownButton>
</layout>

When a user clicks on an actionItem in the dropdown, Jmix automatically triggers the action referenced by the ref attribute. Generate an ActionPerformedEvent handler method for this action. Add the logic to it:

@Subscribe("callAction")
public void onCallAction(final ActionPerformedEvent event) {
    notifications.show("Phone number: +6(876)5463");
}

componentItem

The componentItem element allows you to define custom inner content for dropdownButton.

<layout>
    <dropdownButton icon="MAILBOX" title="msg://contact" id="callBtn">
        <items>
            <componentItem id="emailIt">
                <hbox padding="false">
                    <icon icon="MAILBOX"/>
                    <span text="E Mail"/>
                </hbox>
            </componentItem>
        </items>
    </dropdownButton>
</layout>

You can generate a DropdownButtonItem.ClickEvent handler stub for componentItem using Jmix Studio.

@Subscribe("callBtn.emailIt")
public void onEmailItClick(final DropdownButtonItem.ClickEvent event) {
    notifications.show("Email: test@river.net");
}

textItem

The textItem element holds text.

<layout>
    <dropdownButton icon="MAILBOX" title="msg://contact" id="callBtn">
        <items>
            <textItem id="whatsAppIt" text="WhatsApp"/>
        </items>
    </dropdownButton>
</layout>

You can generate a DropdownButtonItem.ClickEvent handler stub for textItem using Jmix Studio.

@Subscribe("callBtn.whatsAppIt")
public void onCallBtnWhatsAppItClick(final DropdownButtonItem.ClickEvent event) {
    notifications.show("`WhatsApp: +6(876)5463");
}

separator

The separator element is used to visually separate items in the dropdown menu.

icon

The icon element adds a custom icon.