|
| 1 | +--- |
| 2 | +uid: Guides.Modals.Intro |
| 3 | +title: Getting Started with Modals |
| 4 | +--- |
| 5 | +# Modals |
| 6 | + |
| 7 | +## Getting started with modals |
| 8 | +This guide will show you how to use modals and give a few examples of |
| 9 | +valid use cases. If your question is not covered by this guide ask in the |
| 10 | +[Discord.Net Discord Server](https://discord.gg/dnet). |
| 11 | + |
| 12 | +### What is a modal? |
| 13 | +Modals are forms bots can send when responding to interactions. Modals |
| 14 | +are sent to Discord as an array of message components and converted |
| 15 | +into the form layout by user's clients. Modals are required to have a |
| 16 | +custom id, title, and at least one component. |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +When users submit modals, your client fires the ModalSubmitted event. |
| 21 | +You can get the components of the modal from the `Data.Components` property |
| 22 | +on the SocketModal: |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +### Using modals |
| 27 | + |
| 28 | +Lets create a simple modal with an entry field for users to |
| 29 | +tell us their favorite food. We can start by creating a slash |
| 30 | +command that will respond with the modal. |
| 31 | +```cs |
| 32 | +[SlashCommand("food", "Tell us about your favorite food!")] |
| 33 | +public async Task FoodPreference() |
| 34 | +{ |
| 35 | + // send a modal |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +Now that we have our command set up, we need to build a modal. |
| 40 | +We can use the aptly named `ModalBuilder` for that: |
| 41 | + |
| 42 | +| Method | Description | |
| 43 | +| --------------- | ----------------------------------------- | |
| 44 | +| `WithTitle` | Sets the modal's title. | |
| 45 | +| `WithCustomId` | Sets the modal's custom id. | |
| 46 | +| `AddTextInput` | Adds a `TextInputBuilder` to the modal. | |
| 47 | +| `AddComponents` | Adds multiple components to the modal. | |
| 48 | +| `Build` | Builds the `ModalBuilder` into a `Modal`. | |
| 49 | + |
| 50 | +We know we need to add a text input to the modal, so let's look at that |
| 51 | +method's parameters. |
| 52 | + |
| 53 | +| Parameter | Description | |
| 54 | +| ------------- | ------------------------------------------ | |
| 55 | +| `label` | Sets the input's label. | |
| 56 | +| `customId` | Sets the input's custom id. | |
| 57 | +| `style` | Sets the input's style. | |
| 58 | +| `placeholder` | Sets the input's placeholder. | |
| 59 | +| `minLength` | Sets the minimum input length. | |
| 60 | +| `maxLength` | Sets the maximum input length. | |
| 61 | +| `required` | Sets whether or not the modal is required. | |
| 62 | +| `value` | Sets the input's default value. | |
| 63 | + |
| 64 | +To make a basic text input we would only need to set the `label` and |
| 65 | +`customId`, but in this example we will also use the `placeholder` |
| 66 | +parameter. Next we can build our modal: |
| 67 | + |
| 68 | +```cs |
| 69 | +var mb = new ModalBuilder() |
| 70 | + .WithTitle("Fav Food") |
| 71 | + .WithCustomId("food_menu") |
| 72 | + .AddTextInput("What??", "food_name", placeholder:"Pizza") |
| 73 | + .AddTextInput("Why??", "food_reason", TextInputStyle.Paragraph, |
| 74 | + "Kus it's so tasty"); |
| 75 | +``` |
| 76 | + |
| 77 | +Now that we have a ModalBuilder we can update our command to respond |
| 78 | +with the modal. |
| 79 | + |
| 80 | +```cs |
| 81 | +[SlashCommand("food", "Tell us about your favorite food!")] |
| 82 | +public async Task FoodPreference() |
| 83 | +{ |
| 84 | + var mb = new ModalBuilder() |
| 85 | + .WithTitle("Fav Food") |
| 86 | + .WithCustomId("food_menu") |
| 87 | + .AddTextInput("What??", "food_name", placeholder:"Pizza") |
| 88 | + .AddTextInput("Why??", "food_reason", TextInputStyle.Paragraph, |
| 89 | + "Kus it's so tasty"); |
| 90 | + |
| 91 | + await Context.Interaction.RespondWithModalAsync(mb.Build()); |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +When we run the command, our modal should pop up: |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | +### Respond to modals |
| 100 | + |
| 101 | +> [!WARNING] |
| 102 | +> Modals can not be sent when respoding to a modal. |
| 103 | +
|
| 104 | +Once a user has submitted the modal, we need to let everyone know what |
| 105 | +their favorite food is. We can start by hooking a task to the client's |
| 106 | +`ModalSubmitted` event. |
| 107 | +```cs |
| 108 | +_client.ModalSubmitted += async modal => |
| 109 | +{ |
| 110 | + // Get the values of components. |
| 111 | + List<SocketMessageComponentData> components = |
| 112 | + modal.Data.Components.ToList(); |
| 113 | + string food = components |
| 114 | + .Where(x => x.CustomId == "food_name").First().Value; |
| 115 | + string reason = components |
| 116 | + .Where(x => x.CustomId == "food_reason").First().Value; |
| 117 | + |
| 118 | + // Build the message to send. |
| 119 | + string message = "hey @everyone; I just learned " + |
| 120 | + $"{modal.User.Mention}'s favorite food is " + |
| 121 | + $"{food} because {reason}."; |
| 122 | + |
| 123 | + // Specify the AllowedMentions so we don't actually ping everyone. |
| 124 | + AllowedMentions mentions = new AllowedMentions(); |
| 125 | + mentions.AllowedTypes = AllowedMentionTypes.Users; |
| 126 | + |
| 127 | + // Respond to the modal. |
| 128 | + await modal.RespondAsync(message, allowedMentions:mentions); |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +Now responding to the modal should inform everyone of our tasty |
| 133 | +choices. |
| 134 | + |
| 135 | + |
0 commit comments