Merge pull request #268 from seratch/feature/bk-in-modals-ja-docs

Add Japanese documents for Block Kit in Modals

docs/_basic/ja_listening_modals.md

@@ -0,0 +1,55 @@
+---
+title: モーダルビューでの送信のリスニング
+lang: ja-jp
+slug: view_submissions
+order: 11
+---
+
+<div class="section-content">
+<a href="https://api.slack.com/reference/block-kit/views">モーダルビューのペイロード</a>が入力のブロックを含む場合、その入力値を受け取るために <code>view_submission</code> のイベントをリスニングする必要があります。<code>view_submission</code> イベントをリスニングするためには、組み込みの <code>view()</code> メソッドを使用します。
+
+<code>view()</code> メソッドは、文字列型または <code>RegeExp</code>型 の <code>callback_id</code> を必要とします。
+
+<code>input</code> ブロックの値は <code>state</code> オブジェクトを参照することで取得できます。<code>state</code> 内には <code>values</code> というオブジェクトがあり、これは <code>block_id</code> と一意な <code>action_id</code> に紐づける形で入力値を保持しています。
+
+より詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#handling_submissions">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// モーダルビューでのデータ送信イベントを処理します
+app.view('view_b', async ({ ack, body, view, context }) => {
+  // モーダルビューでのデータ送信イベントを確認
+  ack();
+
+  // 入力値を使ってやりたいことをここで実装 - ここでは DB に保存して送信内容の確認を送っている
+
+  // block_id: block_1 という input ブロック内で action_id: input_a の場合の入力
+  const val = view['state']['values']['block_1']['input_a'];
+  const user = body['user']['id'];
+
+  // ユーザーに対して送信するメッセージ
+  let msg = '';
+  // DB に保存
+  const results = await db.set(user.input, val);
+
+  if (results) {
+    // DB への保存が成功
+    msg = 'Your submission was successful';
+  } else {
+    msg = 'There was an error with your submission';
+  }
+
+  // ユーザーにメッセージを送信
+  try {
+    app.client.chat.postMessage({
+      token: context.botToken,
+      channel: user,
+      text: msg
+    });
+  }
+  catch (error) {
+    console.error(error);
+  }
+
+});
+```

docs/_basic/ja_listening_responding_options.md

@@ -2,15 +2,15 @@
 title: オプションのリスニングと応答
 lang: ja-jp
 slug: options
-order: 9
+order: 12
 ---
 
 <div class="section-content">
 `option()` メソッドは、Slack からの着信オプションリクエストペイロードをリッスンします。 [`actions()` と同様](#action-listening)に、 `action_id` オブジェクトまたは制約付きオブジェクトが必要です。
 
 `external_select` メニューには `action_id` を使用することをお勧めしますが、ダイアログはまだ Block Kit をサポートしていないため、制約オブジェクトを用いて `callback_id` でフィルタリングする必要があります。
 
-オプションリクエストに応答するためには、適切なオプションを指定して `ack()` を実行する必要があります。[external_select の応答の例](https://api.slack.com/reference/messaging/block-elements#external-select)も[ダイアログ応答の例](https://api.slack.com/dialogs#dynamic_select_elements_external)も API サイトで参照できます
+オプションリクエストに応答するためには、適切なオプションを指定して `ack()` を実行する必要があります。[external_select の応答の例](https://api.slack.com/reference/messaging/block-elements#external-select)も[ダイアログ応答の例](https://api.slack.com/dialogs#dynamic_select_elements_external)も API サイトで参照できます。
 </div>
 
 ```javascript

docs/_basic/ja_opening_modals.md

