Skip to content

HTML DSL ​

必要な依存関係: io.ktor:ktor-server-html-builder

コード例: html

NativeサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

HTML DSLは、kotlinx.htmlライブラリをKtorに統合し、HTMLブロックを使用してクライアントに応答できるようにします。HTML DSLを使用すると、Kotlinで純粋なHTMLを記述したり、変数をビューに埋め込んだり、テンプレートを使用して複雑なHTMLレイアウトを構築したりすることができます。

依存関係の追加 ​

HTML DSLはインストールを必要としませんが、ktor-server-html-builderアーティファクトが必要です。次のようにビルドスクリプトに含めることができます。

kotlin
implementation(ktorLibs.server.htmlBuilder)
上記のスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
groovy
implementation ktorLibs.server.htmlBuilder
上記のスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-html-builder-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

レスポンスでHTMLを送信する ​

HTMLレスポンスを送信するには、必要なルート(route)内でrespondHtmlメソッドを呼び出します。 以下の例は、HTML DSLのサンプルと、クライアントに送信される対応するHTMLを示しています。

kotlin
import io.ktor.server.application.*
import io.ktor.server.html.*
import io.ktor.http.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.utils.io.*
import kotlinx.html.*

fun Application.module() {
    routing {
        get("/") {
            val name = "Ktor"
            call.respondHtml(HttpStatusCode.OK) {
                head {
                    title {
                        +name
                    }
                }
                body {
                    h1 {
                        +"Hello from $name!"
                    }
                }
            }
        }
    }
}
html
<html>
<head>
    <title>Ktor</title>
</head>
<body>
<h1>Hello from Ktor!</h1>
</body>
</html>

次の例は、ユーザーから認証情報を収集するために使用されるHTMLフォームで応答する方法を示しています。

kotlin
get("/login") {
    call.respondHtml {
        body {
            val urlEncoded = FormEncType
                .applicationXWwwFormUrlEncoded
            form(
                action = "/login",
                encType = urlEncoded,
                method = FormMethod.post
            ) {
                p {
                    +"Username:"
                    textInput(name = "username")
                }
                p {
                    +"Password:"
                    passwordInput(name = "password")
                }
                p {
                    submitInput() { value = "Login" }
                }
            }
        }
    }
}
html
<html>
<body>
<form action="/login" enctype="application/x-www-form-urlencoded" method="post">
    <p>Username:<input type="text" name="username"></p>
    <p>Password:<input type="password" name="password"></p>
    <p><input type="submit" value="Login"></p>
</form>
</body>
</html>

完全な例については、auth-form-html-dslを参照してください。

サーバー側でのフォームパラメーターの受け取りについての詳細は、フォームパラメーターを参照してください。

kotlinx.htmlを使用したHTMLの生成についての詳細は、kotlinx.html wikiを参照してください。

部分的なHTMLの送信 ​

完全なHTMLドキュメントの生成に加えて、.respondHtmlPartial()関数を使用してHTMLフラグメント(断片)で応答することもできます。

HTMLフラグメントは、HTMXのようなライブラリで使用される動的更新など、完全な<html>ドキュメントを必要としない部分的なマークアップを返す場合に役立ちます。

kotlin
import io.ktor.server.application.*
import io.ktor.server.html.*
import io.ktor.http.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.utils.io.*
import kotlinx.html.*

fun Application.module() {
    routing {
        get("/fragment") {
            call.respondHtmlPartial(HttpStatusCode.Created) {
                div("fragment") {
                    span { +"Created!" }
                }
            }
        }
    }
}
html
<div class="fragment">
    <span>
        Created!
    </span>
</div>

この関数は.respondHtml()と同様に機能しますが、ルートHTML要素を追加せず、ビルダー内で定義したコンテンツのみをレンダリングします。

テンプレート ​

