Docs on handling options listeners with a filtering example (#609)

Co-authored-by: Kazuhiro Sera <[email protected]>

Author: filmaj

docs/_basic/ja_listening_responding_options.md

@@ -14,24 +14,29 @@ order: 14
 
 オプションのリクエストに応答するときは、有効なオプションを含む `options` または `option_groups` のリストとともに `ack()` を呼び出す必要があります。API サイトにある[外部データを使用する選択メニューに応答するサンプル例](https://api.slack.com/reference/messaging/block-elements#external-select)と、[ダイアログでの応答例](https://api.slack.com/dialogs#dynamic_select_elements_external)を参考にしてください。
 
+さらに、ユーザーが入力したキーワードに基づいたオプションを返すようフィルタリングロジックを適用することもできます。 これは `payload` という引数の ` value` の値に基づいて、それぞれのパターンで異なるオプションの一覧を返すように実装することができます。 Bolt for Python のすべてのリスナーやミドルウェアでは、[多くの有用な引数](https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html)にアクセスすることができますので、チェックしてみてください。
+
 </div>
 
 <div>
 <span class="annotation">指定可能な引数の一覧は<a href="https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html" target="_blank">モジュールドキュメント</a>を参考にしてください。</span>
 ```python
 # 外部データを使用する選択メニューオプションに応答するサンプル例
 @app.options("external_action")
-def show_options(ack):
+def show_options(ack, payload):
     options = [
         {
-            "text": {"type": "plain_text", "text":"Option 1"},
-            "value":"1-1",
+            "text": {"type": "plain_text", "text": "Option 1"},
+            "value": "1-1",
         },
         {
-            "text": {"type": "plain_text", "text":"Option 2"},
-            "value":"1-2",
+            "text": {"type": "plain_text", "text": "Option 2"},
+            "value": "1-2",
         },
     ]
+    keyword = payload.get("value")
+    if keyword is not None and len(keyword) > 0:
+        options = [o for o in options if keyword in o["text"]["text"]]
     ack(options=options)
 ```
-</div>
+</div>

docs/_basic/listening_responding_options.md

@@ -13,14 +13,15 @@ While it's recommended to use `action_id` for `external_select` menus, dialogs d
 
 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.
 
+Additionally, you may want to apply filtering logic to the returned options based on user input. This can be accomplished by using the `payload` argument to your options listener and checking for the contents of the `value` property within it. Based on the `value` you can return different options. All listeners and middleware handlers in Bolt for Python have access to [many useful arguments](https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html) - be sure to check them out!
 </div>
 
 <div>
 <span class="annotation">Refer to <a href="https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html" target="_blank">the module document</a> to learn the available listener arguments.</span>
 ```python
 # Example of responding to an external_select options request
 @app.options("external_action")
-def show_options(ack):
+def show_options(ack, payload):
     options = [
         {
             "text": {"type": "plain_text", "text": "Option 1"},
@@ -31,6 +32,9 @@ def show_options(ack):
             "value": "1-2",
         },
     ]
+    keyword = payload.get("value")
+    if keyword is not None and len(keyword) > 0:
+        options = [o for o in options if keyword in o["text"]["text"]]
     ack(options=options)
 ```
-</div>
+</div>