Merge pull request #374 from shanedewael/add-block-kit-example

Add Block Kit example to docs

Author: shaydewael

docs-src/basic_usage.rst

@@ -59,6 +59,55 @@ See `chat.postEphemeral <https://api.slack.com/methods/chat.postEphemeral>`_ for
 
 --------
 
+Customizing a message's layout
+-----------------------
+The chat.postMessage method takes an optional blocks argument that allows you to customize the layout of a message. 
+Blocks for Web API methods are all specified in a single object literal, so just add additional keys for any optional argument.
+
+To send a message to a channel, use the channel's ID. For IMs, use the user's ID.
+
+.. code-block:: python
+
+  sc.api_call(
+    "chat.postMessage",
+    channel="C0XXXXXX",
+    blocks=[
+      {
+          "type": "section",
+          "text": {
+              "type": "mrkdwn",
+              "text": "Danny Torrence left the following review for your property:"
+          }
+      },
+      {
+          "type": "section",
+          "text": {
+              "type": "mrkdwn",
+              "text": "<https://example.com|Overlook Hotel> \n :star: \n Doors had too many axe holes, guest in room " +
+              "237 was far too rowdy, whole place felt stuck in the 1920s."
+          },
+          "accessory": {
+              "type": "image",
+              "image_url": "https://images.pexels.com/photos/750319/pexels-photo-750319.jpeg",
+              "alt_text": "Haunted hotel image"
+          }
+      },
+      {
+          "type": "section",
+          "fields": [
+              {
+                  "type": "mrkdwn",
+                  "text": "*Average Rating*\n1.0"
+              }
+          ]
+      }
+    ]
+  )
+
+**Note:** You can use the `Block Kit Builder <https://api.slack.com/tools/block-kit-builder>`for a playground where you can prototype your message's look and feel.
+
+--------
+
 Replying to messages and creating threads
 ------------------------------------------
 Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context

docs/about.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/auth.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/basic_usage.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#deleting-a-message">Deleting a message</a></li>
@@ -202,6 +203,51 @@ <h2>Sending a message<a class="headerlink" href="#sending-a-message" title="Perm
 <p>See <a class="reference external" href="https://api.slack.com/methods/chat.postEphemeral">chat.postEphemeral</a> for more info.</p>
 </div>
 <hr class="docutils" />
+<div class="section" id="customizing-a-message-s-layout">
+<h2>Customizing a message’s layout<a class="headerlink" href="#customizing-a-message-s-layout" title="Permalink to this headline">¶</a></h2>
+<p>The chat.postMessage method takes an optional blocks argument that allows you to customize the layout of a message.
+Blocks for Web API methods are all specified in a single object literal, so just add additional keys for any optional argument.</p>
+<p>To send a message to a channel, use the channel’s ID. For IMs, use the user’s ID.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">sc</span><span class="o">.</span><span class="n">api_call</span><span class="p">(</span>
+  <span class="s2">&quot;chat.postMessage&quot;</span><span class="p">,</span>
+  <span class="n">channel</span><span class="o">=</span><span class="s2">&quot;C0XXXXXX&quot;</span><span class="p">,</span>
+  <span class="n">blocks</span><span class="o">=</span><span class="p">[</span>
+    <span class="p">{</span>
+        <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;section&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="p">{</span>
+            <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;mrkdwn&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="s2">&quot;Danny Torrence left the following review for your property:&quot;</span>
+        <span class="p">}</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+        <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;section&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="p">{</span>
+            <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;mrkdwn&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;https://example.com|Overlook Hotel&gt; </span><span class="se">\n</span><span class="s2"> :star: </span><span class="se">\n</span><span class="s2"> Doors had too many axe holes, guest in room &quot;</span> <span class="o">+</span>
+            <span class="s2">&quot;237 was far too rowdy, whole place felt stuck in the 1920s.&quot;</span>
+        <span class="p">},</span>
+        <span class="s2">&quot;accessory&quot;</span><span class="p">:</span> <span class="p">{</span>
+            <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;image&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;image_url&quot;</span><span class="p">:</span> <span class="s2">&quot;https://images.pexels.com/photos/750319/pexels-photo-750319.jpeg&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;alt_text&quot;</span><span class="p">:</span> <span class="s2">&quot;Haunted hotel image&quot;</span>
+        <span class="p">}</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+        <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;section&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;fields&quot;</span><span class="p">:</span> <span class="p">[</span>
+            <span class="p">{</span>
+                <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;mrkdwn&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="s2">&quot;*Average Rating*</span><span class="se">\n</span><span class="s2">1.0&quot;</span>
+            <span class="p">}</span>
+        <span class="p">]</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Note:</strong> You can use the <a href="#id1"><span class="problematic" id="id2">`</span></a>Block Kit Builder &lt;<a class="reference external" href="https://api.slack.com/tools/block-kit-builder">https://api.slack.com/tools/block-kit-builder</a>&gt;`for a playground where you can prototype your message’s look and feel.</p>
+</div>
+<hr class="docutils" />
 <div class="section" id="replying-to-messages-and-creating-threads">
 <h2>Replying to messages and creating threads<a class="headerlink" href="#replying-to-messages-and-creating-threads" title="Permalink to this headline">¶</a></h2>
 <p>Threaded messages are just like regular messages, except thread replies are grouped together to provide greater context

docs/changelog.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/conversations.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/faq.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/genindex.html

@@ -68,6 +68,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/index.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

docs/metadata.html

@@ -67,6 +67,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>
+<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#customizing-a-message-s-layout">Customizing a message’s layout</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#replying-to-messages-and-creating-threads">Replying to messages and creating threads</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>
 <li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>