HTMX
Proporciona herramientas para desarrolladores para construir contenido dinámico en Drupal utilizando la biblioteca HTMX.
htmx
Install
composer require 'drupal/htmx:^1.5'
composer require 'drupal/htmx:^1.4'
Overview
El módulo HTMX proporciona herramientas completas para que los desarrolladores de Drupal construyan contenido dinámico e interactivo utilizando la biblioteca HTMX. HTMX permite a los desarrolladores acceder a las funcionalidades modernas del navegador directamente desde atributos HTML, permitiendo actualizaciones dinámicas de la página sin escribir JavaScript.
Este módulo extiende la integración HTMX del núcleo de Drupal (introducida en Drupal 11) con clases PHP para construir atributos y cabeceras de respuesta HTMX, un sistema de entidades de bloques personalizados para bloques cargables dinámicamente, integración con Views con plugins de visualización y paginador específicos para HTMX, y extensiones Twig para integración HTMX a nivel de plantilla.
El módulo sigue los principios de aplicaciones orientadas a hipermedia, permitiendo que fragmentos HTML renderizados en el servidor se intercambien en el DOM basándose en eventos del usuario, creando experiencias de aplicación de página única responsivas mientras mantiene la mejora progresiva y la accesibilidad.
Features
- Clase HtmxAttribute que proporciona una API fluida para construir todos los atributos HTMX (hx-get, hx-post, hx-swap, hx-target, hx-trigger, etc.) con seguridad de tipos completa y documentación
- Clase HtmxResponseHeaders para construir cabeceras de respuesta HTMX (HX-Location, HX-Push-Url, HX-Redirect, HX-Trigger, etc.)
- Sistema de entidades de configuración HTMX Block para crear bloques que pueden cargarse dinámicamente mediante solicitudes HTMX
- Plugin HTMX Loader Block que activa la carga de HTMX Blocks basándose en eventos configurables
- Plugin de visualización HTMX para Views que proporciona renderizado de variante de página simple para solicitudes HTMX
- Plugin HTMX Mini Pager para Views para paginación impulsada por HTMX
- Transformación automática de formularios expuestos de Views para envío HTMX
- Extensión Twig que proporciona la función create_htmx() para creación de atributos HTMX a nivel de plantilla
- Suscriptor de eventos que habilita el renderizado SimplePageVariant para rutas con la opción _htmx_route
- Sistema de diálogo off-canvas para formularios de administración en línea
- Ruta para renderizar entidades en modos de visualización específicos vía HTMX
- Submódulo de depuración para desarrollo con biblioteca HTMX sin minificar y registro en consola
Use Cases
Carga diferida de bloques de contenido
Use el bloque HTMX Loader con el trigger de evento 'revealed' o 'intersect' para diferir la carga de bloques de contenido pesados hasta que entren en el viewport. Configure un HTMX Block con su bloque de contenido, luego coloque un HTMX Loader en la región de su tema que lo cargue al intersectar con el viewport.
Actualizaciones de contenido activadas por eventos
Configure HTMX Blocks para cargarse en eventos específicos como 'click', 'change', o eventos HTMX personalizados. Use la clase HtmxAttribute para añadir atributos HTMX a botones o enlaces que activen la carga de contenido, o use el bloque HTMX Loader para configuración declarativa.
Paginación de Views impulsada por HTMX
Cree una Vista con el tipo de visualización HTMX y el mini paginador HTMX. El paginador cargará las páginas subsiguientes vía HTMX sin recargas completas de página, con soporte opcional de push de URL para integración con el historial del navegador.
Formularios mejorados con HTMX
Use HtmxAttribute para añadir atributos HTMX a los botones de envío de formularios para envío de formularios en línea. Use HtmxResponseHeaders para controlar el comportamiento post-envío como activar eventos, redirigir, o actualizar elementos específicos de la página.
Construcción de interfaces de administración con diálogos off-canvas
La interfaz de administración del módulo demuestra el uso de HTMX para diálogos off-canvas. Use HtmxAttribute con on() para manejadores de eventos y la biblioteca dialog.off-canvas para construir experiencias de administración similares.
Carga de modos de visualización de entidades
Use la ruta htmx.htmx_entity_view para cargar cualquier entidad renderizada en un modo de visualización específico vía HTMX. La ruta /htmx/{entityType}/{entity}/{viewMode} devuelve solo el HTML de la entidad para intercambiarlo en su página.
Tips
- Use la interfaz fluida de HtmxAttribute para encadenar múltiples métodos de atributos para código limpio y legible
- Siempre llame a toArray() en HtmxAttribute cuando lo añada a render arrays que puedan ser alterados por otros módulos
- Use la función Twig create_htmx() con drupal_url() de Twig Tweak para integración HTMX a nivel de plantilla
- Configure swap('outerHTML') con ignoreTitle:true (por defecto) para prevenir cambios no deseados del título de página
- Use el trigger 'revealed' con HTMX Loader para carga diferida de contenido debajo del fold para mejorar el rendimiento de carga inicial
- Para Views usando la visualización HTMX, los formularios expuestos se convierten automáticamente para enviar vía HTMX
- Habilite htmx_debug durante el desarrollo pero deshabilítelo en producción para mejor rendimiento
Technical Details
Admin Pages 1
/admin/structure/htmx-block
Página de administración para gestionar entidades HTMX Block. Los HTMX Blocks son configuraciones especiales de bloques que pueden cargarse dinámicamente mediante solicitudes HTMX. A diferencia de los bloques estándar, los HTMX Blocks no se asignan a regiones sino que se cargan bajo demanda basándose en eventos.
Permissions 1
Hooks 5
hook_form_views_exposed_form_alter
Altera los formularios expuestos de Views cuando se usan con la visualización HTMX para enviar vía HTMX en lugar del envío de formulario tradicional
hook_theme
Registra el hook de tema htmx_mini_pager para la plantilla del mini paginador HTMX
hook_preprocess_htmx_mini_pager
Preprocesa variables para la plantilla del mini paginador HTMX, añadiendo atributos HTMX para navegación
hook_preprocess_views_view
Añade el atributo data-htmx-display a Views para ser objetivo del paginador HTMX
hook_page_top
Elimina la barra de herramientas de la región page_top durante las solicitudes HTMX excepto para la ruta toolbar_only
Troubleshooting 4
Asegúrese de que su ruta tenga la opción _htmx_route: true establecida, o use la visualización HTMX de Views. Esto activa el SimplePageVariant que renderiza sin envolturas de tema.
El servicio htmx.block.view usa la cabecera HX-Current-URL para simular el contexto de la página original. Asegúrese de que sus solicitudes HTMX incluyan esta cabecera (incluida automáticamente por la biblioteca HTMX).
Habilite el submódulo htmx_debug que carga la biblioteca HTMX sin minificar y habilita la extensión de depuración para registro comprensivo en consola de todos los eventos HTMX.
El módulo elimina la barra de herramientas de las respuestas HTMX por defecto. Si necesita la barra de herramientas, use la ruta /htmx/toolbar-only que la incluye específicamente.
Security Notes 4
- Los HTMX Blocks respetan los controles de acceso estándar de Drupal a través del BlockAccessControlHandler
- El permiso administer htmx_block es requerido para crear, editar y eliminar configuraciones de HTMX Block
- Las rutas de visualización de entidades verifican el acceso a la entidad antes de renderizar el contenido
- Siempre valide y sanee cualquier entrada de usuario que pueda usarse en valores de atributos HTMX