Skip to content

Commit 9529042

Browse files
seratchseratch
committed
Add Japanese version of #503 
1 parent 519a161 commit 9529042

File tree

10 files changed

+313
-155
lines changed

10 files changed

+313
-155
lines changed

‎docs/guides/app-home.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -108,16 +108,16 @@ You can also build the view in the above example with the [Block Kit Kotlin DSL]
108108
import com.slack.api.model.kotlin_extension.view.blocks
109109
import com.slack.api.model.view.Views.view
110110

111-
val appHomeView = view {
112-
it.type("home")
113-
.blocks {
114-
section {
115-
markdownText(":wave: Hello, App Home! (Last updated: ${now}")
116-
}
117-
image {
118-
imageUrl("https://www.example.com/foo.png")
119-
}
120-
}
111+
val appHomeView = view { it
112+
.type("home")
113+
.blocks {
114+
section {
115+
markdownText(":wave: Hello, App Home! (Last updated: ${now}")
116+
}
117+
image {
118+
imageUrl("https://www.example.com/foo.png")
119+
}
120+
}
121121
}
122122
```
123123

‎docs/guides/composing-messages.md‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -87,15 +87,15 @@ val response = slack.methods(token).chatPostMessage { req -> req
8787
.channel("C1234567")
8888
.blocks {
8989
section {
90-
// "text" fields can be constructed via plainText() and markdownText()
90+
// "text" fields can be constructed via `plainText()` and `markdownText()`
9191
markdownText("*Please select a restaurant:*")
9292
}
9393
divider()
9494
actions {
95-
// To align with the JSON structure, you could put the elements { } block around the buttons but for brevity it can be omitted
95+
// To align with the JSON structure, you could put the `elements { }` block around the buttons but for brevity it can be omitted
9696
// The same is true for things such as the section block's "accessory" container
9797
button {
98-
// For instances where only plain text is acceptable, the field's name can be filled with plain text inputs
98+
// For instances where only `plain_text` is acceptable, the field's name can be filled with `plain_text` inputs
9999
text("Farmhouse", emoji = true)
100100
value("v1")
101101
}
@@ -112,13 +112,10 @@ val response = slack.methods(token).chatPostMessage { req -> req
112112

113113
You can add the Block Kit Kotlin DSL via 2 artifacts:
114114

115-
* 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
116-
* 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
117-
* The `.blocks { }` extension function is available on the following Java builders:
118-
* ChatPostEphemeralRequestBuilder
119-
* ChatPostMessageRequestBuilder
120-
* ChatScheduleMessageRequestBuilder
121-
* ChatUpdateRequestBuilder
115+
|artifactId|Description|
116+
|---|---|
117+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-model-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-model-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|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.|
118+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-client-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-client-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|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 such as **ChatPostEphemeralRequestBuilder**, **ChatPostMessageRequestBuilder**, **ChatScheduleMessageRequestBuilder**, and **ChatUpdateRequestBuilder**.|
122119

123120
**Adding via Gradle:**
124121

@@ -140,9 +137,11 @@ dependencies {
140137

141138
### Notable examples and features
142139

143-
**Standalone withBlocks builder which comes with the model extension**:
140+
In this section, I'll share some code snippets demonstrating how to use this DSL.
144141

145-
You can create lists of blocks outside of the `slack-api-client` Kotlin extension functions with the `withBlocks { }` builder.
142+
#### Standalone `withBlocks { }` builder which comes with the model extension
143+
144+
You can create lists of blocks outside of the **slack-api-client** Kotlin extension functions with the `withBlocks { }` builder.
146145

147146
```kotlin
148147
import com.slack.api.model.kotlin_extension.block.withBlocks
@@ -154,9 +153,11 @@ val blocks = withBlocks {
154153
}
155154
```
156155

157-
**Type safe enums for inputs which require specific string inputs**:
156+
#### Type safe enums for inputs which require specific string inputs
157+
158+
Type-safe enums are available for properties of some block elements which require specific input strings.
158159

159-
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.
160+
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.
160161

161162
```kotlin
162163
import com.slack.api.model.kotlin_extension.block.element.ButtonStyle
@@ -170,7 +171,7 @@ val blocks = withBlocks {
170171
// "accessory" is provided here, but it can be omitted for brevity
171172
accessory {
172173
conversationsSelect {
173-
// Or alternatively, provide strings via filter("im", "mpim") if you'd prefer
174+
// Or alternatively, provide strings via `filter("im", "mpim")` if you'd prefer
174175
filter(ConversationType.IM, ConversationType.MULTIPARTY_IM)
175176
placeholder("Where should we send the cat?")
176177

@@ -188,7 +189,7 @@ val blocks = withBlocks {
188189
}
189190
```
190191

191-
**Write DSL extension functions for message templating**:
192+
#### Write DSL extension functions for message templating
192193

193194
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.
194195

@@ -218,7 +219,10 @@ val blocks = withBlocks {
218219
markdownText("Please select your favorite color.")
219220
}
220221
actions {
221-
presentOptions("Green", "Red", "Blue", "Yellow", "Orange", "Black", prompt = "Pick a color...")
222+
presentOptions(
223+
"Green", "Red", "Blue", "Yellow", "Orange", "Black",
224+
prompt = "Pick a color..."
225+
)
222226
}
223227
}
224228
```

‎docs/guides/ja/app-home.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,26 @@ app.event(AppHomeOpenedEvent::class.java) { event, ctx ->
101101
}
102102
```
103103

104+
また、 Kotlin で開発しているなら、上記の例を [Block Kit Kotlin DSL]({{ site.url | append: site.baseurl }}/guides/composing-messages#block-kit-kotlin-dsl) を使って以下のように実装することもできます。
105+
106+
```kotlin
107+
// これらの import が必要です
108+
import com.slack.api.model.kotlin_extension.view.blocks
109+
import com.slack.api.model.view.Views.view
110+
111+
val appHomeView = view { it
112+
.type("home")
113+
.blocks {
114+
section {
115+
markdownText(":wave: Hello, App Home! (Last updated: ${now}")
116+
}
117+
image {
118+
imageUrl("https://www.example.com/foo.png")
119+
}
120+
}
121+
}
122+
```
123+
104124
### Bolt がやっていること
105125

106126
「[イベント API]({{ site.url | append: site.baseurl }}/guides/ja/events-api)」の同項目を参照してください。

‎docs/guides/ja/composing-messages.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,159 @@ ChatPostMessageResponse response = slack.methods(token).chatPostMessage(req -> r
7070
```
7171

7272
このビルダーは Incoming Webhooks や `response_url` を使った返信の投稿でも利用することができます。
73+
74+
---
75+
## Block Kit Kotlin DSL
76+
77+
もし Kotlin で開発しているなら、この Java SDK は Block Kit の構造を Kotlin らしいやり方で構築できるビルダーモジュールも提供しています。
78+
79+
```kotlin
80+
import com.slack.api.Slack
81+
import com.slack.api.model.block.Blocks.*
82+
import com.slack.api.model.kotlin_extension.request.chat.blocks
83+
84+
val slack = Slack.getInstance()
85+
val token = System.getenv("token")
86+
val response = slack.methods(token).chatPostMessage { req -> req
87+
.channel("C1234567")
88+
.blocks {
89+
section {
90+
// "text" フィールドは plainText() や markdownText() を使って構築できます
91+
markdownText("*Please select a restaurant:*")
92+
}
93+
divider()
94+
actions {
95+
// JSON の構造と揃えるなら、ここに elements { } のブロックを置くこともできますが、省略しても構いません
96+
// これは section ブロックの accessory についても同様です
97+
button {
98+
// plain_text だけを受け付けている場合は、plain_text 型の入力だけを受け付けます
99+
text("Farmhouse", emoji = true)
100+
value("v1")
101+
}
102+
button {
103+
text("Kin Khao", emoji = true)
104+
value("v2")
105+
}
106+
}
107+
}
108+
}
109+
```
110+
111+
### Kotlin DSL モジュールのインストール
112+
113+
Block Kit Kotlin DSL は、以下の二つの artifact で提供されています:
114+
115+
|artifactId|Description|
116+
|---|---|
117+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-model-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-model-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|**slack-api-model** の Kotlin 拡張で Kotlin DSL そのものに加えて `withBlocks { }` というどこでも使えるビルダーを提供します。<br/><br/>また `View.ViewBuilder` に `.blocks { }` 拡張関数も追加します。|
118+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-client-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-client-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|**slack-api-client** の Kotlin 拡張で `MethodsClient` のリクエストオブジェクトビルダーのメソッドに `.blocks { }` という拡張関数を追加して、シームレスに Kotlin DSL を使えるようにします。<br/><br/>この `.blocks { }` 拡張関数は **ChatPostEphemeralRequestBuilder**, **ChatPostMessageRequestBuilder**, **ChatScheduleMessageRequestBuilder**, **ChatUpdateRequestBuilder** で有効になります。|
119+
120+
**Gradle での設定:**
121+
122+
```groovy
123+
dependencies {
124+
implementation "com.slack.api:slack-api-model-kotlin-extension:{{ site.sdkLatestVersion }}"
125+
implementation "com.slack.api:slack-api-client-kotlin-extension:{{ site.sdkLatestVersion }}"
126+
}
127+
```
128+
129+
**Gradle Kotlin DSL での設定:**
130+
131+
```kotlin
132+
dependencies {
133+
implementation("com.slack.api:slack-api-model-kotlin-extension:{{ site.sdkLatestVersion }}")
134+
implementation("com.slack.api:slack-api-client-kotlin-extension:{{ site.sdkLatestVersion }}")
135+
}
136+
```
137+
138+
### サンプルと機能の紹介
139+
140+
ここではいくつかサンプルコードとともに DSL の機能を紹介します。
141+
142+
#### どこでも使える `withBlocks { }` ビルダー
143+
144+
**slack-api-client** の Kotlin DSL が提供する拡張関数を使えない場合でも `withBlocks { }` というビルダーの中で、この DSL を使ってブロックのリストを構築することができます。
145+
146+
```kotlin
147+
import com.slack.api.model.kotlin_extension.block.withBlocks
148+
149+
val blocks = withBlocks {
150+
section {
151+
plainText("Now this can be passed to anything that requires a list of LayoutBlocks")
152+
}
153+
}
154+
```
155+
156+
#### 型安全な enum の利用
157+
158+
特定の文字列のいずれかを指定する必要があるようなブロック要素（Block Element）の属性指定に、型安全な enum を利用することができます。
159+
160+
これを利用することでコンパイル時に値が正しいかを検証できる恩恵を受けられますし、全ての値にイテレートしてアクセスしたりといった Kotlin の enum の機能も利用することができます。文字列を指定する方が望ましい場合は、文字列を指定するバージョンのメソッドも提供されています。
161+
162+
```kotlin
163+
import com.slack.api.model.kotlin_extension.block.element.ButtonStyle
164+
import com.slack.api.model.kotlin_extension.block.element.ConversationType
165+
import com.slack.api.model.kotlin_extension.block.withBlocks
166+
167+
val blocks = withBlocks {
168+
section {
169+
plainText("Please select the person or group you would like to send a cat GIF to.")
170+
171+
// "accessory" をここで指定していますが、この階層は省略することもできます
172+
accessory {
173+
conversationsSelect {
174+
// 別のやり方として `filter("im", "mpim")` のように文字列を指定しても OK です
175+
filter(ConversationType.IM, ConversationType.MULTIPARTY_IM)
176+
placeholder("Where should we send the cat?")
177+
178+
confirm {
179+
title("Confirm destination")
180+
plainText("Are you sure you want to send a cat GIF to this person or group?")
181+
confirm("Yes, send it")
182+
deny("Don't send it")
183+
184+
style(ButtonStyle.PRIMARY)
185+
}
186+
}
187+
}
188+
}
189+
}
190+
```
191+
192+
#### DSL の拡張関数を書く
193+
194+
Kotlin DSL であるということは、メッセージを構築する際に Kotlin の言語機能の恩恵を受けられるということです。一つの例として、よく使われるような Block Kit の構造を構築するために、Kotlin の拡張関数を定義することができます。これはコードの繰り返しを減らすためだけでなく、より読みやすいコードにすることも役立ちます。また、ブロックを構築するときに条件式やループを利用したい場合にも有益でしょう。
195+
196+
```kotlin
197+
import com.slack.api.model.kotlin_extension.block.ActionsBlockBuilder
198+
import com.slack.api.model.kotlin_extension.block.withBlocks
199+
200+
fun ActionsBlockBuilder.presentOptions(vararg optionNames: String, prompt: String? = null) {
201+
staticSelect {
202+
if (prompt != null) {
203+
placeholder(prompt)
204+
}
205+
206+
options {
207+
for (optionName in optionNames) {
208+
option {
209+
plainText(optionName)
210+
value(optionName.toLowerCase())
211+
}
212+
}
213+
}
214+
}
215+
}
216+
217+
val blocks = withBlocks {
218+
section {
219+
markdownText("Please select your favorite color.")
220+
}
221+
actions {
222+
presentOptions(
223+
"Green", "Red", "Blue", "Yellow", "Orange", "Black",
224+
prompt = "Pick a color..."
225+
)
226+
}
227+
}
228+
```

‎docs/guides/ja/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,12 @@ lang: ja
3636
|groupId:artifactId|Description|
3737
|---|---|
3838
|[**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)|チャンネル、メッセージ、ユーザー、Block Kit のブロックとそれによって構成されるサーフェスエリアなど [Slack の核となるような重要なオブジェクト（英語）](https://api.slack.com/types)を表現するクラス群を提供します。|
39+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-model-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-model-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|Block Kit のデータ構造を Kotlin ネイティブな DSL を使って構築できるビルダーのモジュールを提供します。|
3940
|[**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)|様々な Slack API クライアントを提供します。サポートされているのは、API メソッド、RTM API、SCIM API、Audit Logs API、ステータス API です。|
41+
|[**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) [📖](https://oss.sonatype.org/service/local/repositories/releases/archive/com/slack/api/slack-api-client-kotlin-extension/{{ site.sdkLatestVersion }}/slack-api-client-kotlin-extension-{{ site.sdkLatestVersion }}-javadoc.jar/!/index.html#package)|Slack API クライアントのリクエストビルダーのメソッドを拡張することで、Block Kit のデータ構造を構築するための Kotlin ネイティブな DSL を直接利用できるようにするモジュールを提供します。|
4042
|[**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)|Slack アプリサーバーサイドで必要となる共通モジュールやペイロードなどのデータ構造を提供します。サポートされているのは、イベント API、インタラクティブコンポーネント、スラッシュコマンド、アクション、そして OAuth フローです。これらの機能はよりプリミティブなレイヤーとして Bolt から利用されています。|
4143

44+
4245
---
4346
## <!--Requirements--> 動作条件
4447

0 commit comments

Comments
 (0)