Add first draft of Kotlin DSL documentation

Evan Rittenhouse · Evan Rittenhouse · commit 04e88343174d · 2020-06-24T08:38:56.000-04:00
diff --git a/README.md b/README.md
@@ -61,7 +61,9 @@ All released versions are available on the Maven Central repositories. The lates
 |groupId:artifactId|Description|
 |---|---|
 |[**com.slack.api:slack-api-model**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-model)|This module is a collection of the classes representing the [Slack core objects](https://api.slack.com/types) such as conversations, messages, users, surfaces, and blocks. As this one is an essential part of the SDK, all others depend on this.|
+|[**com.slack.api:slack-api-model-kotlin-extension**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-model-kotlin-extension)|This contains the Block Kit Kotlin DSL builder, which allows you to define block kit structures via a Kotlin-native DSL.|
 |[**com.slack.api:slack-api-client**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-client)|This is a collection of the Slack API clients. The supported are Basic API Methods, RTM (Real Time Messaging) API, SCIM API, Audit Logs API, and Status API.|
+|[**com.slack.api:slack-api-client-kotlin-extension**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-client-kotlin-extension)|This contains extension methods for various slack client message builders so you can seamlessly use the Block Kit Kotlin DSL directly on the Java message builders.|
 |[**com.slack.api:slack-app-backend**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-app-backend)|This module is a set of Slack app server-side handlers and data classes for Events API, Interactive Components, Slash Commands, Actions, and OAuth flow. These are used by Bolt framework as the foundation of it in primitive layers.|
 |[**com.slack.api:bolt**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:bolt)|Bolt is a framework that offers an abstraction layer to build Slack apps safely and quickly. The most commonly used Servlet environment is supported out-of-the-box.|
 |[**com.slack.api:bolt-servlet**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:bolt-servlet)|This is an adapter for Servlet environments.|
diff --git a/docs/guides/composing-messages.md b/docs/guides/composing-messages.md
@@ -69,4 +69,147 @@ ChatPostMessageResponse response = slack.methods(token).chatPostMessage(req -> r
 );
 ```
 
-You can use this way also for building a message for Incoming Webhooks and `response_url` calls.
+You can use this way also for building a message for Incoming Webhooks and `response_url` calls.
+
+---
+## Block Kit Kotlin DSL
+
+If you're using Kotlin, the Java Slack SDK also provides Kotlin-style builders which you can use to build your block kit structures.
+
+```kotlin
+import com.slack.api.model.block.Blocks.*
+import com.slack.api.model.kotlin_extension.request.chat.blocks
+
+val response = slack.methods(token).chatPostMessage { req -> req
+    .channel("C1234567")
+    .blocks {
+        section {
+            // "text" fields can be constructed via plainText() and markdownText()
+            markdownText("*Please select a restaurant:*")
+        }
+        divider()
+        actions {
+            // To align with the JSON structure, you could put the elements { } block around the buttons but for brevity it can be omitted
+            // The same is true for things such as the section block's "accessory" container
+            button {
+                // For instances where only plain text is acceptable, the field's name can be filled with plain text inputs
+                text("Farmhouse", emoji = true)
+                value("v1")
+            }
+            button {
+                text("Kin Khao", emoji = true)
+                value("v2")
+            }
+        }
+    }
+}
+```
+
+### Installation
+
+You can add the Block Kit Kotlin DSL via 2 artifacts:
+
+  * The slack model kotlin extension, which adds the Kotlin DSL itself as well as the standalone `withBlocks { }` builder
+  * The slack client kotlin extension, which adds the `.blocks { }` extension function to various Slack Client builders for seamless use of the DSL with the Java builders
+    * The `.blocks { }` extension function is available on the following Java builders:
+      * ChatPostEphemeralRequestBuilder
+      * ChatPostMessageRequestBuilder
+      * ChatScheduleMessageRequestBuilder
+      * ChatUpdateRequestBuilder
+
+**Adding via Gradle:**
+
+```groovy
+dependencies {
+    implementation "com.slack.api:slack-api-model-kotlin-extension:{{ site.sdkLatestVersion }}"
+    implementation "com.slack.api:slack-api-client-kotlin-extension:{{ site.sdkLatestVersion }}"
+}
+```
+
+**Adding via Gradle Kotlin DSL:**
+
+```kotlin
+dependencies {
+    implementation("com.slack.api:slack-api-model-kotlin-extension:{{ site.sdkLatestVersion }}")
+    implementation("com.slack.api:slack-api-client-kotlin-extension:{{ site.sdkLatestVersion }}")
+}
+```
+
+### Notable examples and features
+
+**Standalone withBlocks builder which comes with the model extension**:
+
+```kotlin
+import com.slack.api.model.kotlin_extension.block.withBlocks
+
+val constructedMessage = withBlocks {
+    section {
+        plainText("Now this can be passed to anything that requires a list of LayoutBlocks")
+    }
+}
+```
+
+**Type safe enums for inputs which require specific string inputs**:
+
+```kotlin
+import com.slack.api.model.kotlin_extension.block.element.ButtonStyle
+import com.slack.api.model.kotlin_extension.block.element.ConversationType
+import com.slack.api.model.kotlin_extension.block.withBlocks
+
+val message = withBlocks { 
+    section { 
+        plainText("Please select the person or group you would like to send a cat GIF to.")
+
+        // "accessory" is provided here, but it can be omitted for brevity
+        accessory { 
+            conversationsSelect { 
+                // Or alternatively, provide strings via filter("im", "mpim") if you'd prefer
+                filter(ConversationType.IM, ConversationType.MULTIPARTY_IM)
+                placeholder("Where should we send the cat?")
+                
+                confirm { 
+                    title("Confirm destination")
+                    plainText("Are you sure you want to send a cat GIF to this person or group?")
+                    confirm("Yes, send it")
+                    deny("Don't send it")
+                    
+                    style(ButtonStyle.PRIMARY)
+                }
+            }
+        }
+    }
+}
+```
+
+**Write DSL extension functions for message templating**:
+
+```kotlin
+import com.slack.api.model.kotlin_extension.block.ActionsBlockBuilder
+import com.slack.api.model.kotlin_extension.block.withBlocks
+
+fun ActionsBlockBuilder.presentOptions(vararg optionNames: String, prompt: String? = null) {
+    staticSelect { 
+        if (prompt != null) {
+            placeholder(prompt)
+        }
+        
+        options {
+            for (optionName in optionNames) {
+                option {
+                    plainText(optionName)
+                    value(optionName.toLowerCase())
+                }
+            }
+        }
+    }
+}
+
+val message = withBlocks { 
+    section {
+        markdownText("Please select your favorite color.")
+    }
+    actions {
+        presentOptions("Green", "Red", "Blue", "Yellow", "Orange", "Black", prompt = "Pick a color...")
+    }
+}
+```
diff --git a/docs/guides/web-api-basics.md b/docs/guides/web-api-basics.md
@@ -127,6 +127,8 @@ val response = slack.methods(token).chatPostMessage { it
 }
 ```
 
+In addition, you can check out the [Block Kit Kotlin DSL]({{ site.url | append: site.baseurl }}/guides/composing-messages#block-kit-kotlin-dsl) for a Kotlin-native way of constructing rich messages.
+
 ### Handle Responses
 
 If you're not yet familiar with the Slack Web API response format, read the [Evaluating responses](https://api.slack.com/web#responses) guide to understand it. All Web API responses contain a JSON object, which always contains a top-level boolean property `"ok"`, indicating success or failure.
diff --git a/docs/guides/web-api-client-setup.md b/docs/guides/web-api-client-setup.md
@@ -134,6 +134,10 @@ dependencies {
   implementation(platform("org.jetbrains.kotlin:kotlin-bom"))
   implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
   implementation("com.slack.api:slack-api-client:{{ site.sdkLatestVersion }}")
+
+  // Add these dependencies if you want to use the Kotlin DSL for building rich messages
+  implementation("com.slack.api:slack-api-model-kotlin-extension:{{ site.sdkLatestVersion }}")
+  implementation("com.slack.api:slack-api-client-kotlin-extension:{{ site.sdkLatestVersion }}")
 }
 application {
   mainClassName = "ExampleKt" // add "Kt" suffix for main function source file
diff --git a/docs/index.md b/docs/index.md
@@ -28,7 +28,9 @@ All released versions are available on the Maven Central repositories. The lates
 |[**com.slack.api:bolt-micronaut**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:bolt-micronaut) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/bolt-micronaut/{{ site.sdkLatestVersion }}/bolt-micronaut-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|This is an adapter for [Micronaut](https://micronaut.io/) to run Bolt apps on top of it.|
 |[**com.slack.api:bolt-helidon**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:bolt-helidon) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/bolt-helidon/{{ site.sdkLatestVersion }}/bolt-helidon-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|This is an adapter for [Helidon SE](https://helidon.io/docs/latest/) to run Bolt apps on top of it.|
 |[**com.slack.api:slack-api-model**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-model) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-model/{{ site.sdkLatestVersion }}/slack-api-model-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|This is a collection of the classes representing the [Slack core objects](https://api.slack.com/types) such as conversations, messages, users, blocks, and surfaces. As this is an essential part of the SDK, all other modules depend on this.|
+|[**com.slack.api:slack-api-model-kotlin-extension**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-model-kotlin-extension)|This contains the Block Kit Kotlin DSL builder, which allows you to define block kit structures via a Kotlin-native DSL.|
 |[**com.slack.api:slack-api-client**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-client) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-client/{{ site.sdkLatestVersion }}/slack-api-client-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|This is a collection of the Slack API clients. The supported are Basic API Methods, RTM (Real Time Messaging) API, SCIM API, Audit Logs API, and Status API.|
+|[**com.slack.api:slack-api-client-kotlin-extension**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-api-client-kotlin-extension)|This contains extension methods for various slack client message builders so you can seamlessly use the Block Kit Kotlin DSL directly on the Java message builders.|
 |[**com.slack.api:slack-app-backend**](https://search.maven.org/search?q=g:com.slack.api%20AND%20a:slack-app-backend) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-app-backend/{{ site.sdkLatestVersion }}/slack-app-backend-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|This module is a set of Slack app server-side handlers and data classes for Events API, Interactive Components, Slash Commands, Actions, and OAuth flow. These are used by Bolt framework as the foundation of it in primitive layers.|
 
 ---

Original file line number	Diff line number	Diff line change
`@@ -127,6 +127,8 @@ val response = slack.methods(token).chatPostMessage { it`
`127`	`127`	`}`
`128`	`128`	```
`129`	`129`
	`130`	`+In addition, you can check out the [Block Kit Kotlin DSL]({{ site.url \| append: site.baseurl }}/guides/composing-messages#block-kit-kotlin-dsl) for a Kotlin-native way of constructing rich messages.`
	`131`	`+`
`130`	`132`	`### Handle Responses`
`131`	`133`
`132`	`134`	If you're not yet familiar with the Slack Web API response format, read the [Evaluating responses](https://api.slack.com/web#responses) guide to understand it. All Web API responses contain a JSON object, which always contains a top-level boolean property `"ok"`, indicating success or failure.