218 lines
16 KiB
ReStructuredText
218 lines
16 KiB
ReStructuredText
==================
|
|
Message Components
|
|
==================
|
|
|
|
|
|
Message components are new components you can add to messages, such as buttons and select menus. There are currently four different types of message components:
|
|
|
|
``ActionRow``
|
|
=============
|
|
|
|
Represents a row of buttons on a message. You can add up to 5 buttons to the row, which can then be added to the message. You can only add buttons to action rows.
|
|
|
|
.. code:: php
|
|
|
|
$row = ActionRow::new()
|
|
->addComponent(Button::new(Button::STYLE_SUCCESS));
|
|
|
|
Functions
|
|
---------
|
|
|
|
+----------------------------------+-------------------------------------------------------------+
|
|
| name | description |
|
|
+==================================+=============================================================+
|
|
| ``addComponent($component)`` | adds a component to action row. must be a button component. |
|
|
+----------------------------------+-------------------------------------------------------------+
|
|
| ``removeComponent($component)`` | removes the given component from the action row. |
|
|
+----------------------------------+-------------------------------------------------------------+
|
|
| ``getComponents(): Component[]`` | returns all the action row components in an array. |
|
|
+----------------------------------+-------------------------------------------------------------+
|
|
|
|
``Button``
|
|
==========
|
|
|
|
Represents a button attached to a message. You cannot directly attach a button to a message, it must be contained inside an ``ActionRow``.
|
|
|
|
.. code:: php
|
|
|
|
$button = Button::new(Button::STYLE_SUCCESS)
|
|
->setLabel('push me!');
|
|
|
|
There are 5 different button styles:
|
|
|
|
========= =========================== =======
|
|
name constant colour
|
|
========= =========================== =======
|
|
primary ``Button::STYLE_PRIMARY`` blurple
|
|
secondary ``Button::STYLE_SECONDARY`` grey
|
|
success ``Button::STYLE_SUCCESS`` green
|
|
danger ``Button::STYLE_DANGER`` red
|
|
link ``Button::STYLE_LINK`` grey
|
|
========= =========================== =======
|
|
|
|
.. image:: https://discord.com/assets/7bb017ce52cfd6575e21c058feb3883b.png
|
|
:alt: Discord button styles
|
|
|
|
Discord button styles
|
|
|
|
.. _functions-1:
|
|
|
|
Functions
|
|
---------
|
|
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| name | description |
|
|
+======================================+==========================================================================================================================================+
|
|
| ``setStyle($style)`` | sets the style of the button. must be one of the above constants. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setLabel($label)`` | sets the label of the button. maximum 80 characters. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setEmoji($emoji)`` | sets the emoji for the button. must be an ``Emoji`` object. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setCustomId($custom_id)`` | sets the custom ID of the button. maximum 100 characters. will be automatically generated if left null. not applicable for link buttons. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setUrl($url)`` | sets the url of the button. only for buttons with the ``Button::STYLE_LINK`` style. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setDisabled($disabled)`` | sets whether the button is disabled or not. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setListener($listener, $discord)`` | sets the listener for the button. see below for more information. not applicable for link buttons. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| ``removeListener()`` | removes the listener from the button. |
|
|
+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Adding a button listener
|
|
------------------------
|
|
|
|
If you add a button you probably want to listen for when it is clicked. This is done through the ``setListener(callable $listener, Discord $discord)`` function.
|
|
|
|
The ``callable $listener`` will be a function which is called with the ``Interaction`` object that triggered the button press. You must also pass the function the ``$discord`` client.
|
|
|
|
.. code:: php
|
|
|
|
$button->setListener(function (Interaction $interaction) {
|
|
$interaction->respondWithMessage(MessageBuilder::new()
|
|
->setContent('why\'d u push me?'));
|
|
}, $discord);
|
|
|
|
If the interaction is not responded to after the function is called, the interaction will be automatically acknowledged with no response. If you are going to acknowledge the interaction after a delay (e.g. HTTP request, arbitrary timeout) you should return a promise from the listener to prevent the automatic acknowledgement:
|
|
|
|
.. code:: php
|
|
|
|
$button->setListener(function (Interaction $interaction) use ($discord) {
|
|
return someFunctionWhichWillReturnAPromise()->then(function ($returnValueFromFunction) use ($interaction) {
|
|
$interaction->respondWithMessage(MessageBuilder::new()
|
|
->setContent($returnValueFromFunction));
|
|
});
|
|
}, $discord);
|
|
|
|
``SelectMenu``
|
|
==============
|
|
|
|
Select menus are a dropdown which can be attached to a message. They operate similar to buttons. They do not need to be attached to an ``ActionRow``. You may have up to 25 ``Option``\ s attached to a select menu.
|
|
|
|
.. code:: php
|
|
|
|
$select = SelectMenu::new()
|
|
->addOption(Option::new('me?'))
|
|
->addOption(Option::new('or me?'));
|
|
|
|
.. _functions-2:
|
|
|
|
Functions
|
|
---------
|
|
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| name | description |
|
|
+======================================+========================================================================================================+
|
|
| ``addOption($option)`` | adds an option to the select menu. maximum 25 options per menu. options must have unique values. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``removeOption($option)`` | removes an option from the select menu. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``setPlaceholder($placeholder)`` | sets a placeholder string to be displayed when nothing is selected. null to clear. max 150 characters. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``setMinValues($min_values)`` | the number of values which must be selected to submit the menu. between 0 and 25, default 1. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``setMaxValues($max_values)`` | the maximum number of values which can be selected. maximum 25, default 1. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``setDisabled($disabled)`` | sets whether the menu is disabled or not. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``setListener($listener, $discord)`` | sets the listener for the select menu. see below for more information. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
| ``removeListener()`` | removes the listener from the select menu. |
|
|
+--------------------------------------+--------------------------------------------------------------------------------------------------------+
|
|
|
|
``Option`` functions
|
|
--------------------
|
|
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
| name | description |
|
|
+==================================+===========================================================================================================================+
|
|
| ``new($label, ?$value)`` | creates a new option. requires a label to display, and optionally an internal value (leave as null to auto-generate one). |
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setDescription($description)`` | sets the description of the option. null to clear. maximum 100 characters. |
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setEmoji($emoji)`` | sets the emoji of the option. null to clear. must be an emoji object. |
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
| ``setDefault($default)`` | sets whether the option is the default option. |
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
| ``getValue()`` | gets the internal developer value of the option. |
|
|
+----------------------------------+---------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Adding a select menu listener
|
|
-----------------------------
|
|
|
|
Select menu listeners operate similar to the button listeners, so please read the above section first. The callback function will be called with the ``Interaction`` object as well as a collection of selected ``Option``\ s.
|
|
|
|
.. code:: php
|
|
|
|
$select->setListener(function (Interaction $interaction, Collection $options) {
|
|
foreach ($options as $option) {
|
|
echo $option->getValue().PHP_EOL;
|
|
}
|
|
|
|
$interaction->respondWithMessage(MessageBuilder::new()->setContent('thanks!'));
|
|
}, $discord);
|
|
|
|
``TextInput``
|
|
=============
|
|
|
|
Text inputs are an interactive component that render on modals.
|
|
|
|
.. code:: php
|
|
|
|
$textInput = TextInput::new('Label', TextInput::TYPE_SHORT, 'custom id')
|
|
->setRequired(true);
|
|
|
|
They can be used to collect short-form or long-form text:
|
|
|
|
====================== ==============================
|
|
style constant
|
|
====================== ==============================
|
|
Short (single line) ``TextInput::STYLE_SHORT``
|
|
Paragraph (multi line) ``TextInput::STYLE_PARAGRAPH``
|
|
====================== ==============================
|
|
|
|
.. _functions-3:
|
|
|
|
Functions
|
|
---------
|
|
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| name | description |
|
|
+==================================+=============================================================================================================+
|
|
| ``setCustomId($custom_id)`` | sets the custom ID of the text input. maximum 100 characters. will be automatically generated if left null. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setStyle($style)`` | sets the style of the text input. must be one of the above constants. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setLabel($label)`` | sets the label of the button. maximum 80 characters. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setMinLength($min_length)`` | the minimum length of value. between 0 and 4000, default 0. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setMaxLength($max_length)`` | the maximum length of value. between 1 and 4000, default 4000. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setValue($value)`` | sets a pre-filled value for the text input. maximum 4000 characters. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setPlaceholder($placeholder)`` | sets a placeholder string to be displayed when text input is empty. max 100 characters. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+
|
|
| ``setRequired($required)`` | sets whether the text input is required or not. |
|
|
+----------------------------------+-------------------------------------------------------------------------------------------------------------+ |