update docs > basics with shay feedback

misscoded · seratch · commit 2519e4e880a7 · 2020-09-19T09:34:01.000+09:00
diff --git a/docs/_basic/authenticating_oauth.md b/docs/_basic/authenticating_oauth.md
@@ -7,7 +7,7 @@ order: 14
 
 <div class="section-content">
 
-Slack apps installed on multiple workspaces will need to implement OAuth, then store installation information (like access tokens) securely. By providing `client_id`, `client_secret`, `scopes`, `installation_store`, and `state_store` when initializing App, Bolt for Python will handle the work of setting up OAuth routes and verifying state. If you’re implementing a custom receiver, you can make use of our [OAuth library](https://slack.dev/python-slack-sdk/oauth), which is what Bolt for Python uses under the hood.
+Slack apps installed on multiple workspaces will need to implement OAuth, then store installation information (like access tokens) securely. By providing `client_id`, `client_secret`, `scopes`, `installation_store`, and `state_store` when initializing App, Bolt for Python will handle the work of setting up OAuth routes and verifying state. If you’re implementing a custom receiver, you can make use of our [OAuth library](https://slack.dev/python-slack-sdk/oauth/), which is what Bolt for Python uses under the hood.
 
 Bolt for Python will create a **Redirect URL** `slack/oauth_redirect`, which Slack uses to redirect users after they complete your app’s installation flow. You will need to add this **Redirect URL** in your app configuration settings under **OAuth and Permissions**. This path can be configured in the `OAuthSettings` argument described below.
 
diff --git a/docs/_basic/listening_actions.md b/docs/_basic/listening_actions.md
@@ -6,7 +6,7 @@ order: 5
 ---
 
 <div class="section-content">
-Your app can listen to user actions like button clicks, and menu selects, using the `action` method.
+Your app can listen to user actions, like button clicks, and menu selects, using the `action` method.
 
 Actions can be filtered on an `action_id` of type `str` or `re.Pattern`. `action_id`s act as unique identifiers for interactive components on the Slack platform.
 
diff --git a/docs/_basic/listening_events.md b/docs/_basic/listening_events.md
@@ -7,7 +7,7 @@ order: 3
 
 <div class="section-content">
 
-You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method after subscribing to it in your app configuration. This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.
+You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method after subscribing to it in your app configuration. This allows your app to take action when something happens in a workspace where it's installed, like a user reacting to a message or joining a channel.
 
 The `event()` method requires an `eventType` of type `str`.
 
diff --git a/docs/_basic/listening_modals.md b/docs/_basic/listening_modals.md
@@ -17,27 +17,28 @@ Read more about view submissions in our <a href="https://api.slack.com/surfaces/
 
 ```python
 # Handle a view_submission event
-@app.view("view_b")
-def handle_submission(ack, body, client, view):
-    # Acknowledge the view_submission event
-    ack()
-
-    # Do whatever you want with the input data - here we're saving it to a DB then sending the user a verifcation of their submission
-
-    # Assume there's an input block with `block_1` as the block_id and `input_a`
-    val = view["state"]["values"]["block_1"]["input_a"]
-    user = body["user"]["id"]
-
-    # Message to send user
-    msg = ""
-
-    # TODO: Store in DB
-
-    if results:
-      msg = "Your submission was successful"
-    else:
-      msg = "There was an error with your submission"
-
-    # Message the user
-    client.chat_postMessage(channel=user, text=msg)
+​​@app.view("view_b")
+​​def handle_submission(ack, body, client, view):
+​​    # Acknowledge the view_submission event
+​​    ack()
+​​
+​​    # Do whatever you want with the input data - here we're saving it to a DB
+    # then sending the user a verifcation of their submission
+​​
+​​    # Assume there's an input block with `block_1` as the block_id and `input_a`
+​​    val = view["state"]["values"]["block_1"]["input_a"]
+​​    user = body["user"]["id"]
+​​
+​​    # Message to send user
+​​    msg = ""
+​​
+​​    try:
+​​      # Save to DB
+​​      msg = f"Your submission of {val} was successful"
+​​    except Exception as e:
+​​      # Handle error
+​​      msg = "There was an error with your submission"
+​​    finally:
+​​      # Message the user
+​​      client.chat_postMessage(channel=user, text=msg)
 ```
diff --git a/docs/_basic/listening_responding_commands.md b/docs/_basic/listening_responding_commands.md
@@ -13,7 +13,7 @@ Commands must be acknowledged with `ack()` to inform Slack your app has received
 
 There are two ways to respond to slash commands. The first way is to use `say()`, which accepts a string or JSON payload. The second is `respond()` which is a utility for the `response_url`. These are explained in more depth in the [responding to actions](#action-respond) section.
 
-When configuring commands within your app configuration, you'll continue to append `/slack/events` to your request URL.
+When setting up commands within your app configuration, you'll append `/slack/events` to your request URL.
 
 </div>
 
diff --git a/docs/_basic/listening_responding_options.md b/docs/_basic/listening_responding_options.md
@@ -7,12 +7,12 @@ order: 13
 
 <div class="section-content">
 The `options()` method listens for incoming option request payloads from Slack. [Similar to `action()`](#action-listening),
-an `action_id` or constraints object is required. In order to load external data into your select menus, you must provide an options load URL in your app configuration.
+an `action_id` or constraints object is required. In order to load external data into your select menus, you must provide an options load URL in your app configuration, appended with `/slack/events`.
 
-While it's recommended to use `action_id` for `external_select` menus, dialogs do not yet support Block Kit so you'll have to 
-use the constraints object to filter on a `callback_id`.
+While it's recommended to use `action_id` for `external_select` menus, dialogs do not support Block Kit so you'll have to use the constraints object to filter on a `callback_id`.
+
+To respond to options requests, you'll need to call `ack()` with a valid `options` or `option_groups` list. Both [external select response examples](https://api.slack.com/reference/messaging/block-elements#external-select) and [dialog response examples](https://api.slack.com/dialogs#dynamic_select_elements_external) can be found on our API site.
 
-To respond to options requests, you'll need to `ack()` with valid options. Both [external select response examples](https://api.slack.com/reference/messaging/block-elements#external-select) and [dialog response examples](https://api.slack.com/dialogs#dynamic_select_elements_external) can be found on our API site.
 </div>
 
 ```python
@@ -29,6 +29,5 @@ def show_options(ack):
             "value": "1-2",
         },
     ]
-
     ack(options=options)
 ```
diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md
@@ -15,9 +15,9 @@ Shortcuts must be acknowledged with `ack()` to inform Slack that your app has re
 
 Shortcuts include a `trigger_id` which an app can use to [open a modal](#creating-modals) that confirms the action the user is taking.
 
-When configuring shortcuts within your app configuration, you'll continue to append `/slack/events` to your request URL.
+When setting up shortcuts within your app configuration, as with other URLs, you'll append `/slack/events` to your request URL.
 
-⚠️ Note that global shortcuts do **not** include a channel ID. If your app needs access to a channel ID, you may use a [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) element within a modal. Message shortcuts do include channel ID.
+⚠️ Note that global shortcuts do **not** include a channel ID. If your app needs access to a channel ID, you may use a [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) element within a modal. Message shortcuts do include a channel ID.
 
 </div>
 
diff --git a/docs/_basic/opening_modals.md b/docs/_basic/opening_modals.md
@@ -6,23 +6,24 @@ order: 10
 ---
 
 <div class="section-content">
-<a href="https://api.slack.com/block-kit/surfaces/modals">Modals</a> are focused surfaces that allow you to collect user data and display dynamic information. You can open a modal by passing a valid <code>trigger_id</code> and a <a href="https://api.slack.com/reference/block-kit/views">view payload</a> to the built-in client's <a href="https://api.slack.com/methods/views.open"><code>views.open</code></a> method.
 
-Your app receives <code>trigger_id</code>s in payloads sent to your Request URL triggered user invocation like a slash command, button press, or interaction with a select menu.
+<a href="https://api.slack.com/block-kit/surfaces/modals">Modals</a> are focused surfaces that allow you to collect user data and display dynamic information. You can open a modal by passing a valid `trigger_id` and a <a href="https://api.slack.com/reference/block-kit/views">view payload</a> to the built-in client's <a href="https://api.slack.com/methods/views.open">`views.open`</a> method.
+
+Your app receives `trigger_id`s in payloads sent to your Request URL that are triggered by user invocations, like a shortcut, button press, or interaction with a select menu.
 
 Read more about modal composition in the <a href="https://api.slack.com/surfaces/modals/using#composing_views">API documentation</a>.
 
 </div>
 
 ```python
-# Listen for a slash command invocation
-@app.command("/ticket")
+# Listen for a shortcut invocation
+@app.shortcut("open_modal")
 def open_modal(ack, body, client):
     # Acknowledge the command request
     ack();
 
     # Call views_open with the built-in client
-    client.views_open({
+    client.views_open(
         # Pass a valid trigger_id within 3 seconds of receiving it
         trigger_id=body["trigger_id"],
         # View payload
@@ -69,5 +70,5 @@ def open_modal(ack, body, client):
                 "text": "Submit"
             }
         }
-    })
+    )
 ```
diff --git a/docs/_basic/responding_actions.md b/docs/_basic/responding_actions.md
@@ -9,7 +9,7 @@ order: 6
 
 There are two main ways to respond to actions. The first (and most common) way is to use the `say` function. The `say` function sends a message back to the conversation where the incoming event took place.
 
-The second way to respond to actions is using `respond()`, which is a simple utility to use the `response_url` associated with an action.
+The second way to respond to actions is using `respond()`, which is a utility to use the `response_url` associated with the action.
 
 </div>
 
diff --git a/docs/_basic/updating_pushing_modals.md b/docs/_basic/updating_pushing_modals.md
@@ -9,11 +9,11 @@ order: 11
 
 Modals contain a stack of views. When you call <a href="https://api.slack.com/methods/views.open">`views_open`</a>, you add the root view to the modal. After the initial call, you can dynamically update a view by calling <a href="https://api.slack.com/methods/views.update">`views_update`</a>, or stack a new view on top of the root view by calling <a href="https://api.slack.com/methods/views.push">`views_push`</a>.
 
-<strong><code>views_update</code></strong><br>
-To update a view, you can use the built-in client to call <code>views_update</code> with the <code>view_id</code> that was generated when you opened the view, and a new <code>view</code> including the updated <code>blocks</code> array. If you're updating the view when a user interacts with an element inside of an existing view, the <code>view_id</code> will be available in the <code>body</code> of the request.
+**`views_update`**<br>
+To update a view, you can use the built-in client to call `views_update` with the `view_id` that was generated when you opened the view, and a new `view` including the updated `blocks` list. If you're updating the view when a user interacts with an element inside of an existing view, the `view_id` will be available in the `body` of the request.
 
-<strong><code>views_push</code></strong><br>
-To push a new view onto the view stack, you can use the built-in client to call <code>views_push</code> with a valid <code>trigger_id</code> a new <a href="https://api.slack.com/reference/block-kit/views">view payload</a>. The arguments for `views_push` is the same as <a href="#creating-modals">opening modals</a>. After you open a modal, you may only push two additional views onto the view stack.
+**`views_push`**<br>
+To push a new view onto the view stack, you can use the built-in client to call `views_push` with a valid `trigger_id` a new <a href="https://api.slack.com/reference/block-kit/views">view payload</a>. The arguments for `views_push` is the same as <a href="#creating-modals">opening modals</a>. After you open a modal, you may only push two additional views onto the view stack.
 
 Learn more about updating and pushing views in our <a href="https://api.slack.com/surfaces/modals/using#modifying">API documentation</a>.
 
@@ -28,6 +28,8 @@ def update_modal(ack, view, client):
     client.views_update(
         # Pass the view_id
         view_id=view["id"],
+        # String that represents view state to protect against race conditions
+        hash=view["hash"],
         # View payload with updated blocks
         view={
             "type": "modal",
diff --git a/docs/_basic/web_api.md b/docs/_basic/web_api.md
@@ -8,7 +8,7 @@ order: 4
 <div class="section-content">
 You can call [any Web API method](https://api.slack.com/methods) using the [`WebClient`](https://slack.dev/python-slack-sdk/basic_usage.html) provided to your Bolt app as `app.client` (given that your app has the appropriate scopes). When you call one the client’s methods, it returns a `SlackResponse` which contains the response from Slack.
 
-The token used to initialize Bolt can be found in the `context` object, which is required for most Web API methods.
+The token used to initialize Bolt can be found in the `context` object, which is required to call most Web API methods.
 
 </div>
 
@@ -17,7 +17,7 @@ The token used to initialize Bolt can be found in the `context` object, which is
 def say_hello(client, message):
     # Unix Epoch time for September 30, 2020 11:59:59 PM
     when_september_ends = 1601510399
-    channel_id = message['channel']
+    channel_id = message["channel"]
     client.chat_scheduleMessage(channel=channel_id,
                                 post_at=when_september_ends,
                                 text="Summer has come and passed")
