Modals

Overview

Modals are defined by annotating a method with @Modal. The first parameter must always be a ModalEvent.

@Modal("My Modal")
public void onModal(ModalEvent event) { ... }

Replying with Modals

You can reply to CommandEvents and ComponentEvents with a Modal by calling ModalReplyableEvent#replyModal(String, ModalTopLevelComponent, Entry...) on the event.

Example

event.replyModal("onModal", TextDisplay.of("Hello World"));

Foreign Modals

You can also reply with modals that were defined in a different class by calling ModalReplyableEvent#replyModal(Class, String, ModalTopLevelComponent, Entry...).

Example

event.replyModal(ModalHelpers.class, "onModal", TextDisplay.of("Hello World"));

Modal Components

Modals consist of a title, which is set via the @Modal annotation, and of up to 5 components.

These components aren't defined via annotations, but are just passed over to the reply method.

Example

@Command("ban")
public void onCommand(CommandEvent event, User target) {
    event.replyModal("onModal", TextDisplay.of("Do you really want to ban the user?")); //(1)!
}

@Modal("Confirm ban")
public void onModal(ModalEvent event) { ... }

1. We reference the Modal we want to send via the method name.

When using input components, such as a text input or select menu, you can access the ModalMappings directly via the ModalEvent.

Example

@Modal("User Select")
public void onModal(ModalEvent event) {
    event.replyModal("onModal", Label.of(
        "Select a user",
        EntitySelectMenu.create("user-select", SelectTarget.USER).build()
    ));
}

@Modal("Example")
public void onModal(ModalEvent event) { 
    var value = event.value("user-select");
}

Localization and Placeholders

To avoid hardcoded values, all string values can be replaced by a localization key as supported by the current used Localization System.

Furthermore, it's possible to directly use placeholders. For more information on how to use placeholders please visit this page.

Also take a look at the general message resolution documentation.

Key Example (with Fluava)

@Command("ban")
public void onCommand(CommandEvent event, User target) {
    event.replyModal("onModal", TextDisplay.of("modal-text"));
}

@Modal("modal-title")
public void onModal(ModalEvent event) { ... }

When using placeholders, you have to also pass the Entries to the reply method.

Placeholder Example

@Command("ban")
public void onCommand(CommandEvent event, User target) {
    event.replyModal("onModal", List.of(TextDisplay.of("modal-text")), entry("modal_name", target.getName()));
}

@Modal("Ban { $user_name }?")
public void onModal(ModalEvent event) { ... }

Unicode and application emojis

JDA-Commands has built in support for Unicode and application emoji aliases. If you want to use them, just take a look here.

Example

@Modal("Example :thumbs_up:")
public void onModal(ModalEvent event) { ... }