@@ -0,0 +1,79 @@
+---
+title: モーダルビューのオープン
+lang: ja-jp
+slug: creating-modals
+order: 9
+---
+
+<div class="section-content">
+
+<a href="https://api.slack.com/block-kit/surfaces/modals">モーダルビュー</a>は、ユーザー情報を収集したり、情報の動的な表示を実現するためのインタフェースです。モーダルビューは、適切な <code>trigger_id</code> と <a href="https://api.slack.com/reference/block-kit/views">ビュー部分のペイロード</a> を組み込みの API クライアントによる <a href="https://api.slack.com/methods/views.open"><code>views.open</code></a> メソッドの呼び出しに渡すことでオープンすることができます。
+
+<code>trigger_id</code> はコマンド、ボタンの押下、メニューの選択などによって Request URL に送信されたペイロードの項目として入手することができます。
+
+モーダルビューの作成についてのより詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#composing_modal">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// コマンド起動をリッスン
+app.command('/ticket', ({ ack, payload, context }) => {
+  // コマンドのリクエストを確認
+  ack();
+
+  try {
+    const result = app.client.views.open({
+      token: context.botToken,
+      type: 'modal',
+      // 適切な trigger_id を受け取ってから 3 秒以内に渡す
+      trigger_id: payload.trigger_id,
+      // view の値をペイロードに含む
+      view: {
+        // callback_id が view を特定するための識別子
+        callback_id: 'view_1',
+        title: {
+          type: 'plain_text',
+          text: 'Modal title'
+        },
+        blocks: [
+          {
+            type: 'section',
+            text: {
+              type: 'mrkdwn',
+              text: 'Welcome to a modal with _blocks_'
+            },
+            accessory: {
+              type: 'button',
+              text: {
+                type: 'plain_text',
+                text: 'Click me!'
+              },
+              action_id: 'button_abc'
+            }
+          },
+          {
+            type: 'input',
+            block_id: 'input_c',
+            label: {
+              type: 'plain_text',
+              text: 'What are your hopes and dreams?'
+            },
+            element: {
+              type: 'plain_text_input',
+              action_id: 'dreamy_input',
+              multiline: true
+            }
+          }
+        ],
+        submit: {
+          type: 'plain_text',
+          text: 'Submit'
+        }
+      }
+    });
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```

docs/_basic/ja_updating_pushing_modals.md

@@ -0,0 +1,62 @@
+---
+title: モーダルビューの更新と多重表示
+lang: ja-jp
+slug: updating-pushing-views
+order: 10
+---
+
+<div class="section-content">
+モーダルビューの表示は、複数のビューをスタックとして保持する場合があります。<a href="https://api.slack.com/methods/views.open">`views.open`</a> という API を呼び出すと、まずルートのモーダルビューが生成されます。その最初の呼び出しの後で、<a href="https://api.slack.com/methods/views.update">`views.update`</a> によって動的にそのビューを書き換えたり、<a href="https://api.slack.com/methods/views.push">`views.push`</a> で新しいビューをその上に積み重ねて表示したりといったことができます。
+
+<strong><code>views.update</code></strong><br>
+モーダルビューを更新するには組み込みの API クライアントを使って <code>views.update</code> を呼び出します。この API 呼び出しにはそのビューをオープンしたときに生成された <code>view_id</code> と、書き換えられた <code>blocks</code> の配列を渡します。ユーザーが既存のビューの中にある要素とインタラクションを行なったことをきっかけにビューを更新する場合は、そのリクエストの <code>body</code> に <code>view_id</code> が含まれています。
+
+<strong><code>views.push</code></strong><br>
+ビューのスタックに新しいビューを積み重ねるには、組み込みの API クライアントを使って <code>views.push</code> を呼び出します。この API 呼び出しには、適切な <code>trigger_id</code> と新しく生成する <a href="https://api.slack.com/reference/block-kit/views">ビュー部分のペイロード</a>を渡します。`views.push` の引数は <a href="#creating-modals">ビューをオープンするとき</a>と同様です。最初のモーダルビューをオープンした後、その上にさらに二つまで追加のビューをスタックに積み重ねることができます。
+
+より詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#updating_views">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// action_id: button_abc のボタンを押すイベントをリッスン
+// （そのボタンはモーダルビューの中にあるという想定）
+app.action('button_abc', ({ ack, body, context }) => {
+  // ボタンを押したイベントを確認
+  ack();
+
+  try {
+    const result = app.client.views.update({
+      token: context.botToken,
+      // リクエストに含まれる view_id を渡す
+      view_id: body.view.id,
+      // 更新された view の値をペイロードに含む
+      view: {
+        // callback_id が view を特定するための識別子
+        callback_id: 'view_1',
+        title: {
+          type: 'plain_text',
+          text: 'Updated modal'
+        },
+        blocks: [
+          {
+            type: 'section',
+            text: {
+              type: 'plain_text',
+              text: 'You updated the modal!'
+            }
+          },
+          {
+            type: 'image',
+            image_url: 'https://media.giphy.com/media/SVZGEcYt7brkFUyU90/giphy.gif',
+            alt_text: 'Yay! The modal was updated'
+          }
+        ]
+      }
+    });
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```

docs/_basic/updating_pushing_modals.md

@@ -6,7 +6,7 @@ order: 10
 ---
 
 <div class="section-content">
-Modals contain a stack of views. When you call `views.open`, 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>.
+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 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.