UI Patterns (SDC en la interfaz de Drupal)
Expone SDC (Single Directory Components) como plugins de Drupal y permite usarlos de forma integrada en el desarrollo y construcción de sitios Drupal.
ui_patterns
Install
composer require 'drupal/ui_patterns:^2.0'
Overview
UI Patterns es un módulo integral que extiende la API de Single Directory Components (SDC) del núcleo de Drupal, proporcionando un framework robusto para definir, gestionar y utilizar componentes de interfaz reutilizables en todo su sitio Drupal. Los componentes son elementos reutilizables y anidables, guiados por estándares claros, que pueden ensamblarse para construir cualquier número de aplicaciones.
El módulo proporciona una arquitectura basada en plugins donde los componentes pueden usarse como Blocks, Layouts, Field Formatters y plugins de filas/estilos de Views. Incluye un sofisticado sistema de fuentes que permite mapear diversas fuentes de datos (Fields, Entities, tokens, menús, breadcrumbs) a las propiedades y slots de los componentes.
UI Patterns extiende la validación JSON Schema para las propiedades de los componentes, detecta automáticamente los tipos de propiedades (string, number, boolean, enum, URL, links, slots, etc.) y proporciona widgets apropiados para configurar cada tipo de propiedad en la interfaz de administración.
Features
- Extiende la API SDC del núcleo de Drupal con características adicionales y mejoras de usabilidad
- Arquitectura basada en plugins que expone los componentes como Blocks, Layouts, Field Formatters y plugins de Views
- Sistema integral de plugins Source para mapear datos a propiedades y slots de componentes
- Sistema PropType con detección automática desde JSON Schema (string, number, boolean, enum, URL, links, list, attributes, slot, etc.)
- Navegador de biblioteca de componentes para documentación y exhibición de componentes
- Sistema de widgets para configurar propiedades de componentes (textfield, select, checkbox, WYSIWYG, etc.)
- Plugins Source conscientes del contexto que se adaptan según el contexto de Entity, Field o View
- Soporte para variantes de componentes y atributos personalizados
- Filtros Twig para añadir clases y establecer atributos en componentes
- Resolución de referencias JSON Schema con protocolo de esquema personalizado ui-patterns://
- Sistema de negociación de componentes que permite a los Themes reemplazar componentes de Modules
- Capa de compatibilidad legacy para componentes de UI Patterns 1.x
- Sistema de historias/previsualizaciones para documentación de componentes
Use Cases
Crear un Componente de Tarjeta para Listado de Contenido
Crea un componente de tarjeta en tu Theme con props para título, imagen, resumen y enlace. Habilita UI Patterns Field Formatters y configura un campo Entity Reference para usar el formateador 'Component per item'. Mapea el título de la Entity referenciada al prop de título de la tarjeta, el campo de imagen al prop de imagen, y el resumen del body al prop de resumen. Cada Entity referenciada se renderiza como una tarjeta estilizada.
Construir una Sección Hero con Layout Builder
Crea un componente hero con slots para fondo, contenido y llamada a la acción. Habilita UI Patterns Layouts para exponerlo como un layout. En Layout Builder, selecciona el layout hero para una sección, luego coloca Blocks (texto, imágenes, botones) en cada región de slot. Configura los props de variante para alternar entre estilos centrados y alineados a la izquierda.
Mostrar Menús de Navegación
Crea un componente de navegación con un tipo de prop 'links'. Al configurar el componente en un Block, selecciona la fuente 'Menu' para el prop links y elige el menú deseado. El árbol del menú se transforma automáticamente en la estructura de datos de enlaces esperada por el componente.
Crear Layouts de Página Reutilizables
Define componentes de layout de página con slots para encabezado, barra lateral, contenido principal y pie de página. Úsalos como layouts en Layout Builder para una estructura de página consistente en todo tu sitio. Diferentes variantes pueden proporcionar disposiciones de dos o tres columnas.
Construir Views con Plantillas de Componentes
Crea un componente teaser para teasers de contenido. Habilita UI Patterns Views y configura una View para usar 'Component (UI Patterns)' como el plugin de fila. Mapea los Fields de la View a los props del componente usando los plugins de fuente de Field. Cada resultado de la View se renderiza usando tu plantilla de componente.
Migrar desde UI Patterns 1.x
Habilita UI Patterns Legacy para cargar componentes definidos en el formato YAML 1.x. Esto permite una migración gradual al nuevo formato de componentes basado en SDC mientras se mantiene la compatibilidad con definiciones de componentes existentes.
Tips
- Usa la propiedad 'group' en component.yml para organizar componentes en categorías lógicas en la biblioteca
- Define archivos stories.yml junto a tus componentes para proporcionar ejemplos de vista previa en la biblioteca de componentes
- El prop 'attributes' se añade automáticamente a todos los componentes - úsalo para pasar clases personalizadas y atributos data
- Usa la propiedad 'noUi: true' en component.yml para ocultar componentes internos/de utilidad de las interfaces de selección
- Los componentes pueden usar la propiedad 'replaces' para sobrescribir componentes de otros Modules o Themes
- Los plugins de fuente son conscientes del contexto - las fuentes de Field solo aparecen cuando el contexto de Entity está disponible
- Los filtros Twig add_class y set_attribute ayudan a manipular atributos dentro de las plantillas de componentes
- Usa JSON Schema $ref con el protocolo 'ui-patterns://' para referenciar los schemas de tipos de prop integrados de UI Patterns
- Los adaptadores PropType manejan la transformación de datos entre schemas compatibles pero estructurados de manera diferente
- Limpia las cachés después de añadir o modificar componentes para ver los cambios en la interfaz de administración
Technical Details
Admin Pages 5
/admin/appearance/ui
Página principal para bibliotecas relacionadas con la UI, incluyendo componentes, iconos, estilos y ejemplos. Sirve como punto de entrada a las bibliotecas del sistema de diseño.
/admin/appearance/ui/components
Explora todos los componentes de UI disponibles agrupados por categoría. Muestra el nombre del componente, proveedor, descripción y enlaces rápidos a las páginas individuales de cada componente. Los componentes están organizados por su propiedad 'group' definida en component.yml.
/admin/appearance/ui/components/{provider}
Explora componentes proporcionados por un Module o Theme específico. Muestra todos los componentes de ese proveedor organizados por grupo.
/admin/appearance/ui/components/{provider}/{machineName}
Página de documentación detallada para un componente individual. Muestra metadatos del componente (nombre, grupo, descripción, estado), tabla de props con tipos y valores predeterminados, tabla de slots y vistas previas de stories renderizadas si están definidas.
/admin/structure/component
Listado administrativo de todos los componentes con su gestión de visualización de formularios. Permite configurar cómo se presentan los props y slots del componente en los formularios de edición de contenido. Parte del Module experimental UI Patterns UI.
Permissions 3
Hooks 6
hook_component_info_alter
Modifica las definiciones de componentes SDC después de ser descubiertas. Permite modificar props, slots y otros metadatos del componente.
hook_ui_patterns_source_value_alter
Modifica los valores producidos por los plugins de origen antes de pasarlos a los componentes.
hook_ui_patterns_component_pre_build_alter
Prepara el elemento de renderizado del componente antes de pasar por el pipeline de renderizado.
hook_plugin_filter_block__ui_patterns_alter
Filtra los plugins de Block que pueden usarse como fuentes en UI Patterns. Establece _ui_patterns_compatible a FALSE para excluir bloques.
hook_component_form_display_groups
Define grupos para la interfaz de configuración de visualización de formulario del componente. (módulo UI Patterns UI)
hook_component_form_display_group_row_alter
Modifica una fila de grupo en la tabla de visualización de formulario del componente. (módulo UI Patterns UI)
Troubleshooting 5
Verifica que el component.yml sea válido, limpia las cachés y confirma que el componente no tenga 'noUi: true' configurado. Asegúrate de que el componente tenga al menos un slot definido para la integración con Block/layout.
Verifica que el JSON schema del prop coincida con un PropType conocido. Si usas schemas personalizados, asegúrate de que sean compatibles con los tipos de prop existentes o crea un adaptador PropType.
Verifica que los valores de los props coincidan con los tipos esperados del JSON schema. UI Patterns normaliza los valores, pero estructuras de datos incompatibles aún pueden causar fallos de validación.
Asegúrate de que el contexto de Entity esté disponible. En Blocks, esto requiere que el Block esté colocado en un contexto que proporcione una Entity (por ejemplo, Layout Builder en una visualización de Entity).
Habilita el Module UI Patterns Legacy que requiere UI Patterns Library. Asegúrate de que las definiciones de patrones legacy estén en el formato YAML esperado.
Security Notes 4
- La fuente WYSIWYG respeta los permisos de formato de texto de Drupal - asegúrate de que los formatos apropiados estén configurados
- El reemplazo de tokens en la fuente Token sigue el modelo de seguridad del sistema de tokens de Drupal
- Las fuentes de Block filtran inline_block y ciertos Blocks del sistema por defecto para prevenir dependencias entre Entities de contenido y configuración
- Los valores de atributos de componentes se sanitizan a través de la clase Attribute de Drupal cuando se renderizan