Layout Options
Proporciona un plugin de Layout que permite agregar fácilmente opciones de configuración a los layouts utilizando archivos YAML y plugins LayoutOption personalizados.
layout_options
Install
composer require 'drupal/layout_options:8.x-1.7'
composer require 'drupal/layout_options:8.x-1.5'
Overview
Layout Options es un módulo potente que extiende el sistema de Layout de Drupal proporcionando una forma flexible de agregar opciones de estilo y configuración a los layouts. En lugar de escribir código PHP, los constructores de sitios pueden definir opciones de layout a través de archivos YAML, facilitando agregar clases CSS, atributos ID y otras personalizaciones a los layouts y sus regiones.
El módulo funciona proporcionando una clase de plugin Layout personalizada (LayoutOptions) que reemplaza la clase de layout predeterminada. Este plugin lee la configuración de los archivos *.layout_options.yml descubiertos en módulos y temas, luego genera los elementos de formulario apropiados para configurar layouts en Layout Builder o Entity Reference Layouts. Los valores configurados se aplican como atributos HTML durante el renderizado.
El módulo soporta herencia de temas, permitiendo que los temas base definan opciones que pueden ser extendidas o sobrescritas por sub-temas. Las opciones pueden aplicarse globalmente a todos los layouts, a layouts específicos por ID, o incluso a contextos de campos específicos cuando se usa con Entity Reference Layouts.
Features
- Define opciones de configuración de layout mediante archivos YAML sin escribir código PHP
- Agrega atributos ID a layouts y regiones de layout usando el plugin layout_options_id
- Agrega clases CSS mediante entrada de texto usando el plugin layout_options_class_string
- Agrega clases CSS mediante menús desplegables usando el plugin layout_options_class_select con soporte para selección simple o múltiple
- Agrega clases CSS mediante checkboxes usando el plugin layout_options_class_checkboxes
- Agrega clases CSS mediante botones de radio usando el plugin layout_options_class_radios
- Configura opciones para aplicar solo al layout principal, solo a regiones, o ambos
- Restringe opciones a regiones específicas usando la configuración allowed_regions
- Aplica opciones globalmente a todos los layouts o apunta a IDs de layout específicos
- Soporte para opciones específicas de campo cuando se usa con Entity Reference Layouts
- Soporte de herencia de temas permitiendo que sub-temas extiendan o sobrescriban opciones del tema base
- Validación automática de identificadores CSS para asegurar nombres de clase e IDs válidos
- Ordenamiento basado en peso para controlar el orden de los elementos del formulario
- Sistema de plugins extensible para crear tipos de opciones de layout personalizados
Use Cases
Agregar colores de fondo Bootstrap a layouts
Crea una definición YAML que permita a los editores de contenido seleccionar clases de color de fondo Bootstrap (bg-primary, bg-secondary, etc.) para layouts y regiones. Define las opciones como un menú desplegable y aplícalas globalmente para que aparezcan en todos los layouts.
Clases de diseño específicas del tema
Define un conjunto de clases CSS específicas de tu tema (ej., layout--narrow, layout--wide, layout--centered) como checkboxes. Los constructores de sitios pueden aplicar rápidamente estas variaciones de diseño sin editar código.
Agregar IDs personalizados para enlaces ancla
Usa el plugin layout_options_id para permitir que los editores de contenido agreguen IDs HTML personalizados a layouts y regiones. Esto permite crear enlaces ancla para navegación dentro de la página.
Opciones específicas de campo para Entity Reference Layouts
Cuando usas el módulo Entity Reference Layouts, define opciones que solo aparezcan para campos específicos. Por ejemplo, un campo hero_section podría tener opciones de estilo diferentes que un campo content_blocks.
Personalizaciones específicas de layout
Define opciones que solo apliquen a ciertos layouts. Por ejemplo, un layout de dos columnas podría tener opciones para controlar las proporciones de columnas, mientras que un layout de una columna tiene diferentes opciones de márgenes.
Extensiones de opciones en sub-temas
Crea un tema base con opciones de layout principales, luego extiéndelas en un sub-tema para agregar opciones de estilo específicas del cliente. El sub-tema puede agregar nuevas opciones o sobrescribir las existentes.
Controles de espaciado solo para regiones
Define clases de padding y margin que solo apliquen a regiones, no al contenedor principal del layout. Usa allowed_regions para restringir aún más ciertas opciones a regiones específicas como barras laterales.
Tips
- Crea un módulo personalizado para las opciones de layout de tu sitio en lugar de agregarlas a un tema - esto asegura que las opciones permanezcan disponibles incluso si los temas cambian
- Usa IDs de opción significativos que describan su propósito (ej., layout_bg_color, layout_spacing) para mejor mantenibilidad
- Establece pesos apropiados en las opciones para agrupar configuraciones relacionadas juntas en el formulario de configuración
- Usa la sección global para opciones comúnmente usadas, y secciones específicas de layout solo cuando sea necesario
- Cuando crees plugins LayoutOption personalizados, extiende la clase OptionBase para aprovechar las utilidades de validación y construcción de formularios incorporadas
- Prueba las opciones de layout con diferentes temas para asegurar que las clases CSS funcionen como se espera en diferentes sistemas de diseño
- Usa la configuración allowed_regions para evitar que opciones irrelevantes aparezcan en ciertas regiones
- El submódulo Layout Options UI solo muestra layouts que usan la clase LayoutDefault predeterminada - los plugins de layout personalizados no aparecerán en la lista de sobrescritura
Technical Details
Admin Pages 1
/admin/config/system/layout_options/config
Esta página permite a los administradores seleccionar qué layouts deben ser sobrescritos para usar la clase Layout Options en lugar de la clase Layout predeterminada. Esto permite agregar opciones de configuración a layouts que no fueron originalmente diseñados para soportarlas.
Hooks 2
hook_layout_option_info_alter
Permite a los módulos alterar las definiciones de plugins de opciones de layout después de que son descubiertas. Puede usarse para modificar tipos de opciones existentes o agregar/eliminar funcionalidad.
hook_layout_alter
Usado por el submódulo Layout Options UI para sobrescribir clases de layout. Puede usarse para establecer programáticamente layouts para usar la clase LayoutOptions.
Troubleshooting 6
Asegúrate de que tu layout esté usando la clase LayoutOptions. Define un layout personalizado con class: '\Drupal\layout_options\Plugin\Layout\LayoutOptions' o habilita Layout Options UI y selecciona el layout a sobrescribir. También verifica que tu archivo YAML esté correctamente nombrado y ubicado en el directorio raíz del módulo/tema.
Limpia todas las cachés de Drupal (drush cr) después de modificar archivos *.layout_options.yml. El descubrimiento de YAML cachea el contenido de los archivos.
Asegúrate de que tu tema esté establecido como el tema predeterminado. Solo el tema predeterminado y sus temas base se consideran en la jerarquía de temas. Otros temas instalados pero no activos son filtrados.
Verifica que el ID del plugin en tu YAML coincida exactamente con un plugin LayoutOption disponible (layout_options_id, layout_options_class_string, layout_options_class_select, layout_options_class_checkboxes, layout_options_class_radios). Los IDs de plugin distinguen mayúsculas y minúsculas.
Verifica que tu plantilla de layout use la variable attributes. Asegúrate de que las clases sean identificadores CSS válidos - el módulo valida y rechaza identificadores inválidos.
Los identificadores CSS no pueden comenzar con números y solo pueden contener letras, números, guiones y guiones bajos. El módulo usa Html::cleanCssIdentifier para validación.
Security Notes 3
- Todos los valores ingresados por el usuario son sanitizados usando Html::escape() antes de ser almacenados o renderizados
- Los identificadores CSS son validados usando Html::cleanCssIdentifier() para prevenir nombres de clase inválidos o maliciosos
- La página de administración de Layout Options UI requiere el permiso 'administer site configuration'