Botones y menús

Un mensaje enviado por un comando puede tener botones y menús. Cuando alguien usa uno, el mismo comando corre otra vez, y sabe cuál fue el botón. Así un solo comando contiene todo un sistema: el mensaje, sus botones y lo que hace cada uno.

La idea

{{ if eq .Trigger "command" }}
  {{ sendMessage nil (complexMessage
       "content" "¿Te gusta la pizza?"
       "components" (cslice (crow
         (cbutton "label" "Sí" "id" "yes" "style" "success")
         (cbutton "label" "No" "id" "no" "style" "danger")))) }}
{{ return }}{{ end }}

{{/* Desde aquí, se usó un botón */}}
{{ respond (printf "Pulsaste **%s**." .Button.ID) true }}

• .Trigger dice por qué corre el código: "command" (alguien escribió el comando), "button" o "select" (alguien usó un botón o un menú).
• .Button.ID es el "id" del botón que se usó, y .Button.Data es su "data".
• Para un menú, .Values es la lista de las opciones que se eligieron.
• {{ return }} termina el código, así la parte del comando no corre cuando se usa un botón.

cbutton

cbutton crea un botón a partir de pares de un nombre y un valor.

Nombre	Valor
label	El texto del botón, hasta 80 caracteres
emoji	Un emoji como "👆", en lugar de la etiqueta o junto a ella
id	El nombre del botón, de 1 a 20 letras, números, - o _. Obligatorio, salvo que tenga una url
data	Texto extra para el botón, hasta 20 letras, números, ., - o _. Vuelve en .Button.Data
style	"primary", "secondary" (el predeterminado), "success" o "danger"
url	Crea un botón de enlace. Empieza con http:// o https://, y no tiene id: solo abre el enlace
disabled	true para un botón que no se puede usar
user	Un ID de usuario. Solo ese miembro puede usar el botón; a los demás se les dice “Esto no es para ti”

Un botón necesita una etiqueta o un emoji.

cselect

Un menú de opciones, a partir de pares de un nombre y un valor.

Nombre	Valor
id	El nombre del menú, como en un botón. Obligatorio
options	Una lista de opciones, cada una cslice "etiqueta" "valor" o cslice "etiqueta" "valor" "descripción". De 1 a 25
placeholder	El texto que se muestra cuando no hay nada elegido, hasta 150 caracteres
min, max	Cuántas opciones se pueden elegir. Por defecto 1 y 1
user	Un ID de usuario, como en un botón

{{ sendMessage nil (complexMessage "components" (cslice (crow
  (cselect "id" "pick" "placeholder" "Elige una" "options" (cslice
    (cslice "Pizza" "pizza" "Con queso")
    (cslice "Sushi" "sushi")))))) }}

Cuando se usa un menú, .Values contiene el value de cada opción elegida, por ejemplo (index .Values 0).

crow

crow pone componentes en una fila. Una fila contiene hasta 5 botones, o un menú solo. Un mensaje contiene hasta 5 filas:

"components" (cslice (crow boton1 boton2) (crow menu))

Modales: formularios emergentes

Un botón o un menú puede abrir un modal, un formulario con campos de texto que aparece sobre Discord. Cuando la persona lo envía, el mismo comando corre otra vez, con lo que escribió.

{{ if eq .Trigger "command" }}
  {{ sendMessage nil (complexMessage "content" "¿Tienes una idea?" "components" (cslice (crow
       (cbutton "label" "Sugerir" "id" "open" "style" "primary")))) }}
{{ return }}{{ end }}

{{ if eq .Trigger "button" }}
  {{ showModal (cmodal "id" "send" "title" "Tu sugerencia" "fields" (cslice
       (ctext "id" "title" "label" "Título" "max" 80)
       (ctext "id" "details" "label" "Detalles" "style" "paragraph" "required" false))) }}
{{ return }}{{ end }}

{{/* Desde aquí, se envió el formulario */}}
{{ respond (printf "Escribiste: **%s**" .Fields.title) true }}

• .Trigger es "modal" cuando se envió el formulario. .Modal.ID es el "id" del modal y .Modal.Data su "data".
• .Fields contiene lo que se escribió, por el id de cada campo: .Fields.title, .Fields.details. Un campo que se deja vacío es un texto vacío.
• showModal solo funciona cuando el comando corre por un botón o un menú. Un modal no puede abrir otro modal, y un comando escrito en el chat no puede abrir uno.
• respond responde al formulario, en privado con true. updateMessage cambia el mensaje en el que estaba el botón.
• Abrir el modal es la respuesta al clic, así que una ejecución puede usar showModal o respond/updateMessage, no ambos.

cmodal

Nombre	Valor
id	El nombre del modal, como en un botón. Obligatorio
title	El título de arriba, hasta 45 caracteres. Obligatorio
fields	Una lista de 1 a 5 campos hechos con ctext. Obligatorio
data	Texto extra, como el data de un botón. Vuelve en .Modal.Data

ctext

Nombre	Valor
id	El nombre del campo, de 1 a 20 letras, números o _. Obligatorio. Así lo encuentra .Fields
label	El texto encima del campo, hasta 45 caracteres. Obligatorio
style	"short" (una línea, el predeterminado) o "paragraph" (varias líneas)
placeholder	Una pista que se muestra mientras el campo está vacío, hasta 100 caracteres
value	Texto con el que empieza el campo, hasta 4000 caracteres
required	false deja que la persona lo deje vacío. Por defecto es obligatorio
min, max	La menor y la mayor cantidad de caracteres, de 0 a 4000

Responder a un clic

Cuando se usa un botón o un menú, la persona espera una respuesta. En el código de un botón puedes:

Función	Qué hace
respond mensaje	Responde al clic con un mensaje nuevo, visto por todos
respond mensaje true	Lo mismo, pero solo lo ve quien hizo clic
updateMessage mensaje	Cambia el mensaje en el que está el botón. Lo que no des se queda: si solo das un embed, los botones se quedan
Imprimir texto	Si el código imprime texto y no usa respond ni updateMessage, ese texto es la respuesta

Si el código no hace nada de eso, el clic simplemente se confirma y no se muestra nada. Solo se puede usar uno de respond y updateMessage en una ejecución.

mensaje es un texto, un cembed o un complexMessage, como en Embeds y mensajes. También puede contener nuevos "components".

Las demás acciones (addRole, sendMessage…) también funcionan en un clic, para quien hizo clic, con las mismas comprobaciones.

Qué puede leer el código en un clic

Todo lo de Datos está ahí, sobre quien hizo clic, además de:

• .Message.ID, .Message.Content y .Message.Embeds (una lista de mapas con Title, Description, Footer, Author, AuthorIcon, FooterIcon, Thumbnail, Image y Color) del mensaje en el que está el botón.
• .Trigger, .Button y .Values, como arriba. Cuando se envió un modal, .Modal y .Fields.

.Args está vacío en un clic.

Bueno saber

• Un botón sigue funcionando mientras el comando exista y tenga código. Si el comando se elimina, el clic responde “Ese comando ya no existe.”
• Usar el mismo botón dos veces seguidas en muy poco tiempo se ignora.
• Los mensajes directos no pueden tener botones ni menús.
• Cada controlador corre con los mismos límites que un comando.
• Usa los datos guardados para recordar lo que la gente eligió. El id del mensaje (.Message.ID) es una buena clave para cosas que pertenecen a un mensaje, como una votación.

Un ejemplo completo: una votación

La plantilla vote es una votación de sí o no donde cada persona tiene un voto y puede cambiarlo. Instálala con !customcommand template vote y lee su código con !customcommand codeshow vote.