Skip to content

Commit ce3216c

Browse files
WilliamBergaminWilliamBergamin
authored
Merge branch 'main' into zimeg-build-pytest-requirement-lower-bound
2 parents da1ff23 + 1e69f1d commit ce3216c

File tree

1 file changed

+100
-66
lines changed

1 file changed

+100
-66
lines changed

‎docs/content/tutorial/modals.md‎

Lines changed: 100 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,135 @@
1+
12
# Modals
23

3-
If you're learning about Slack apps, modals, or slash commands for the first time, you've come to the right place! In this tutorial, we'll take a look at setting up your very own server using Glitch, and using that server to run your Slack app.
4+
If you're learning about Slack apps, modals, or slash commands for the first time, you've come to the right place! In this tutorial, we'll take a look at setting up your very own server using GitHub Codespaces, then using that server to run your Slack app built with the [**Bolt for Python framework**](https://github.com/SlackAPI/bolt-python).
45

5-
Let's take a look at the technologies we'll use in this tutorial:
6+
:::info[GitHub Codespaces]
7+
GitHub Codespaces is an online IDE that allows you to work on code and host your own server at the same time. While Codespaces is good for testing and development purposes, it should not be used in production.
68

7-
* Glitch is a online IDE that allows you to collaboratively work on code and host your own server. Glitch should only be used for development purposes and should not be used in production.
8-
* We'll use Python in conjunction with our [Bolt for Python](https://github.com/SlackAPI/bolt-python) SDK.
9-
* [Block Kit](https://docs.slack.dev/block-kit/) is a UI framework for Slack apps that allows you to create beautiful, interactive messages within Slack. If you've ever seen a message in Slack with buttons or a select menu, that's Block Kit.
10-
* Modals are similar to a pop-up window that displays right in Slack. They grab the attention of the user, and are normally used to prompt users to provide some kind of information or input.
9+
:::
1110

12-
---
11+
At the end of this tutorial, your final app will look like this:
1312

14-
## Final product overview {#final_product}
15-
If you follow through with the extra credit tasks, your final app will look like this:
13+
![announce](https://github.com/user-attachments/assets/0bf1c2f0-4b22-4c9c-98b3-b21e9bcc14a8)
1614

17-
![Final product](/img/tutorials/modals/final_product.gif)
15+
And will make use of these Slack concepts:
16+
* [**Block Kit**](https://docs.slack.dev/block-kit/) is a UI framework for Slack apps that allows you to create beautiful, interactive messages within Slack. If you've ever seen a message in Slack with buttons or a select menu, that's Block Kit.
17+
* [**Modals**](https://docs.slack.dev/surfaces/modals) are a pop-up window that displays right in Slack. They grab the attention of the user, and are normally used to prompt users to provide some kind of information or input in a form.
18+
* [**Slash Commands**](https://docs.slack.dev/interactivity/implementing-slash-commands) allow you to invoke your app within Slack by just typing into the message composer box. e.g. `/remind`, `/topic`.
1819

19-
---
20+
If you're familiar with using Heroku you can also deploy directly to Heroku with the following button.
2021

21-
## The process {#steps}
22+
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/wongjas/modal-example)
2223

23-
1. [Create a new app](https://api.slack.com/apps/new) and name it whatever you like.
24+
---
25+
26+
## Setting up your app within App Settings {#setting-up-app-settings}
2427

25-
2. [Remix (or clone)](https://glitch.com/edit/#!/remix/intro-to-modals-bolt) the Glitch template.
28+
You'll need to create an app and configure it properly within App Settings before using it.
2629

27-
Here's a copy of what the modal payload looks like — this is what powers the modal.
30+
1. [Create a new app](https://api.slack.com/apps/new), click `From a Manifest`, and choose the workspace that you want to develop on. Then copy the following JSON object; it describes the metadata about your app, like its name, its bot display name and permissions it will request.
2831

2932
```json
3033
{
31-
"type": "modal",
32-
"callback_id": "gratitude-modal",
33-
"title": {
34-
"type": "plain_text",
35-
"text": "Gratitude Box",
36-
"emoji": true
37-
},
38-
"submit": {
39-
"type": "plain_text",
40-
"text": "Submit",
41-
"emoji": true
42-
},
43-
"close": {
44-
"type": "plain_text",
45-
"text": "Cancel",
46-
"emoji": true
47-
},
48-
"blocks": [
49-
{
50-
"type": "input",
51-
"block_id": "my_block",
52-
"element": {
53-
"type": "plain_text_input",
54-
"action_id": "my_action"
55-
},
56-
"label": {
57-
"type": "plain_text",
58-
"text": "Say something nice!",
59-
"emoji": true
60-
}
34+
"display_information": {
35+
"name": "Intro to Modals"
36+
},
37+
"features": {
38+
"bot_user": {
39+
"display_name": "Intro to Modals",
40+
"always_online": false
41+
},
42+
"slash_commands": [
43+
{
44+
"command": "/announce",
45+
"description": "Makes an announcement",
46+
"should_escape": false
47+
}
48+
]
49+
},
50+
"oauth_config": {
51+
"scopes": {
52+
"bot": [
53+
"chat:write",
54+
"commands"
55+
]
56+
}
57+
},
58+
"settings": {
59+
"interactivity": {
60+
"is_enabled": true
61+
},
62+
"org_deploy_enabled": false,
63+
"socket_mode_enabled": true,
64+
"token_rotation_enabled": false
6165
}
62-
]
6366
}
6467
```
6568

66-
3. Find the base path to your server by clicking **Share**, then copy the Live site link.
69+
2. Once your app has been created, scroll down to `App-Level Tokens` and create a token that requests for the [`connections:write`](https://docs.slack.dev/reference/scopes/connections.write) scope, which allows you to use [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode), a secure way to develop on Slack through the use of WebSockets. Copy the value of your app token and keep it for safe-keeping.
70+
71+
3. Install your app by heading to `Install App` in the left sidebar. Hit `Allow`, which means you're agreeing to install your app with the permissions that it is requesting. Be sure to copy the token that you receive, and keep it somewhere secret and safe.
6772

68-
![Get the base link](/img/tutorials/modals/base_link.gif)
73+
## Starting your Codespaces server {#starting-server}
6974

70-
4. On your app page, navigate to **Interactivity & Shortcuts**. Append "/slack/events" to your base path URL and enter it into the **Request URL** e.g., `https://festive-harmonious-march.glitch.me/slack/events`. This allows your server to retrieve information from the modal. You can see the code for this within the Glitch project.
75+
1. Log into GitHub and head to this [repository](https://github.com/wongjas/modal-example).
7176

72-
![Interactivity URL](/img/tutorials/modals/interactivity_url.png)
77+
2. Click the green `Code` button and hit the `Codespaces` tab and then `Create codespace on main`. This will bring up a code editor within your browser so you can start coding.
7378

74-
5. Create the slash command so you can access it within Slack. Navigate to the **Slash Commands** section and create a new command. Note the **Request URL** is the same link as above, e.g. `https://festive-harmonious-march.glitch.me/slack/events` . The code that powers the slash command and opens a modal can be found within the Glitch project.
79+
## Understanding the project files {#understanding-files}
7580

76-
![Slash command details](/img/tutorials/modals/slash_command.png)
81+
Within the project you'll find a `manifest.json` file. This is a a configuration file used by Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.
7782

78-
6. Select **Install App**. After you've done this, you'll see a **Bot User OAuth Access Token**, copy this.
83+
The `simple_modal_example.py` Python script contains the code that powers your app. If you're going to tinker with the app itself, take a look at the comments found within the `simple_modal_example.py` file!
7984

80-
7. Navigate to your Glitch project and click the `.env` file where the credentials are stored, and paste your bot token where the `SLACK_BOT_TOKEN` variable is shown. This allows your server to send authenticated requests to the Slack API. You'll also need to head to your app's settings page under **Basic Information** and copy the _Signing secret_ to place into the `SLACK_SIGNING_SECRET` variable.
85+
The `requirements.txt` file contains the Python package dependencies needed to run this app.
8186

82-
![Environment variables](/img/tutorials/modals/heart_icon.gif)
87+
:::info[This repo contains optional Heroku-specific configurations]
8388

84-
8. Test by heading to Slack and typing `/thankyou`.
89+
The `app.json` file defines your Heroku app configuration including environment variables and deployment settings, to allow your app to deploy with one click. `Procfile` is a Heroku-specific file that tells Heroku what command to run when starting your app — in this case a Python script would run as a `worker` process. If you aren't deploying to Heroku, you can ignore both these files.
8590

86-
All done! 🎉 You've created your first slash command using Block Kit and modals! The world is your oyster; you can create more complex modals by playing around with [Block Kit Builder](https://app.slack.com/block-kit-builder).
91+
:::
92+
93+
## Adding tokens {#adding-tokens}
94+
95+
1. Open a terminal up within the browser's editor.
96+
97+
2. Grab the app and bot tokens that you kept safe. We're going to set them as environment variables.
98+
99+
```bash
100+
export SLACK_APP_TOKEN=<YOUR-APP-TOKEN-HERE>
101+
export SLACK_BOT_TOKEN=<YOUR-BOT-TOKEN-HERE>
102+
```
87103

88-
### Extra credit {#extra_credit}
104+
## Running the app {#running-app}
105+
106+
1. Activate a virtual environment for your Python packages to be installed.
107+
108+
```bash
109+
# Setup your python virtual environment
110+
python3 -m venv .venv
111+
source .venv/bin/activate
112+
```
113+
114+
2. Install the dependencies from the `requirements.txt` file.
115+
116+
117+
```bash
118+
# Install the dependencies
119+
pip install -r requirements.txt
120+
```
121+
122+
3. Start your app using the `python3 simple_modal_example.py` command.
123+
124+
```bash
125+
# Start your local server
126+
python3 simple_modal_example.py
127+
```
89128

90-
For a little extra credit, let's post the feedback we received in a channel.
129+
4. Now that your app is running, you should be able to see it within Slack. Test this by heading to Slack and typing `/announce`.
91130

92-
1. Add the `chat:write` bot scope, which allows your bot to post messages within Slack. You can do this in the **OAuth & Permissions** section for your Slack app.
93-
2. Reinstall your app to apply the scope.
94-
3. Create a channel and name it `#thanks`. Get its ID by right clicking the channel name, copying the link, and copying the last part starting with the letter `C`. For example, if your channel link looks like this: https://my.slack.com/archives/C123FCN2MLM, the ID is `C123FCN2MLM`.
95-
4. Add your bot to the channel by typing the command `/invite @your_bots_name`.
96-
5. Uncomment the `Extra Credit` code within your Glitch project and make sure to replace `your_channel_id` with the ID above.
97-
6. Test it out by typing `/thankyou`, and watching all the feedback come into your channel!
131+
All done! 🎉 You've created your first slash command using Block Kit and modals! The world is your oyster; play around with [Block Kit Builder](https://app.slack.com/block-kit-builder) and create more complex modals and place them in your code to see what happens!
98132

99133
## Next steps {#next-steps}
100134

101-
If you want to learn more about Bolt for Python, refer to the [Getting Started guide](/bolt-python/getting-started).
135+
If you want to learn more about Bolt for Python, refer to the [Getting Started guide](https://tools.slack.dev/bolt-python/getting-started).

0 commit comments

Comments
 (0)