reference,learn: start moving custom interactions to learn

Signed-off-by: Luca Zeuch <[email protected]>

Author: l-zeuch

content/learn/advanced/_index.md

@@ -0,0 +1,4 @@
++++
+title = "Advanced"
+weight = 400
++++

content/learn/advanced/custom-interactions/_index.md

@@ -0,0 +1,4 @@
++++
+title = "Custom Interactions"
+weight = 410
++++

content/learn/advanced/custom-interactions/basic_button.png

@@ -0,0 +1,97 @@
++++
+title = "Creating Interactive Elements"
+weight = 412
++++
+
+Before you can start triggering custom commands with interactive elements---such as buttons---you'll obviously need
+to have elements to interact with. In this section, we'll cover how to create these elements and then make them usable
+to trigger custom commands.
+
+## Message Components
+
+### Buttons
+
+Buttons are probably the simplest interactive element to create, so we'll start with them. To create a button, we use
+the [`cbutton`](docs/reference/templates/functions#cbutton) function. In and of itself, that is rather useless, so we'll
+also have to attach it to a message. We do that by calling the
+[`complexMessage`](docs/reference/templates/functions#complexmessage) builder and adding the result of `cbutton` to it.
+Finally, we send the message.
+
+```yag
+{{ $button := cbutton "label" "My Cool Button" "custom-id" "buttons-duck" }}
+{{ $m := complexMessage "buttons" $button }}
+{{ sendMessage nil $m }}
+```
+
+Result:
+
+![A basic button, sent with the above code.](basic_button.png)
+
+We've successfully crated a basic button! It doesn't do anything yet, but we'll cover that in a later section.
+In the meantime, play around with the values `cbutton` takes. Try to attach an emoji to it, or change its style!
+
+### Select Menus
+
+Select menus act as dropdowns, allowing users to select one or more of several options. To further complicate things,
+select menus come in different types, each offering different functionality. We'll first focus on the most intuitive
+type, the **Text** select menu. This type allows you to define a custom list of options.
+
+Available select menu types are as follows:
+
+- **Text** - The options available to be selected are defined when creating the select menu. Options have labels, and
+  can optionally have emojis and longer-form descriptions.
+- **User** - The options are populated with users on the server by Discord.
+- **Role** - The options are populated with roles on the server by Discord.
+- **Mentionable** - The options are auto-populated with both users and roles on the server by Discord, allowing members
+  to select both.
+- **Channel** - The options are populated with channels on the server by Discord. You can limit which channel types
+  appear as options when creating the select menu.
+
+#### Text Select Menus
+
+To create a text select menu, we use the [`cmenu`](docs/reference/templates/functions#cmenu) function. Then, just like
+with a button, we attach it to a message and send it.
+
+```yag
+{{ $menu := cmenu
+  "type" "text"
+  "placeholder" "Choose a terrible thing"
+  "custom_id" "menus-duck"
+  "options" (cslice
+    (sdict "label" "Two Ducks" "value" "opt-1" "default" true)
+    (sdict "label" "A Duck" "value" "duck-option" "emoji" (sdict "name" "🦆"))
+    (sdict "label" "Half a Duck" "value" "third-option" "description" "Don't let the smaller amount fool you."))
+  "max_values" 3
+}}
+
+{{ sendMessage nil (complexMessage "menus" $menu) }}
+```
+
+Opening the select menu that was sent using the above code should yield the following result:
+
+![A Photo of the above menu](text_menu_example.png)
+
+In this menu, our first option (Ducks) is defined as `default`, which is why it is already selected when we look at the
+menu on our server. You can define multiple default options, however the amount of default options you define must fall
+between your `min_values` and `max_values`.
+
+We have also set the `max_values` to 3, and we haven't set a `min_values` argument. This means the server member could
+select anywhere between 1 and 3 of these options.
+
+#### Other Select Menu Types
+
+The other select menu types are created in the same way as the text select menu, but with a few differences. As Discord
+automatically populates the options, you need not---nor can you---define these options.
+
+```yag
+{{ $menu := cmenu
+  "type" "role"
+  "placeholder" "Choose roles who are secretly ducks"
+  "custom_id" "menus-duck-roles"
+  "max_values" 3
+}}
+
+{{ sendMessage nil (complexMessage "menus" $menu) }}
+```
+
+![A photo of the above role select menu.](role_select_menu_example.png)

content/learn/advanced/custom-interactions/creating-elements.md

@@ -0,0 +1,91 @@
++++
+title = "Introduction"
+weight = 411
+description = "Learn how to use buttons, modals, and select menus in custom commnads."
++++
+
+{{< callout context="danger" title="Danger: Advanced Topic" icon="outline/alert-octagon" >}}
+
+Use of interactions within YAGPDB is an advanced topic; you will need a thorough understanding of YAGPDB's scripting
+language before learning interactions.
+
+{{< /callout >}}
+
+Interactions within Discord allow server members to use alternative, built-in features to trigger bots to take action
+other than messages or reactions. These features include builtin buttons, dropdown selection menus, or submitting a
+modal (basically a pop-up form). Within custom commands it is possible to not only create and customize these new
+interactive features, but respond to them as well, opening up new possibilities for ephemeral message responses, modals,
+and more within custom commands.
+
+## Interaction Lifetime
+
+An interaction's lifetime starts with the initial *interaction* with an *interactive element*.
+
+1. A server member clicks on a *button*, uses a *menu*, or submits a *modal* after filling it out.
+2. This interaction is sent to YAGPDB, and becomes available to trigger any custom commands which match it.
+3. Within the triggered custom command(s), YAGPDB should then *respond* once to the interaction, sending a message,
+   updating the triggering message, or sending a modal. This may only be done within the CC which was triggered by the
+   interaction.
+4. (optional) Continue to send followup responses for up to 15 minutes until the interaction token expires.
+
+```mermaid
+graph LR;
+A[Button pressed] --> B{CC Triggered}
+C[Menu used] --> B
+D[Modal submitted] --> B
+B --> E[Bot sends message response]
+B --> G[Bot sends modal response]
+B --> H[Bot updates message]
+E -.-> F(Bot sends followups)
+G -.-> F
+H -.-> F
+```
+
+## Definitions
+
+On the following pages, we will the listed terms with their respective definitions, which are also used by the Discord
+API.
+
+Interaction
+: A user engaging with YAGPDB through one of Discord's builtin features: Clicking a button, Making a
+selection with a select menu, or Submitting a modal.
+
+Response
+: YAGPDB is required to respond promptly after receiving an interaction by either sending a message or modal, or by
+updating the message on which the interaction was triggered. If it does not do this, the user triggering the interaction
+will see a "This application did not respond" error. The bot cannot respond to an interaction more than once.
+
+Followup
+: Since YAGPDB may only *respond* to an *interaction* once, it is subsequently required to send an interaction
+followup if it still needs to interface with the interaction. These followups can be sent up to 15 minutes after the initial
+interaction, and you can send as many as you want. YAGPDB may only send a followup in one of the following ways: Sending
+a followup message, editing an initial response or previous followup message, or getting an initial response or previous
+followup message.
+
+Interactive Elements
+: Elements users can interact with to send *interactions*, i.e. buttons, menus, and modals.
+
+Message Components
+: *Interactive Elements* which can be attached to YAGPDB's Discord messages, i.e. buttons and menus.
+
+Button
+: A button appearing in or under a Discord message sent by YAGPDB. You can create and customize these
+buttons' appearance and behavior with color, emoji, label text, etc. When a button is clicked, an *interaction* is sent
+to the bot.
+
+Menu
+: A dropdown select menu appearing in or under a Discord message sent by YAGPDB. You can create and customize these
+menus' appearance and behavior with placeholder text, predefined options with labels, descriptions, and/or emojis,
+designate the entire menu as a user or role select menu instead, etc. When a select menu is used, an *interaction* is
+sent to the bot.
+
+Modal
+: A pop-up form YAGPDB can send in response to an interaction. It allows users to privately input text which
+is sent directly to YAGPDB for use in CC scripting. You can create and customize these modals' appearance and
+behavior with a title and fields. YAGPDB can both **receive a submitted modal** (which is an
+*interaction*), and **send a modal** for a member to fill out, (which is an interaction *response*).
+
+Ephemeral
+: An ephemeral message is sent to a server channel but only appears to a single user. YAGPDB cannot send
+these ephemeral messages to users except in response to an *interaction*. Both *response* messages and *followup*
+messages can be ephemeral.