Custom Elements
Proporciona un framework para renderizar entidades de Drupal como elementos HTML personalizados (Web Components) para arquitecturas frontend desacopladas.
custom_elements
Install
composer require 'drupal/custom_elements:^3.3'
Overview
El módulo Custom Elements proporciona un framework integral para renderizar datos de Drupal (entidades, campos) en marcado de elementos personalizados. Los elementos personalizados pueden ser fácilmente renderizados por componentes frontend utilizando Web Components o diversos frameworks JavaScript como Vue.js o React.
Esto permite a Drupal renderizar componentes de tema de alto nivel mientras el renderizado real es manejado por una aplicación frontend. El módulo soporta tanto el desacoplamiento progresivo (mezclando elementos personalizados con la salida tradicional de Drupal) como el desacoplamiento completo (respuestas de API con marcado de elementos personalizados o JSON).
Las capacidades principales incluyen: configuración de UI para salida de elementos personalizados por modo de vista de entidad, API para construir árboles anidados de elementos personalizados con metadatos de caché, serialización a marcado HTML o representación JSON, y sistema extensible de procesadores para personalizar cómo se renderizan los datos en elementos personalizados.
Features
- Renderizar entidades de Drupal como elementos HTML personalizados (Web Components) para consumo por frameworks frontend
- Configuración basada en UI de la salida de elementos personalizados por tipo de entidad, bundle y modo de vista mediante entidades Custom Elements Display
- Dos formatos de serialización: marcado HTML (estilo Web Component o estilo Vue 3) y JSON (formato explícito o legacy)
- Integración con Layout Builder para construir elementos personalizados desde secciones y regiones de layout
- Modo de procesamiento automático que mapea inteligentemente campos a atributos o slots según la complejidad del campo
- Custom Element Field Formatters conectables para control detallado sobre la salida de campos individuales
- Sistema extensible de procesadores para personalizar cómo se renderizan entidades y campos en elementos personalizados
- Proveedores de vista previa para estructura JSON, vista previa de código de marcado y vista previa de frontend Nuxt.js
- Soporte para elementos personalizados anidados con propagación adecuada de metadatos de caché
- Permisos dinámicos por tipo de entidad para administrar displays de elementos personalizados
Use Cases
Desacoplamiento progresivo con Web Components
Usar elementos personalizados como parte de una respuesta regular renderizada por Drupal donde Web Components o JavaScript toma el control del renderizado en el navegador. Habilitar 'Force custom elements rendering' en modos de vista de entidad específicos, y agregar el JavaScript de Web Component a la librería custom_elements/main en tu tema.
Desacoplamiento completo con Vue.js/Nuxt
Construir un frontend completamente desacoplado usando Vue.js/Nuxt mientras Drupal sirve como CMS headless. Usar Lupus Custom Elements Renderer para servir respuestas de API JSON. Configurar el estilo de marcado Vue 3 para compatibilidad de sintaxis de slots. El proveedor de vista previa de Nuxt permite editar contenido con vistas previas en vivo.
Integración con Layout Builder
Construir layouts de página complejos usando Layout Builder de Drupal mientras se muestran como elementos personalizados. Cada sección de layout se convierte en un elemento <drupal-layout> con regiones como slots. Los bloques dentro de las regiones se renderizan como elementos personalizados anidados.
Renderizado de campo de referencia de entidad
Renderizar entidades referenciadas (como media, paragraphs u otro contenido) como elementos personalizados anidados. Usar el formatter 'Custom element: Rendered entity' con modo de vista configurable y aplanamiento opcional para fusionar propiedades en el elemento padre.
Campo de imagen con procesamiento de estilo
Mostrar campos de imagen con procesamiento de estilo de imagen. El formatter Image genera URLs para imágenes estilizadas junto con texto alt, ancho y atributos de alto. Habilitar la opción de aplanar para mostrar propiedades de imagen como atributos separados en el elemento padre.
Desarrollo y depuración de API
Usar el proveedor de vista previa JSON en el formulario de edición de Custom Elements Display para ver exactamente qué estructura JSON se enviará a tu frontend. El formato JSON explícito separa claramente props de slots para un consumo más fácil en el frontend.
Tips
- Los modos de vista con nombres que comienzan con 'custom_elements' automáticamente tienen habilitado el renderizado de elementos personalizados
- Usar la opción 'Flatten' en formatters de referencia de entidad y archivo para fusionar propiedades de entidades referenciadas directamente en el elemento padre
- El sistema de prioridad de procesadores permite a módulos personalizados sobrescribir el manejo predeterminado de campos registrando servicios de procesador con mayor prioridad
- Los metadatos de caché se propagan correctamente a través de elementos personalizados anidados, asegurando la invalidación correcta del caché
- La propiedad estática CustomElement::$removeFieldPrefix puede configurarse en settings.php para eliminar globalmente los prefijos 'field_' de las claves de salida
Technical Details
Admin Pages 1
/admin/config/system/custom-elements
Configurar ajustes globales para el renderizado de elementos personalizados incluyendo estilo de marcado, formato JSON y modo de renderizado predeterminado.
Permissions 2
Hooks 2
hook_custom_element_entity_defaults_alter
Permite preparar valores predeterminados del elemento personalizado antes de ser procesado. Se llama cuando se generan elementos personalizados desde entidades para permitir a los módulos establecer nombres de etiqueta, prefijos o atributos predeterminados.
hook_custom_element_entity_alter
Permite alterar elementos personalizados después de la generación, antes de ser renderizados. Se llama después de que todo el procesamiento de campos está completo para permitir modificaciones finales.
Troubleshooting 4
Asegurarse de que 'Force custom elements rendering' esté habilitado en la pestaña Manage Display de la entidad para ese modo de vista, o que el nombre del modo de vista comience con 'custom_elements' lo cual habilita automáticamente el renderizado.
Tanto el entity view display COMO el Custom Elements Display deben tener 'Use Layout Builder' habilitado. Verificar ambas configuraciones y asegurarse de que el módulo Layout Builder esté instalado.
Verificar la configuración de formato de serialización JSON en /admin/config/system/custom-elements. El formato 'Explicit' separa props/slots, el formato 'Legacy' los mezcla. Los sitios existentes pueden estar en formato legacy después de la actualización.
La versión 3.x usa renderizado basado en configuración. Crear Custom Elements Displays para tus modos de vista de entidad y habilitar la opción 'Automatic Processing' para replicar el comportamiento de 2.x. Ver registros de cambios en drupal.org/list-changes/custom_elements.
Security Notes 3
- Los displays de Custom Elements respetan el sistema de acceso a campos de Drupal - los campos a los que los usuarios no pueden acceder no se incluyen en la salida
- La salida JSON usa escape apropiado para prevenir XSS cuando se renderiza marcado
- El módulo no expone ningún dato que no sería accesible a través del renderizado normal de vista de entidad