HTMXの統合
必要な依存関係: io.ktor:ktor-htmx, io.ktor:ktor-htmx-html, io.ktor:ktor-server-htmx
コード例: htmx-integration
HTMX は、HTML属性を使用して動的なクライアント側の動作を可能にする軽量なJavaScriptライブラリです。JavaScriptを記述することなく、AJAX、CSSトランジション、WebSocket、Server-Sent Eventsなどの機能をサポートします。
Ktorは、サーバーとクライアントの両方のコンテキストで統合を簡素化する一連の共有モジュールを通じて、HTMXに対する実験的なファーストクラスのサポートを提供します。これらのモジュールは、HTMXヘッダーの操作、Kotlin DSLを使用したHTML属性の定義、サーバー上でのHTMX固有のルーティングロジックの処理を行うためのツールを提供します。
モジュールの概要
KtorのHTMXサポートは、3つの実験的モジュールで利用できます。
| モジュール | 説明 |
|---|---|
ktor-htmx | コア定義とヘッダー定数 |
ktor-htmx-html | Kotlin HTML DSLとの統合 |
ktor-server-htmx | HTMX固有のリクエストに対するルーティングサポート |
すべてのAPIには @ExperimentalKtorApi のマークが付けられており、@OptIn(ExperimentalKtorApi::class) によるオプトインが必要です。
HTMXヘッダー
コアの ktor-htmx モジュールの定義済み定数を使用して、型安全な方法でHTMXヘッダーにアクセスまたは設定できます。これらの定数を使用することで、トリガー、履歴の復元、コンテンツの置換(スワップ)などのHTMXの動作を検出する際にマジックストリングを回避できます。
リクエストヘッダー
アプリケーションでHTMXリクエストヘッダーを読み取ったりマッチングしたりするには、HxRequestHeaders オブジェクトを使用します。
trueレスポンスヘッダー
HTMXレスポンスヘッダーの定数にアクセスするには、HxResponseHeaders オブジェクトを使用できます。
スワップモード
コアの ktor-htmx モジュールの HxSwap オブジェクトを使用して、さまざまなHTMXスワップモードの定数にアクセスできます。
HTML DSL拡張
ktor-htmx-html モジュールは、KotlinのHTML DSLに拡張関数を追加し、HTML要素に直接HTMX属性を追加できるようにします。
@OptIn(ExperimentalKtorApi::class)
html {
body {
button {
attributes.hx {
get = "/data"
target = "#result"
swap = HxSwap.outerHtml
trigger = "click"
}
+"Load Data"
}
}
}上記の例は、HTMX属性を持つHTMLを生成します。
<button hx-get="/api/data" hx-target="#result-div" hx-swap="outerHTML" hx-trigger="click">Load Data</button>サーバー側のルーティング
ktor-server-htmx モジュールは、hx DSLブロックを通じてHTMXを認識するルーティングを提供します。
@OptIn(ExperimentalKtorApi::class)
routing {
route("api") {
// 通常のルート(HTMXリクエストと非HTMXリクエストの両方)
get {
call.respondText("Regular response")
}
// HTMXリクエストにのみ一致(HX-Requestヘッダーが存在する場合)
hx.get {
call.respondText("HTMX response")
}
// 特定のターゲットを持つHTMXリクエストに一致
hx {
target("#result-div") {
get {
call.respondText("Response for #result-div")
}
}
// 特定のトリガーを持つHTMXリクエストに一致
trigger("#load-button") {
get {
call.respondText("Response for #load-button clicks")
}
}
}
}
}これらの機能により、クライアントから送信されたHTMXヘッダーに応じて、アプリケーションが異なる応答を返すことができるようになります。
