HTMX
Provides developer tools for building dynamic content in Drupal using the HTMX library.
htmx
インストール
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
Lazy Loading Content Blocks
Use the HTMX Loader block with the 'revealed' or 'intersect' event trigger to defer loading of heavy content blocks until they scroll into view. Configure an HTMX Block with your content block, then place an HTMX Loader in your theme region that loads it on viewport intersection.
Event-Triggered Content Updates
Configure HTMX Blocks to load on specific events like 'click', 'change', or custom HTMX events. Use the HtmxAttribute class to add HTMX attributes to buttons or links that trigger content loading, or use the HTMX Loader block for declarative configuration.
HTMX-Powered Views Pagination
Create a View with the HTMX display type and HTMX mini pager. The pager will load subsequent pages via HTMX without full page reloads, with optional URL push support for browser history integration.
HTMX-Enhanced Forms
Use HtmxAttribute to add HTMX attributes to form submit buttons for inline form submission. Use HtmxResponseHeaders to control post-submission behavior like triggering events, redirecting, or updating specific page elements.
Building Admin Interfaces with Off-Canvas Dialogs
The module's admin interface demonstrates using HTMX for off-canvas dialogs. Use HtmxAttribute with on() for event handlers and the dialog.off-canvas library for building similar admin experiences.
Entity View Mode Loading
Use the htmx.htmx_entity_view route to load any entity rendered in a specific view mode via HTMX. The route /htmx/{entityType}/{entity}/{viewMode} returns just the entity HTML for swapping into your page.
Tips
- Use HtmxAttribute's fluent interface to chain multiple attribute methods for clean, readable code
- Always call toArray() on HtmxAttribute when adding to render arrays that may be altered by other modules
- Use the create_htmx() Twig function with Twig Tweak's drupal_url() for template-level HTMX integration
- Set swap('outerHTML') with ignoreTitle:true (default) to prevent unwanted page title changes
- Use the 'revealed' trigger with HTMX Loader for lazy-loading below-fold content to improve initial page performance
- For Views using the HTMX display, exposed forms are automatically converted to submit via HTMX
- Enable htmx_debug during development but disable in production for better performance
Technical Details
Admin Pages 1
/admin/structure/htmx-block
Administration page for managing HTMX Block entities. HTMX Blocks are special block configurations that can be dynamically loaded via HTMX requests. Unlike standard blocks, HTMX Blocks are not assigned to regions but are loaded on-demand based on events.
権限 1
Hooks 5
hook_form_views_exposed_form_alter
Alters Views exposed forms when used with HTMX display to submit via HTMX instead of traditional form submission
hook_theme
Registers the htmx_mini_pager theme hook for the HTMX mini pager template
hook_preprocess_htmx_mini_pager
Preprocesses variables for the HTMX mini pager template, adding HTMX attributes for navigation
hook_preprocess_views_view
Adds data-htmx-display attribute to Views for targeting by HTMX pager
hook_page_top
Removes toolbar from page_top region during HTMX requests except for the toolbar_only route
Troubleshooting 4
Ensure your route has the _htmx_route: true option set, or use the HTMX Views display. This triggers the SimplePageVariant which renders without theme wrappers.
The htmx.block.view service uses the HX-Current-URL header to simulate the original page context. Ensure your HTMX requests include this header (automatically included by HTMX library).
Enable the htmx_debug submodule which loads the unminified HTMX library and enables the debug extension for comprehensive console logging of all HTMX events.
The module removes the toolbar from HTMX responses by default. If you need the toolbar, use the /htmx/toolbar-only route which specifically includes it.
Security Notes 4
- HTMX Blocks respect standard Drupal access controls through the BlockAccessControlHandler
- The administer htmx_block permission is required to create, edit, and delete HTMX Block configurations
- Entity view routes check entity access before rendering content
- Always validate and sanitize any user input that might be used in HTMX attribute values