Components¶

Note

This section only covers how you define components. See the Reply API section to learn how to use them in replies.

Localization and Placeholders¶

To avoid hardcoded values, all string values of an annotation 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.

Example (with Fluava)

@Button(value = "my.localization.key", style = ButtonStyle.DANGER, link = "{ $jdac_link }")
public void onButton(ComponentEvent event) {...}

The Dollar Sign ($)

The dollar sign is a reserved character for bundle name separation. In most cases that shouldn't bother you but if you encounter any problems, please read the notes here.

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.

Buttons¶

Buttons are defined by annotating a method with @Button. The first parameter must always be a ComponentEvent. The label and other metadata of the button is passed to the annotation.

@Button("example")
public void onButton(ComponentEvent event) {...}

style¶

Sets the style of a button.

Button Styles

Example

@Button(value = "example", style = ButtonStyle.DANGER)
public void onButton(ComponentEvent event) {...}

Note

ButtonStyle#PREMIUM is not supported by JDA-Commands.

emoji¶

Sets the emoji of a button.

Example

@Button(value = "Emoji", emoji = "🤗")
public void onButton(ComponentEvent event) {...}

link¶

Buttons that have a link cannot be executed, but they are still defined like normal buttons.

Example

@Button(value = "JDA-Commands Wiki", link = "https://kaktushose.github.io/jda-commands/wiki/")
public void onButton(ComponentEvent event) { }

Select Menus¶

String Select Menus¶

String Select Menus are defined by annotating a method with @StringSelectMenu The first parameter must always be a ComponentEvent. The second parameter must be a List.

The placeholder and other metadata of the String Select Menu is passed to the annotation.

Select Options are defined by annotating the method with @MenuOption.

Example

@MenuOption(label= "Pizza", value = "pizza")
@MenuOption(label= "Hamburger", value = "hamburger")
@MenuOption(label= "Sushi", value = "Sushi")
@StringSelectMenu("What's your favourite food?")
public void onMenu(ComponentEvent event, List<String> choices) { ... }

Min & Max Value¶

String Select Menus support up to 25 options. You can set the minimum and maximum value by using the minValue and maxValue fields.

Example

@SelectOption(label= "Pizza", value = "pizza")
@SelectOption(label= "Hamburger", value = "hamburger")
@SelectOption(label= "Sushi", value = "Sushi")
...
@StringSelectMenu(value = "What's your favourite food?", minValue = 2, maxValue = 4)
public void onMenu(ComponentEvent event, List<String> choices) { ... }

Entity Select Menus¶

Entity Select Menus are defined by annotating a method with @EntitySelectMenu. The first parameter must always be a ComponentEvent. The second parameter must be of type Mentions.

Example

@EntitySelectMenu(value = SelectTarget.USER, placeholder = "Who's your favourite user?")
public void onMenu(ComponentEvent event, Mentions mentions) { ... }

Channel Types¶

When using SelectTarget.CHANNEL you can limit the selectable channel types with the channelTypes field.

Example

@EntitySelectMenu(
            value = SelectTarget.CHANNEL, 
            placeholder = "What's your favourite channel?", 
            channelTypes = {ChannelType.TEXT, ChannelType.VOICE}
)
public void onMenu(ComponentEvent event, Mentions mentions) { ... }

Default Values¶

You can set the default values of the Entity Select Menu by using respectively the defaultChannels, defaultRoles or defaultUsers fields.

Example

@EntitySelectMenu(
            value = SelectTarget.CHANNEL, 
            placeholder = "What's your favourite channel?",
            defaultChannels = {0123456789L, 9876543210L}
)
public void onMenu(ComponentEvent event, Mentions mentions) { ... }

Min & Max Value¶

Just as for String Select Menus you can set the minimum and maximum value by using the minValue and maxValue fields.