インストール
composer require 'drupal/htmx:^1.5'
composer require 'drupal/htmx:^1.4'
概要
HTMXモジュールは、HTMXライブラリを使用して動的でインタラクティブなコンテンツを構築するための包括的なツールをDrupal開発者に提供します。HTMXを使用すると、開発者はHTML属性から直接モダンなブラウザ機能にアクセスでき、JavaScriptを書かずに動的なページ更新を実現できます。
このモジュールは、Drupalコア（Drupal 11で導入）のHTMX統合を拡張し、HTMX属性とレスポンスヘッダーを構築するためのPHPクラス、動的にロード可能なブロック用のカスタムブロックエンティティシステム、HTMX固有のディスプレイおよびページャープラグインを備えたViews統合、テンプレートレベルのHTMX統合のためのTwig拡張を提供します。
このモジュールはハイパーメディア駆動型アプリケーションの原則に従い、ユーザーイベントに基づいてサーバーレンダリングされたHTMLフラグメントをDOMにスワップすることで、プログレッシブエンハンスメントとアクセシビリティを維持しながら、レスポンシブなシングルページアプリケーション体験を実現します。
Features
- すべてのHTMX属性（hx-get、hx-post、hx-swap、hx-target、hx-triggerなど）を構築するための流暢なAPIを提供するHtmxAttributeクラス（完全な型安全性とドキュメント付き）
- HTMXレスポンスヘッダー（HX-Location、HX-Push-Url、HX-Redirect、HX-Triggerなど）を構築するためのHtmxResponseHeadersクラス
- HTMXリクエストを介して動的にロードできるブロックを作成するためのHTMX Block設定エンティティシステム
- 設定可能なイベントに基づいてHTMX Blockのロードをトリガーするhtmx_loader Blockプラグイン
- HTMXリクエスト用のシンプルなページバリアントレンダリングを提供するViews HTMXディスプレイプラグイン
- HTMX駆動のページネーション用Views HTMXミニページャープラグイン
- HTMX送信用のViews公開フォームの自動変換
- テンプレートレベルでのHTMX属性作成のためのcreate_htmx()関数を提供するTwig拡張
- _htmx_routeオプションを持つルートに対してSimplePageVariantレンダリングを有効にするイベントサブスクライバー
- インライン管理フォーム用のオフキャンバスダイアログシステム
- HTMXを介して特定のビューモードでエンティティをレンダリングするためのルート
- 非圧縮HTMXライブラリとコンソールロギングによる開発用デバッグサブモジュール
Use Cases
コンテンツブロックの遅延ロード
HTMXローダーブロックで'revealed'または'intersect'イベントトリガーを使用し、重いコンテンツブロックのロードをビューポートにスクロールするまで延期します。コンテンツブロックでHTMX Blockを設定し、次にテーマリージョンにHTMXローダーを配置してビューポート交差時にロードします。
イベントトリガーによるコンテンツ更新
'click'、'change'、またはカスタムHTMXイベントなどの特定のイベントでロードするようにHTMX Blockを設定します。HtmxAttributeクラスを使用してコンテンツロードをトリガーするボタンやリンクにHTMX属性を追加するか、HTMXローダーブロックを使用して宣言的な設定を行います。
HTMX駆動のViewsページネーション
HTMXディスプレイタイプとHTMXミニページャーでViewを作成します。ページャーはページ全体のリロードなしにHTMXを介して後続のページをロードし、ブラウザ履歴統合用のオプションのURLプッシュサポートを備えています。
HTMX強化フォーム
HtmxAttributeを使用してフォーム送信ボタンにHTMX属性を追加し、インラインフォーム送信を実現します。HtmxResponseHeadersを使用して、イベントのトリガー、リダイレクト、特定のページ要素の更新など、送信後の動作を制御します。
オフキャンバスダイアログを使用した管理インターフェースの構築
このモジュールの管理インターフェースは、オフキャンバスダイアログにHTMXを使用する例を示しています。HtmxAttributeのon()をイベントハンドラーとともに使用し、dialog.off-canvasライブラリで同様の管理体験を構築します。
エンティティビューモードのロード
htmx.htmx_entity_viewルートを使用して、特定のビューモードでレンダリングされた任意のエンティティをHTMXを介してロードします。/htmx/{entityType}/{entity}/{viewMode}ルートは、ページにスワップするためのエンティティHTMLのみを返します。
Tips
- HtmxAttributeの流暢なインターフェースを使用して、複数の属性メソッドをチェーンすることでクリーンで読みやすいコードを実現してください
- 他のモジュールによって変更される可能性のあるrender arrayに追加する場合は、HtmxAttributeで常にtoArray()を呼び出してください
- テンプレートレベルのHTMX統合には、Twig Tweakのdrupal_url()とcreate_htmx() Twig関数を使用してください
- 不要なページタイトルの変更を防ぐために、swap('outerHTML')をignoreTitle:true（デフォルト）で設定してください
- HTMXローダーで'revealed'トリガーを使用して、初期ページパフォーマンスを向上させるためにフォールド下のコンテンツを遅延ロードしてください
- HTMXディスプレイを使用するViewsでは、公開フォームは自動的にHTMXを介して送信されるように変換されます
- 開発中はhtmx_debugを有効にし、パフォーマンス向上のため本番環境では無効にしてください
Technical Details
Admin Pages 1
/admin/structure/htmx-block
HTMX Blockエンティティを管理するための管理ページです。HTMX Blockは、HTMXリクエストを介して動的にロードできる特別なブロック設定です。標準的なブロックとは異なり、HTMX Blockはリージョンに割り当てられず、イベントに基づいてオンデマンドでロードされます。
権限 1
Hooks 5
hook_form_views_exposed_form_alter
HTMXディスプレイで使用されるViews公開フォームを変更し、従来のフォーム送信の代わりにHTMXを介して送信するようにします
hook_theme
HTMXミニページャーテンプレート用のhtmx_mini_pagerテーマフックを登録します
hook_preprocess_htmx_mini_pager
HTMXミニページャーテンプレートの変数を前処理し、ナビゲーション用のHTMX属性を追加します
hook_preprocess_views_view
HTMXページャーによるターゲティング用にViewsにdata-htmx-display属性を追加します
hook_page_top
toolbar_onlyルートを除くHTMXリクエスト時にpage_topリージョンからツールバーを削除します
Troubleshooting 4
ルートに_htmx_route: trueオプションが設定されているか、HTMX Viewsディスプレイを使用していることを確認してください。これにより、テーマラッパーなしでレンダリングするSimplePageVariantがトリガーされます。
htmx.block.viewサービスは、HX-Current-URLヘッダーを使用して元のページコンテキストをシミュレートします。HTMXリクエストにこのヘッダーが含まれていることを確認してください（HTMXライブラリにより自動的に含まれます）。
htmx_debugサブモジュールを有効にしてください。非圧縮のHTMXライブラリがロードされ、すべてのHTMXイベントの包括的なコンソールロギング用のデバッグ拡張が有効になります。
モジュールはデフォルトでHTMXレスポンスからツールバーを削除します。ツールバーが必要な場合は、それを特別に含む/htmx/toolbar-onlyルートを使用してください。
Security Notes 4
- HTMX BlockはBlockAccessControlHandlerを通じて標準的なDrupalアクセス制御を遵守します
- HTMX Block設定の作成、編集、削除にはadminister htmx_block権限が必要です
- エンティティビュールートはコンテンツをレンダリングする前にエンティティアクセスをチェックします
- HTMX属性値で使用される可能性のあるユーザー入力は常にバリデーションとサニタイズを行ってください