インテグレーション

Hypermedia Components はテンプレートエンジン非依存の UI キットです。このセクションのドキュメントでは、代表的なサーバレンダリングスタックへの組み込み方法を示します。各ガイドは共通して次の 5 つの関心事を扱います:

アセット読み込み — hc.css、hc.behaviors.min.js、任意の macros/index.min.js を、そのフレームワークの静的ファイル構成のどこに置くか。
コンポーネントの描画 — 繰り返し登場する UI 形状(hc-field、 hc-button、テーブル行)の慣用的なスニペット。
HTML フラグメント — コントローラ / ハンドラ / ビューが htmx スワップ用の HTML 片を返す方法。
HX-Trigger トースト — サーバが HX-Trigger レスポンスヘッダー経由で hc:toast イベントを発火する方法。
CSRF 統合 — フレームワークの CSRF トークンをすべての htmx リクエストに渡す方法。

ガイド

基礎(初めて HC を組み込むならここから):

Plain HTML — dist ファイルをコピーするだけ。テンプレートエンジンもバンドラーも不要。
htmx — すべてのフレームワークガイドが継承する htmx 側の規約(設定、ヘッダー、イベント)。

サーバサイドテンプレートエンジン:

Thymeleaf(Spring Boot)
Django
Rails
Go — html/template + net/http
Razor(ASP.NET Core)

クライアントサイドの相棒:

Hyperscript — vanilla の installXxx ビヘイビアに対するオプトインの代替。

共通の規約

いくつかの規約はすべてのガイドで繰り返し登場します。一度身につけておく価値があります:

htmx は `HX-Request` ヘッダーで検知する

すべての htmx リクエストは HX-Request: true を設定します。ハンドラはこのヘッダーで分岐し、フルページかフラグメントだけかを返し分けます。

GET /items
HX-Request: true           → return rows fragment
                no header  → return full page (with layout + chrome)

空ボディは正当

破壊系エンドポイントの多くは、空ボディ + HX-Trigger ヘッダーを返します:

HTTP/1.1 200 OK
HX-Trigger: {"hc:toast":{"message":"Deleted.","variant":"success"}}

(empty body)

クライアント側のスワップは削除された行の outerHTML なので、ボディの内容にかかわらず htmx が行を取り除きます。

`hx-` より `data-hx-`

HC のドキュメントが data-hx-* を選ぶのは、妥当な HTML5 構文であり、テンプレートエンジンと相性が良く、たいていのリンターを通るからです。 htmx は簡潔さを好むスタック向けに hx-* も受け付けます — この選択はプロジェクト単位であり、コンポーネント単位ではありません。

CSRF はリクエストヘッダーで運ぶ

レイアウトに <meta name="csrf-token"> タグを 1 つ描画すれば、 auto-init の installCsrfHeader() ビヘイビアがすべての htmx リクエストでトークンを転送します — data-header で、フレームワークが期待するヘッダー名(X-CSRFToken、X-CSRF-Token、 RequestVerificationToken など)に改名できます。 CSRF トークン — 公認の規約を参照してください。ヘッダー名が実行時にしか分からない場合は、手書きの htmx:configRequest リスナーがフォールバックとして残ります。