From cd063d672a735ad2e95681f25c95f591d147b7e3 Mon Sep 17 00:00:00 2001 From: LordOfPolls Date: Thu, 17 Jun 2021 10:03:15 +0100 Subject: [PATCH 1/8] add component tutorial --- docs/components.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 76 insertions(+) create mode 100644 docs/components.rst diff --git a/docs/components.rst b/docs/components.rst new file mode 100644 index 000000000..d676c2adb --- /dev/null +++ b/docs/components.rst @@ -0,0 +1,75 @@ +How to use components +===================== + + +So you've seen the new fancy buttons and want to give them a try, but dont know where to start. No problem! + +First lets cover the basics. Discord messages can have *components*, such as buttons, dropdowns etc. These components sit in whats called an "action row". An action row can hold 5 components at a time. Your message can have 5 action rows, so thats a total of 25 components! + +Sending some components +_______________________ + +First we need to create some buttons, lets put them in a list for now. We'll use :meth:`create_button() ` to create a green button + +.. code-block:: python + + from discord_slash.utils import manage_components + from discord_slash.model import ButtonStyle + + buttons = [ + manage_components.create_button( + style=ButtonStyle.green, + label="A Green Button" + ) + ] + +So we have a button, but where do we use it. Let's create an action row with :meth:`create_actionrow() ` and put our buttons in it + +.. code-block:: python + + [...] + action_row = manage_components.create_actionrow(*buttons) + + +Fantastic, we now have an action row with a green button in it, now lets get it sent in discord + +.. code-block:: python + + await ctx.send("My Message", components=[action_row]) + +Now if you've followed along, you have a green button in discord! But theres a problem, whenever you click it you see that the ``interaction failed``. Why is that? +Well, in Discord, clicking buttons and using slash commands are called ``interactions``, and Discord doesn't know if we've received them or not unless we tell Discord. So how do we do that? + +Responding to interactions +__________________________ + +When responding to interactions, we have 2 choices, either to do it in the command itself, or a global event handler (like :meth:`on_slash_command_error`) + +Lets go through the most common method first, responding in the event itself. We simply need to :meth:`wait_for` the event, just like you do for reactions. For this we're going to use :meth:`wait_for_component() `, and we're going to only wait for events from the action row we just . +This method will return a :class:`ComponentContext ` object that we can use to respond. For this example, we'll just edit the original message (:meth:`edit_origin() `) + +.. code-block:: python + + await ctx.send("My Message", components=[action_row]) + button_ctx: ComponentContext = await manage_components.wait_for_component(bot, action_row) + await button_ctx.edit_origin(content="You pressed a button!") + +.. note:: It's worth being aware that if you handle the event in the command itself, it will not persist reboots. As such when you restart the bot, the interaction will fail + +Next we'll go over the alternative, a global event handler. This works just the same as :meth:`on_slash_command_error` or `on_ready`. + +.. code-block:: python + + @bot.event + async def on_component(ctx: ComponentContext): + await button_ctx.edit_origin(content="You pressed a button!") + +But [writer], I dont want to edit the message +********************************************* + +Well lucky for you, you don't have to. You can either respond silently, with a thinking animation, or send a whole new message. Take a look here: :class:`ComponentContext ` + +How do i know which button was pressed? +_______________________________________ + +Each button gets a ``custom_id``, this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button. When handling the event, simply check the custom_id, and handle accordingly. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 6b7e3d545..473992da5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,7 @@ feel free to reach out to others on the `Discord`_! quickstart.rst gettingstarted.rst migration.rst + components.rst discord_slash.rst events.rst discord_slash.utils.rst From 5211c1b12121b248092376ce5acdbc29c36928cb Mon Sep 17 00:00:00 2001 From: LordOfPolls Date: Fri, 18 Jun 2021 09:30:59 +0100 Subject: [PATCH 2/8] mention that this only handles one press --- docs/components.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/components.rst b/docs/components.rst index d676c2adb..a2248dcee 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -51,6 +51,7 @@ This method will return a :class:`ComponentContext Date: Fri, 18 Jun 2021 09:31:23 +0100 Subject: [PATCH 3/8] add link to components in gettingstarted.rst --- docs/gettingstarted.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 707d1e5fb..dfcb00847 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -311,7 +311,12 @@ command as show in the following example: async def test(ctx): await ctx.send(content="Hello World!") -.. _quickstart: https://discord-py-slash-command.readthedocs.io/en/latest/quickstart.html +But what about buttons? +----------------------- +This library supports components (buttons, actionrows, selects, etc.). Take a look here: `components`_. + +.. _quickstart: quickstart.html +.. _components: components.html .. _ApplicationCommandOptionType: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptiontype .. _ApplicationCommandOptionChoice: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptionchoice .. _ApplicationCommandOption: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoption From 52887db3b56e63b656e7fc18f97ae8da3e73efc2 Mon Sep 17 00:00:00 2001 From: LordOfPolls <22540825+LordOfPolls@users.noreply.github.com> Date: Fri, 18 Jun 2021 14:54:14 +0100 Subject: [PATCH 4/8] meth -> func Co-authored-by: artem30801 <38689676+artem30801@users.noreply.github.com> --- docs/components.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components.rst b/docs/components.rst index a2248dcee..c8f4e801e 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -45,7 +45,7 @@ __________________________ When responding to interactions, we have 2 choices, either to do it in the command itself, or a global event handler (like :meth:`on_slash_command_error`) -Lets go through the most common method first, responding in the event itself. We simply need to :meth:`wait_for` the event, just like you do for reactions. For this we're going to use :meth:`wait_for_component() `, and we're going to only wait for events from the action row we just . +Lets go through the most common method first, responding in the event itself. We simply need to :meth:`wait_for` the event, just like you do for reactions. For this we're going to use :func:`wait_for_component() `, and we're going to only wait for events from the action row we just . This method will return a :class:`ComponentContext ` object that we can use to respond. For this example, we'll just edit the original message (:meth:`edit_origin() `) .. code-block:: python @@ -73,4 +73,4 @@ Well lucky for you, you don't have to. You can either respond silently, with a t How do i know which button was pressed? _______________________________________ -Each button gets a ``custom_id``, this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button. When handling the event, simply check the custom_id, and handle accordingly. \ No newline at end of file +Each button gets a ``custom_id``, this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button. When handling the event, simply check the custom_id, and handle accordingly. From 5064d144e8ca48088effe80873eacd5700caf3d5 Mon Sep 17 00:00:00 2001 From: LordOfPolls <22540825+LordOfPolls@users.noreply.github.com> Date: Fri, 18 Jun 2021 14:54:23 +0100 Subject: [PATCH 5/8] meth -> func Co-authored-by: artem30801 <38689676+artem30801@users.noreply.github.com> --- docs/components.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components.rst b/docs/components.rst index c8f4e801e..5a4f12449 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -23,7 +23,7 @@ First we need to create some buttons, lets put them in a list for now. We'll use ) ] -So we have a button, but where do we use it. Let's create an action row with :meth:`create_actionrow() ` and put our buttons in it +So we have a button, but where do we use it. Let's create an action row with :func:`create_actionrow() ` and put our buttons in it .. code-block:: python From 2c18bd8a4ec67b51a558282841e78c1608a8bab0 Mon Sep 17 00:00:00 2001 From: LordOfPolls <22540825+LordOfPolls@users.noreply.github.com> Date: Fri, 18 Jun 2021 14:54:41 +0100 Subject: [PATCH 6/8] comma for easier copying Co-authored-by: artem30801 <38689676+artem30801@users.noreply.github.com> --- docs/components.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components.rst b/docs/components.rst index 5a4f12449..908d9e3aa 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -20,7 +20,7 @@ First we need to create some buttons, lets put them in a list for now. We'll use manage_components.create_button( style=ButtonStyle.green, label="A Green Button" - ) + ), ] So we have a button, but where do we use it. Let's create an action row with :func:`create_actionrow() ` and put our buttons in it From 9eec9b8811caf3ab3a704ce470f0ea07c1eed01a Mon Sep 17 00:00:00 2001 From: LordOfPolls Date: Fri, 18 Jun 2021 15:12:07 +0100 Subject: [PATCH 7/8] changes based on feedback Added info about random `custom_id` Added note about working in both slash and dpy --- docs/components.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/components.rst b/docs/components.rst index 908d9e3aa..ce39159dd 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -37,6 +37,8 @@ Fantastic, we now have an action row with a green button in it, now lets get it await ctx.send("My Message", components=[action_row]) +.. note:: This will work in both slash commands, and discord.py commands + Now if you've followed along, you have a green button in discord! But theres a problem, whenever you click it you see that the ``interaction failed``. Why is that? Well, in Discord, clicking buttons and using slash commands are called ``interactions``, and Discord doesn't know if we've received them or not unless we tell Discord. So how do we do that? @@ -73,4 +75,4 @@ Well lucky for you, you don't have to. You can either respond silently, with a t How do i know which button was pressed? _______________________________________ -Each button gets a ``custom_id``, this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button. When handling the event, simply check the custom_id, and handle accordingly. +Each button gets a ``custom_id``, this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button, if you don't; a random one will be generated. When handling the event, simply check the custom_id, and handle accordingly. From 7bf8fe857c3cc59d03e4fcd185b3c7bc0b3ab72e Mon Sep 17 00:00:00 2001 From: LordOfPolls Date: Fri, 18 Jun 2021 15:14:28 +0100 Subject: [PATCH 8/8] update responding brief --- docs/components.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components.rst b/docs/components.rst index ce39159dd..57ea5c33e 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -45,7 +45,7 @@ Well, in Discord, clicking buttons and using slash commands are called ``interac Responding to interactions __________________________ -When responding to interactions, we have 2 choices, either to do it in the command itself, or a global event handler (like :meth:`on_slash_command_error`) +When responding, you have 2 choices in how you handle interactions. You can either wait for them in the command itself, or listen for them in a global event handler (similar to :meth:`on_slash_command_error`) Lets go through the most common method first, responding in the event itself. We simply need to :meth:`wait_for` the event, just like you do for reactions. For this we're going to use :func:`wait_for_component() `, and we're going to only wait for events from the action row we just . This method will return a :class:`ComponentContext ` object that we can use to respond. For this example, we'll just edit the original message (:meth:`edit_origin() `)