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