Merge pull request #503 from emanguy/kotlin-dsl-docs

seratch · web-flow · commit 3058558e38c5 · 2020-07-13T15:08:52.000+09:00
Add Kotlin DSL documentation (English)
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/app-home.md b/docs/guides/app-home.md
@@ -101,6 +101,26 @@ app.event(AppHomeOpenedEvent::class.java) { event, ctx ->
 }
 ```
 
+You can also build the view in the above example with the [Block Kit Kotlin DSL]({{ site.url | append: site.baseurl }}/guides/composing-messages#block-kit-kotlin-dsl) like so:
+
+```kotlin
+// These imports are necessary for this code
+import com.slack.api.model.kotlin_extension.view.blocks
+import com.slack.api.model.view.Views.view
+
+val appHomeView = view {
+     it.type("home")
+     .blocks { 
+        section {
+          markdownText(":wave: Hello, App Home! (Last updated: ${now}")
+        }
+        image {
+          imageUrl("https://www.example.com/foo.png")
+        }
+     }
+}
+```
+
 ### Under the Hood
 
 Refer to [the Events API guide]({{ site.url | append: site.baseurl }}/guides/events-api).
diff --git a/docs/guides/composing-messages.md b/docs/guides/composing-messages.md
@@ -69,4 +69,156 @@ 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.Slack
+import com.slack.api.model.block.Blocks.*
+import com.slack.api.model.kotlin_extension.request.chat.blocks
+
+val slack = Slack.getInstance()
+val token = System.getenv("token")
+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-api-model` Kotlin extension, which adds the Kotlin DSL itself as well as the standalone `withBlocks { }` builder and `View.ViewBuilder`'s `.blocks { }` extension function
+  * The `slack-api-client` Kotlin extension, which adds the `.blocks { }` extension function to `MethodsClient`'s request object 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**:
+
+You can create lists of blocks outside of the `slack-api-client` Kotlin extension functions with the `withBlocks { }` builder.
+
+```kotlin
+import com.slack.api.model.kotlin_extension.block.withBlocks
+
+val blocks = 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**:
+
+Type-safe enums are available for properties of some block elements which require specific input strings. With this, you get the benefit of verifying your inputs are correct at compile time and you gain access to Kotlin enum features such as being able to iterate over or retrieve all possible values for these inputs. Versions of these inputs which accept strings are also available, if you prefer.
+
+```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 blocks = 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**:
+
+Because it is a Kotlin DSL, you benefit from Kotlin language features while you are constructing your messages, one of which being able to create extension functions which reproduce common Block Kit structures. This makes your code less repetitive and easier to read. You also benefit from being able to use conditionals and loops as you construct your blocks.
+
+```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 blocks = 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/modals.md b/docs/guides/modals.md
@@ -228,6 +228,57 @@ val res = ctx.client().viewsOpen { it
 }
 ```
 
+Alternatively, you can use the [Block Kit DSL]({{ site.url | append: site.baseurl }}/guides/composing-messages#block-kit-kotlin-dsl) in conjunction with the Java Builder to construct your view. The Java example above would look like this in Kotlin:
+
+```kotlin
+import com.slack.api.model.kotlin_extension.view.blocks
+import com.slack.api.model.view.Views.*
+
+fun buildView(): View {
+  return view { thisView -> thisView
+          .callbackId("meeting-arrangement")
+          .type("modal")
+          .notifyOnClose(true)
+          .title(viewTitle { it.type("plain_text").text("Meeting Arrangement").emoji(true) })
+          .submit(viewSubmit { it.type("plain_text").text("Submit").emoji(true) })
+          .close(viewClose { it.type("plain_text").text("Cancel").emoji(true) })
+          .privateMetadata("""{"response_url":"https://hooks.slack.com/actions/T1ABCD2E12/330361579271/0dAEyLY19ofpLwxqozy3firz"}""")
+          .blocks {
+            section {
+              blockId("category-block")
+              markdownText("Select a category of the meeting!")
+              staticSelect { 
+                actionId("category-selection-action")
+                placeholder("Select a category")
+                options {
+                  option {
+                    description("Customer")
+                    value("customer")
+                  }
+                  option {
+                    description("Partner")
+                    value("partner")
+                  }
+                  option {
+                    description("Internal")
+                    value("internal")
+                  }
+                }
+              }
+            }
+            input {
+              blockId("agenda-block")
+              plainTextInput { 
+                actionId("agenda-action")
+                multiline(true)
+              }
+              label("Detailed Agenda", emoji = true)
+            }
+          }
+  }
+}
+```
+
 ### `"block_actions"` requests
 
 Basically it's the same with [Interactive Components]({{ site.url | append: site.baseurl }}/guides/interactive-components) but the only difference is that a payload coming from a modal has `view` and also its `private_metadata`
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
@@ -35,7 +35,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) [📖](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.