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 に対する実験的な第一級（first-class）のサポートを提供します。これらのモジュールは、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 に対するユーザーのレスポンス

レスポンスヘッダー

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

HxResponseHeaders.Location

ページのリロードを伴わないクライアント側のリダイレクト

HxResponseHeaders.PushUrl

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

HxResponseHeaders.Redirect

クライアント側のリダイレクト

HxResponseHeaders.Refresh

ページのフルリフレッシュを強制する

HxResponseHeaders.ReplaceUrl

現在の URL を置換する

HxResponseHeaders.Reswap

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

HxResponseHeaders.Retarget

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

HxResponseHeaders.Reselect

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

HxResponseHeaders.Trigger

クライアント側のイベントをトリガーする

HxResponseHeaders.TriggerAfterSettle

定着（settle）後にイベントをトリガーする

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 に拡張関数を追加し、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 ヘッダーに応じて、アプリケーションが異なるレスポンスを返すことができます。