Botões e menus

Uma mensagem enviada por um comando pode ter botões e menus. Quando alguém usa um, o mesmo comando roda de novo, e ele sabe qual foi o botão. Assim um único comando contém todo um sistema: a mensagem, seus botões e o que cada um faz.

A ideia

{{ if eq .Trigger "command" }}
  {{ sendMessage nil (complexMessage
       "content" "Você gosta de pizza?"
       "components" (cslice (crow
         (cbutton "label" "Sim" "id" "yes" "style" "success")
         (cbutton "label" "Não" "id" "no" "style" "danger")))) }}
{{ return }}{{ end }}

{{/* A partir daqui, um botão foi usado */}}
{{ respond (printf "Você apertou **%s**." .Button.ID) true }}

.Trigger diz por que o código está rodando: "command" (alguém digitou o comando), "button" ou "select" (alguém usou um botão ou um menu).
.Button.ID é o "id" do botão que foi usado, e .Button.Data é o seu "data".
Para um menu, .Values é a lista das opções que foram escolhidas.
{{ return }} encerra o código, então a parte do comando não roda quando um botão é usado.

cbutton

cbutton cria um botão a partir de pares de um nome e um valor.

Nome	Valor
`label`	O texto do botão, até 80 caracteres
`emoji`	Um emoji como `"👆"`, no lugar do rótulo ou junto com ele
`id`	O nome do botão, de 1 a 20 letras, números, `-` ou `_`. Obrigatório, a menos que tenha uma `url`
`data`	Texto extra para o botão, até 20 letras, números, `.`, `-` ou `_`. Volta em `.Button.Data`
`style`	`"primary"`, `"secondary"` (o padrão), `"success"` ou `"danger"`
`url`	Cria um botão de link. Começa com `http://` ou `https://`, e não tem `id`: só abre o link
`disabled`	`true` para um botão que não pode ser usado
`user`	Um ID de usuário. Só esse membro pode usar o botão; os outros ouvem “Isto não é para você”

Um botão precisa de um rótulo ou de um emoji.

cselect

Um menu de opções, a partir de pares de um nome e um valor.

Nome	Valor
`id`	O nome do menu, como em um botão. Obrigatório
`options`	Uma lista de opções, cada uma `cslice "rótulo" "valor"` ou `cslice "rótulo" "valor" "descrição"`. De 1 a 25
`placeholder`	O texto mostrado quando nada está escolhido, até 150 caracteres
`min`, `max`	Quantas opções podem ser escolhidas. Por padrão 1 e 1
`user`	Um ID de usuário, como em um botão

{{ sendMessage nil (complexMessage "components" (cslice (crow
  (cselect "id" "pick" "placeholder" "Escolha uma" "options" (cslice
    (cslice "Pizza" "pizza" "Com queijo")
    (cslice "Sushi" "sushi")))))) }}

Quando um menu é usado, .Values contém o value de cada opção escolhida, por exemplo (index .Values 0).

crow

crow coloca componentes em uma linha. Uma linha contém até 5 botões, ou um menu sozinho. Uma mensagem contém até 5 linhas:

"components" (cslice (crow botao1 botao2) (crow menu))

Modais: formulários que aparecem

Um botão ou um menu pode abrir um modal, um formulário com campos de texto que aparece sobre o Discord. Quando a pessoa o envia, o mesmo comando roda de novo, com o que ela escreveu.

{{ if eq .Trigger "command" }}
  {{ sendMessage nil (complexMessage "content" "Tem uma ideia?" "components" (cslice (crow
       (cbutton "label" "Sugerir" "id" "open" "style" "primary")))) }}
{{ return }}{{ end }}

{{ if eq .Trigger "button" }}
  {{ showModal (cmodal "id" "send" "title" "Sua sugestão" "fields" (cslice
       (ctext "id" "title" "label" "Título" "max" 80)
       (ctext "id" "details" "label" "Detalhes" "style" "paragraph" "required" false))) }}
{{ return }}{{ end }}

