Skip to content

Commit 9df39fb

Browse files
l-zeuchl-zeuch
committed
docs: migrate interaction section to header format
Signed-off-by: Luca Zeuch <[email protected]>
1 parent 959e195 commit 9df39fb

File tree

1 file changed

+188
-69
lines changed

1 file changed

+188
-69
lines changed

‎content/docs/reference/templates/functions.md‎

Lines changed: 188 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -408,11 +408,69 @@ about using interactions, [see here](/docs/reference/custom-interactions).
408408
- A CC executed with `execCC` by the triggered CC will be able to send initial responses to the triggering interaction.
409409
- A response is not the same thing as a followup.
410410

411-
| **Function** | **Description** |
412-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
413-
| `sendModal` modal | Responds to an interaction by showing the member a modal. `modal` must be an `sdict` with the following keys: `title`, `custom_id`, and `fields`. The `fields` argument should be a slice of sdicts with the following keys: `label`, `placeholder`, `value` (default value if they don't enter anything), `required`, `style` (1 for short, 2 for long), `min_length`, and `max_length`, however only the `label` argument is required for each field. You cannot send a modal in response to a user submitting another modal. Example in section's [Snippets](#interactions-sections-snippets). |
414-
| `updateMessage` newMessage | Edits the message on which the button, select menu, or modal was triggered on. |
415-
| `updateMessageNoEscape` newMessage | Edits the message triggered on and has same logic in escaping characters as `sendMessageNoEscape`. |
411+
### sendModal
412+
413+
```yag
414+
{{ sendModal <modal> }}
415+
```
416+
417+
Sends a modal to the member who triggered the interaction.
418+
419+
- `modal`: an sdict with the following keys:
420+
- `title`: the title of the modal.
421+
- `custom_id`: a unique identifier for the modal.
422+
- `fields`: a slice of sdicts with the following keys:
423+
- `label`: the label for the field.
424+
- `placeholder`: the placeholder text for the field.
425+
- `value`: the default value for the field.
426+
- `required`: whether the field is required.
427+
- `style`: the style of the field (1 for short, 2 for long).
428+
- `min_length`: the minimum length of the field.
429+
- `max_length`: the maximum length of the field.
430+
431+
#### Example
432+
433+
```yag
434+
{{ $modal := sdict
435+
"title" "My Custom Modal"
436+
"custom_id" "modals-my_first_modal"
437+
"fields" (cslice
438+
(sdict "label" "Name" "placeholder" "Duck" "required" true)
439+
(sdict "label" "Do you like ducks?" "value" "Heck no")
440+
(sdict "label" "Duck hate essay" "min_length" 100 "style")) }}
441+
{{ sendModal $modal }}
442+
```
443+
444+
### updateMessage
445+
446+
```yag
447+
{{ updateMessage <newMessage> }}
448+
```
449+
450+
Edits the message on which the button, select menu, or modal was triggered on.
451+
452+
- `newMessage`: the new message content. May be a string, an embed, or a complex message.
453+
454+
#### Example
455+
456+
The following example must be triggered by a component or modal submission.
457+
458+
```yag
459+
{{ $button := cbutton "label" "I won!" "custom_id" "i_won" }}
460+
{{ $content := printf "Press this button when you win! The last person who won was %s! They wanted to say they are a %s %s." .User.Mention adjective noun }}
461+
462+
{{ $message := complexMessageEdit "content" $content "buttons" $button }}
463+
{{ updateMessage $message }}
464+
```
465+
466+
467+
### updateMessageNoEscape
468+
469+
```yag
470+
{{ updateMessageNoEscape <newMessage> }}
471+
```
472+
473+
Same as [updateMessage](#updatemessage), plus it does not escape mentions.
416474

417475
### Interaction Followups
418476

@@ -423,96 +481,157 @@ about using interactions, [see here](/docs/reference/custom-interactions).
423481
already been responded to.
424482
- A followup is not the same thing as a response.
425483

426-
| **Function** | **Description** |
427-
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
428-
| `editResponse` interactionToken messageID newMessageContent | Edits one of the bot's responses to an interaction. `interactionToken` must be a valid token or `nil` to target the triggering interaction. `messageID` must be a valid message ID of a followup message, or `nil` to target the original interaction response. Example in section's [Snippets](#interactions-sections-snippets). |
429-
| `editResponseNoEscape` interactionToken messageID newMessageContent | Edits the response and has same logic in escaping characters as `sendMessageNoEscape`. |
484+
### editResponse
485+
486+
```yag
487+
{{ editResponse <interactionToken> <messageID> <newContent> }}
488+
```
489+
490+
Edits a response to an interaction.
491+
492+
- `interactionToken`: the token of the interaction to edit. `nil` for the triggering interaction.
493+
- `messageID`: the ID of a follow-up message. `nil` for the original interaction response.
494+
- `newContent`: the new content for the message.
495+
496+
#### Example
497+
498+
The following example must be triggered by a component trigger or modal submission.
499+
500+
```yag
501+
{{ $token := .Interaction.Token }}
502+
503+
{{ sendResponse nil "Here's the first message!" }}
504+
{{ $id := sendResponseRetID $token (complexMessage "content" "Here's a sneaky one!" "ephemeral" true) }}
505+
506+
{{ sleep 2 }}
507+
508+
{{ editResponse $token $id (print "I've edited this message to say " noun) }}
509+
{{ $editedResponse := getResponse $token $id }}
510+
{{ editResponse $token nil $editedResponse.Content }}
511+
```
512+
513+
### editResponseNoEscape
514+
515+
```yag
516+
{{ editResponseNoEscape <interactionToken> <messageID> <newContent> }}
517+
```
518+
519+
Same as [editResponse](#editresponse), plus it does not escape mentions.
430520

431521
### Interaction Response/Followup Hybrids
432522

433-
- Hybrid functions will send an interaction response if the interaction has not already been responded to, otherwise they will send the equivalent followup function.
523+
Hybrid functions will send an interaction response if the interaction has not already been responded to, otherwise
524+
they will send the equivalent followup function. See [editResponse](#editresponse) for an example using
525+
`sendResponse*` functions.
434526

435-
| **Function** | **Description** |
436-
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
437-
| `sendResponse` interactionToken message | Sends a message (string, embed, or complexMessage) in response to an interaction. Supports the `ephemeral` flag in `complexMessage`. `interactionToken` must be a valid token or `nil` to target the triggering interaction. Example in section's [Snippets](#interactions-sections-snippets). |
438-
| `sendResponseNoEscape` interactionToken message | Sends a message as a response, and doesn't escape mentions (e.g. role mentions, reply mentions or @here/@everyone). |
439-
| `sendResponseNoEscapeRetID` interactionToken message | Same as `sendResponseNoEscape`, but also returns messageID to assigned variable for later use. |
440-
| `sendResponseRetID` interactionToken message | Same as `sendResponse`, but also returns messageID to assigned variable for later use. Example in section's [Snippets](#interactions-sections-snippets). |
527+
### sendResponse
528+
529+
```yag
530+
{{ sendResponse <interactionToken> <message> }}
531+
```
532+
533+
Sends a message in response to an interaction. Supports the `ephemeral` flag in `complexMessage`.
534+
535+
### sendResponseNoEscape
536+
537+
```yag
538+
{{ sendResponseNoEscape <interactionToken> <message> }}
539+
```
540+
541+
Same as [sendResponse](#sendresponse), plus it does not escape mentions.
542+
543+
### sendResponseNoEscapeRetID
544+
545+
```yag
546+
{{ sendResponseNoEscapeRetID <interactionToken> <message> }}
547+
```
548+
549+
Same as [sendResponseNoEscape](#sendresponsenoescape), but also returns the message ID.
550+
551+
### sendResponseRetID
552+
553+
```yag
554+
{{ sendResponseRetID <interactionToken> <message> }}
555+
```
556+
557+
Same as [sendResponse](#sendresponse), but also returns the message ID.
441558

442559
### Interaction Miscellaneous
443560

444-
| **Function** | **Description** |
445-
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
446-
| `cbutton` "list of button values" | Functions similarly to `cembed`. [Available values](https://discord.com/developers/docs/interactions/message-components#button-object) A Link style button must have a URL and cannot have a Custom ID. All other styles must have a Custom ID and cannot have a URL. All buttons must have either a label or an emoji. Example in section's [Snippets](#interactions-sections-snippets). |
447-
| `cmenu` "list of select menu values" | Functions similarly to `cembed`. [Available values](https://discord.com/developers/docs/interactions/message-components#select-menu-object) Type should be provided as a string, either `"text"`, `"user"`, `"role"`, `"mentionable"`, or `"channel"`. Text type menus must have `options`, all other types cannot. Example in section's [Snippets](#interactions-sections-snippets). |
448-
| `ephemeralResponse` | Send the response text ephemerally. Only works when triggered by an interaction. Works on responses and followups. |
449-
| `getResponse` interactionToken messageID | Can be used to get the bot's responses or followup messages, including ephemeral messages. Returns a [Message](/docs/reference/templates/syntax-and-data#message) object. `interactionToken` must be a valid token or `nil` to target the triggering interaction. `messageID` must be a valid message ID of a followup message, or `nil` to target the original interaction response. Example in section's [Snippets](#interactions-sections-snippets). |
450-
451-
### Interactions section's snippets
452-
453-
- To demonstrate creating buttons and menus
454-
455-
```yag
456-
{{ $funButton := cbutton
457-
"label" "My Custom Button"
458-
"custom_id" "duck-button"
459-
"style" "success" }}
460-
{{ $badButton := cbutton
461-
"label" "My Useless Button"
462-
"style" "secondary"
463-
"disabled" true }}
464-
{{ $emojiButton := cbutton
465-
"emoji" ( sdict "name" "🦆" )
466-
"style" "link"
467-
"url" "https://yagpdb.xyz" }}
561+
### cbutton
562+
563+
```yag
564+
{{ $button := cbutton "list of button values" }}
565+
```
566+
567+
Creates a [button object](https://discord.com/developers/docs/interactions/message-components#button-object) for use in
568+
interactions.
569+
570+
A link style button *must* have a URL and may not have a Custom ID. All other styles *must* have a Custom ID and cannot
571+
have a URL. All buttons must have either a label or an emoji.
572+
573+
#### Example
574+
575+
```yag
576+
{{ $button := cbutton "label" "Button" "custom_id" "buttons-duck" }}
577+
{{ $message := complexMessage "buttons" $button }}
578+
{{ sendMessage nil $message }}
579+
```
580+
581+
### cmenu
582+
583+
```yag
584+
{{ $menu := cmenu "list of select menu values" }}
585+
```
586+
587+
Creates a [select menu object](https://discord.com/developers/docs/interactions/message-components#select-menu-object)
588+
for use in interactions.
589+
590+
The type should be provided as a string: `"text"`, `"user"`, `"role"`, `"mentionable"`, or `"channel"`. Text type menus
591+
*must* have `options`, while all other types cannot.
592+
593+
#### Example
594+
595+
```yag
468596
{{ $menu := cmenu
469597
"type" "text"
470598
"placeholder" "Choose a terrible thing"
471-
"custom_id" "duck-menus-my_first_menu"
599+
"custom_id" "menus-duck"
472600
"options" (cslice
473-
(sdict "label" "Ducks" "value" "opt-1" "default" true)
474-
(sdict "label" "Duck" "value" "opt-2" "emoji" (sdict "name" "🦆"))
475-
(sdict "label" "Half a Duck" "value" "opt-3" "description" "Don't let the smaller amount fool you."))
601+
(sdict "label" "Two Ducks" "value" "opt-1" "default" true)
602+
(sdict "label" "A Duck" "value" "duck-option" "emoji" (sdict "name" "🦆"))
603+
(sdict "label" "Half a Duck" "value" "third-option" "description" "Don't let the smaller amount fool you."))
476604
"max_values" 3 }}
477-
{{ $message := complexMessage "buttons" (cslice $funButton $badButton $emojiButton) "menus" $menu }}
478-
{{ sendMessage nil $message }}
605+
606+
{{ sendMessage nil (complexMessage "menus" $menu) }}
479607
```
480608

481-
- To demonstrate responding with a modal (this must be triggered by a component or modal submission)
609+
### ephemeralResponse
482610

483611
```yag
484-
{{ $modal := sdict
485-
"title" "My Custom Modal"
486-
"custom_id" "modals-my_first_modal"
487-
"fields" (cslice
488-
(sdict "label" "Name" "placeholder" "Duck" "required" true)
489-
(sdict "label" "Do you like ducks?" "value" "Heck no")
490-
(sdict "label" "Duck hate essay" "min_length" 100)) }}
491-
{{ sendModal $modal }}
612+
{{ ephemeralResponse }}
492613
```
493614

494-
- To demonstrate sending, getting, and editing responses (this must be triggered by a component or modal submission)
615+
Tells the bot to send the response text as an ephemeral message. Only works when triggered by an interaction. Works on
616+
responses and follow-ups.
617+
618+
#### Example
495619

496620
```yag
497-
{{ $interactionToken := .Interaction.Token }}
498-
{{ sendResponse nil "Here's the first message!" }}
499-
{{ $followupID := sendResponseRetID $interactionToken (complexMessage "content" "Here's a sneaky one!" "ephemeral" true) }}
500-
{{ sleep 2 }}
501-
{{ editResponse $interactionToken $followupID (print "I've edited this message to say " noun) }}
502-
{{ $editedResponse := getResponse $interactionToken $followupID }}
503-
{{ editResponse $interactionToken nil $editedResponse.Content }}
621+
{{ ephemeralResponse }}
622+
623+
This text is invisible to others!
504624
```
505625

506-
- To demonstrate updating the triggering message (this must be triggered by a component or modal submission)
626+
### getResponse
507627

508628
```yag
509-
{{ $button := cbutton "label" "I won!" "custom_id" "i_won" }}
510-
{{ $content := printf "Press this button when you win! The last person who won was %s! They wanted to say they are a %s %s." .User.Mention adjective noun }}
511-
512-
{{ $message := complexMessageEdit "content" $content "buttons" $button }}
513-
{{ updateMessage $message }}
629+
{{ $response := getResponse <interactionToken> <messageID> }}
514630
```
515631

632+
Returns the response or follow-up with the specified message ID belonging to the given interaction as a [message
633+
object](/docs/reference/templates/syntax-and-data#message). Is also valid for ephemeral messages.
634+
516635
## Math
517636

518637
{{< callout context="note" title="Note" icon="outline/info-circle" >}}

0 commit comments

Comments
 (0)