Experimental

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オブジェクトを使用します。

HxRequestHeaders.Request

HTMXリクエストの場合は常にtrue

HxRequestHeaders.Target

ターゲット要素のID

HxRequestHeaders.Trigger

トリガーされた要素のID

HxRequestHeaders.TriggerName

トリガーされた要素の名前

HxRequestHeaders.Boosted

hx-boost経由のリクエストを示す

HxRequestHeaders.CurrentUrl

現在のブラウザURL

HxRequestHeaders.HistoryRestoreRequest

履歴の復元用

HxRequestHeaders.Prompt

hx-promptへのユーザー応答

レスポンスヘッダー

HTMXレスポンスヘッダーの定数にアクセスするには、HxResponseHeadersオブジェクトを使用できます。

HxResponseHeaders.Location

ページリロードなしのクライアントサイドリダイレクト

HxResponseHeaders.PushUrl

URLを履歴スタックにプッシュ

HxResponseHeaders.Redirect

クライアントサイドリダイレクト

HxResponseHeaders.Refresh

強制的なページ全体のリフレッシュ

HxResponseHeaders.ReplaceUrl

現在のURLを置き換え

HxResponseHeaders.Reswap

レスポンスのスワップ方法を制御

HxResponseHeaders.Retarget

コンテンツ更新のターゲットを更新

HxResponseHeaders.Reselect

スワップするレスポンスの一部を選択

HxResponseHeaders.Trigger

クライアントサイドイベントをトリガー

HxResponseHeaders.TriggerAfterSettle

落ち着いた後にイベントをトリガー

HxResponseHeaders.TriggerAfterSwap

スワップ後にイベントをトリガー

スワップモード

コアモジュールktor-htmxのHxSwapオブジェクトを使用して、異なるHTMXスワップモードの定数にアクセスできます。

HxSwap.innerHtml

内部HTMLを置き換え（デフォルト）

HxSwap.outerHtml

要素全体を置き換え

HxSwap.textContent

テキストコンテンツのみを置き換え

HxSwap.beforeBegin

ターゲット要素の前に挿入

HxSwap.afterBegin

最初の子として挿入

HxSwap.beforeEnd

最後の子として挿入

HxSwap.afterEnd

ターゲット要素の後に挿入

HxSwap.delete

ターゲット要素を削除

HxSwap.none

コンテンツの追加なし

HTML DSL拡張機能

ktor-htmx-htmlモジュールは、KotlinのHTML DSLに拡張機能を追加し、HTMX属性をHTML要素に直接追加できるようにします。

@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") {
        // Regular route (both HTMX and non-HTMX requests)
        get {
            call.respondText("Regular response")
        }
        
        // Only matches HTMX requests (HX-Request header is present)
        hx.get {
            call.respondText("HTMX response")
        }
        
        // Matches HTMX requests with specific target
        hx {
            target("#result-div") {
                get {
                    call.respondText("Response for #result-div")
                }
            }
            
            // Matches HTMX requests with specific trigger
            trigger("#load-button") {
                get {
                    call.respondText("Response for #load-button clicks")
                }
            }
        }
    }
}

これらの機能により、アプリケーションはクライアントから送信されるHTMXヘッダーに応じて異なる応答をすることができます。