{{/* A partir daqui, o formulário foi enviado */}}
{{ respond (printf "Você escreveu: **%s**" .Fields.title) true }}

.Trigger é "modal" quando o formulário foi enviado. .Modal.ID é o "id" do modal e .Modal.Data o seu "data".
.Fields contém o que foi escrito, pelo id de cada campo: .Fields.title, .Fields.details. Um campo deixado vazio é um texto vazio.
showModal só funciona quando o comando roda por causa de um botão ou de um menu. Um modal não pode abrir outro modal, e um comando digitado no chat não pode abrir um.
respond responde ao formulário, em privado com true. updateMessage muda a mensagem em que o botão estava.
Abrir o modal é a resposta ao clique, então uma execução pode usar showModal ou respond/updateMessage, não os dois.

cmodal

Nome	Valor
`id`	O nome do modal, como em um botão. Obrigatório
`title`	O título de cima, até 45 caracteres. Obrigatório
`fields`	Uma lista de 1 a 5 campos feitos com `ctext`. Obrigatório
`data`	Texto extra, como o `data` de um botão. Volta em `.Modal.Data`

ctext

Nome	Valor
`id`	O nome do campo, de 1 a 20 letras, números ou `_`. Obrigatório. É assim que `.Fields` o encontra
`label`	O texto acima do campo, até 45 caracteres. Obrigatório
`style`	`"short"` (uma linha, o padrão) ou `"paragraph"` (várias linhas)
`placeholder`	Uma dica mostrada enquanto o campo está vazio, até 100 caracteres
`value`	Texto com que o campo começa, até 4000 caracteres
`required`	`false` deixa a pessoa deixá-lo vazio. Por padrão é obrigatório
`min`, `max`	A menor e a maior quantidade de caracteres, de 0 a 4000

Responder a um clique

Quando um botão ou um menu é usado, a pessoa espera uma resposta. No código de um botão você pode:

Função	O que faz
`respond mensagem`	Responde ao clique com uma mensagem nova, vista por todos
`respond mensagem true`	O mesmo, mas só quem clicou vê
`updateMessage mensagem`	Muda a mensagem em que o botão está. O que você não der fica: se você só der um embed, os botões ficam
Imprimir texto	Se o código imprime texto e não usa `respond` nem `updateMessage`, esse texto é a resposta

Se o código não faz nada disso, o clique é apenas confirmado e nada é mostrado. Só um de respond e updateMessage pode ser usado em uma execução.

mensagem é um texto, um cembed ou um complexMessage, como em Embeds e mensagens. Também pode conter novos "components".

As outras ações (addRole, sendMessage…) também funcionam em um clique, para quem clicou, com as mesmas verificações.

O que o código pode ler em um clique

Tudo de Dados está lá, sobre quem clicou, além de:

.Message.ID, .Message.Content e .Message.Embeds (uma lista de mapas com Title, Description, Footer, Author, AuthorIcon, FooterIcon, Thumbnail, Image e Color) da mensagem em que o botão está.
.Trigger, .Button e .Values, como acima. Quando um modal foi enviado, .Modal e .Fields.

.Args fica vazio em um clique.

Bom saber

Um botão continua funcionando enquanto o comando existir e tiver código. Se o comando for removido, o clique responde “Esse comando não existe mais.”
Usar o mesmo botão duas vezes seguidas em muito pouco tempo é ignorado.
Mensagens diretas não podem ter botões nem menus.
Cada tratador roda com os mesmos limites que um comando.
Use os dados guardados para lembrar o que as pessoas escolheram. O id da mensagem (.Message.ID) é uma boa chave para coisas que pertencem a uma mensagem, como uma votação.

Um exemplo completo: uma votação

O template vote é uma votação de sim ou não em que cada pessoa tem um voto e pode mudá-lo. Instale-o com !customcommand template vote e leia o seu código com !customcommand codeshow vote.