プレーンなHTMLの生成に加えて、Ktorは複雑なレイアウトを構築するために使用できるテンプレートエンジンを提供しています。ページ全体用のルートテンプレート、ページヘッダーやフッター用の子テンプレートなど、HTMLページのさまざまな部分に対してテンプレートの階層を作成できます。Ktorは、テンプレートを操作するための次のAPIを公開しています。

  1. 指定されたテンプレートに基づいて構築されたHTMLで応答するには、respondHtmlTemplateメソッドを呼び出します。
  2. テンプレートを作成するには、Templateインターフェースを実装し、HTMLを提供するTemplate.applyメソッドをオーバーライドする必要があります。
  3. 作成したテンプレートクラス内では、さまざまなコンテンツタイプに対応するプレースホルダーを定義できます。
    • Placeholderはコンテンツを挿入するために使用されます。PlaceholderListは、複数回出現するコンテンツ(リスト項目など)を挿入するために使用できます。
    • TemplatePlaceholderは、子テンプレートを挿入してネストされたレイアウトを作成するために使用できます。

例 ​

テンプレートを使用して階層的なレイアウトを作成する方法の例を見てみましょう。次のようなHTMLがあるとします。

html
<body>
<h1>Ktor</h1>
<article>
    <h2>Hello from Ktor!</h2>
    <p>Kotlin Framework for creating connected systems.</p>
    <ul>
       <li><b>One</b></li>
       <li>Two</li>
    </ul>
</article>
</body>

このページのレイアウトは2つの部分に分割できます。

  • ページヘッダー用のルートレイアウトテンプレートと記事用の子テンプレート。
  • 記事コンテンツ用の子テンプレート。

これらのレイアウトを段階的に実装してみましょう。

  1. respondHtmlTemplateメソッドを呼び出し、パラメーターとしてテンプレートクラスを渡します。この場合、Templateインターフェースを実装する必要があるLayoutTemplateクラスになります。

    kotlin
    get("/") {
        call.respondHtmlTemplate(LayoutTemplate()) {
            // ...
        }
    }

    ブロック内では、テンプレートにアクセスしてそのプロパティ値を指定できます。これらの値は、テンプレートクラスで指定されたプレースホルダーを置き換えます。次のステップでLayoutTemplateを作成し、そのプロパティを定義します。

  2. ルートレイアウトテンプレートは次のようになります。

    kotlin
    class LayoutTemplate: Template<HTML> {
        val header = Placeholder<FlowContent>()
        val content = TemplatePlaceholder<ArticleTemplate>()
        override fun HTML.apply() {
            body {
                h1 {
                    insert(header)
                }
                insert(ArticleTemplate(), content)
            }
        }
    }

    このクラスは2つのプロパティを公開します。

    • headerプロパティは、h1タグ内に挿入されるコンテンツを指定します。
    • contentプロパティは、記事コンテンツ用の子テンプレートを指定します。
  3. 子テンプレートは次のようになります。

    kotlin
    class ArticleTemplate : Template<FlowContent> {
        val articleTitle = Placeholder<FlowContent>()
        val articleText = Placeholder<FlowContent>()
        val list = TemplatePlaceholder<ListTemplate>()
        override fun FlowContent.apply() {
            article {
                h2 {
                    insert(articleTitle)
                }
                p {
                    insert(articleText)
                }
                insert(ListTemplate(), list)
            }
        }
    }

    このテンプレートはarticleTitle、articleText、listプロパティを公開し、それらの値はarticleの内部に挿入されます。

  4. テンプレートとして値のリストを提供するには、次のように新しいクラスを作成します。

    kotlin
    class ListTemplate : Template<FlowContent> {
        val item = PlaceholderList<UL, FlowContent>()
        override fun FlowContent.apply() {
            if (!item.isEmpty()) {
                ul {
                    each(item) {
                        li {
                            if (it.first) {
                                b {
                                    insert(it)
                                }
                            } else {
                                insert(it)
                            }
                        }
                    }
                }
            }
        }
    }

    このテンプレートは、PlaceholderListクラスを使用して、提供された項目から順不同リスト(UL)を生成します。 また、強調のために最初の項目を<b>要素でラップします。

  5. これで、指定したプロパティ値を使用して構築されたHTMLを送信する準備が整いました。

    kotlin
    get("/") {
        call.respondHtmlTemplate(LayoutTemplate()) {
            header {
                +"Ktor"
            }
            content {
                articleTitle {
                    +"Hello from Ktor!"
                }
                articleText {
                    +"Kotlin Framework for creating connected systems."
                }
                list {
                    item { +"One" }
                    item { +"Two" }
                }
            }
        }
    }

完全な例はこちらで確認できます: html-templates。