Style Options
Una API de gestión de estilos configurable que permite adjuntar clases CSS, colores de fondo e imágenes de fondo a layouts, paragraphs y otros componentes de Drupal a través de un sistema de plugins extensible.
style_options
Instalar
composer require 'drupal/style_options:^1.1'
Overview
El módulo Style Options proporciona una API completa para gestionar opciones de estilo reutilizables en todo el ecosistema de Drupal. Permite a los constructores de sitios y desarrolladores adjuntar estilos configurables—como clases CSS, colores de fondo e imágenes de fondo—a varios componentes de Drupal sin escribir código personalizado.
El módulo utiliza un sistema de configuración basado en YAML que permite definir opciones de estilo en módulos o temas. Estas opciones pueden aplicarse a diferentes contextos, incluyendo layouts de Layout API y tipos de Paragraph. La arquitectura de plugins extensible permite a los desarrolladores crear plugins de opciones de estilo personalizados para necesidades de estilización especializadas.
Style Options incluye integración incorporada con Layout API y el módulo Paragraphs, proporcionando una experiencia de edición fluida. Los editores pueden configurar estilos a través de formularios intuitivos con características como selectores de color y carga de archivos. El módulo genera CSS dinámico que se adjunta automáticamente a los componentes renderizados.
Features
- Plugin de Clases CSS: Adjunta clases CSS personalizadas a componentes con soporte para opciones predefinidas (select/radios) o entrada de texto libre, con capacidad opcional de selección múltiple
- Plugin de Color de Fondo: Añade colores de fondo usando un selector de color integrado (Spectrum.js) con paleta configurable, soporte de transparencia alfa y elección del método de generación CSS (etiquetas de estilo incrustadas o estilos en línea)
- Plugin de Imagen de Fondo: Carga y aplica imágenes de fondo con manejo de archivos gestionados, ubicación de carga configurable, límites de tamaño de archivo, validación de dimensiones y generación automática de CSS estilo cover
- Plugin de Propiedad: Un plugin genérico para adjuntar valores de propiedades arbitrarias a componentes, útil para implementaciones personalizadas
- Integración con Layout API: Clase de plugin de layout incorporada (StyleOptionLayoutPlugin) que habilita opciones de estilo para layouts completos y regiones individuales con una interfaz de pestañas
- Integración con Paragraphs Behavior: Plugin ParagraphsBehavior que añade opciones de estilo a los formularios de edición de tipos de paragraph con configuración por bundle
- Configuración Basada en YAML: Define opciones de estilo en archivos [module].style_options.yml o [theme].style_options.yml con soporte para valores predeterminados, sobrescrituras y deshabilitación selectiva
- Configuración Consciente del Contexto: Configura qué opciones aparecen para layouts específicos, bundles de paragraph u otros contextos con herencia de valores predeterminados
- Sistema de Plugins Extensible: Crea plugins de opciones de estilo personalizados extendiendo StyleOptionPluginBase e implementando StyleOptionPluginInterface
- Generación Dinámica de CSS: Los estilos se renderizan como etiquetas <style> incrustadas en el head de la página con nombres de clase únicos para estilización sin conflictos
- Soporte AJAX: Soporte completo para contenido renderizado por AJAX con estilos correctamente adjuntados como sufijos cuando está en contexto AJAX
- Herramientas de Migración: Utilidad de migración incorporada para la transición desde el módulo Option Plugin con conversión automática de datos
Use Cases
Añadir Clases CSS Personalizadas a Layouts
Los constructores de sitios pueden definir un conjunto de clases CSS predefinidas (ej. 'container-wide', 'container-narrow', 'highlighted-section') en el archivo style_options.yml de su tema. Los editores pueden entonces seleccionar estas clases al configurar layouts, aplicando estilos consistentes sin necesidad de entender CSS.
Colores de Fondo Configurables para Secciones de Contenido
Define una paleta de colores aprobada por la marca en la configuración. Los editores de contenido pueden aplicar colores de fondo a tipos de paragraph como 'Llamada a la Acción' o 'Contenido Destacado' usando el selector de color, manteniendo la consistencia de marca mientras permiten flexibilidad creativa.
Secciones Hero con Imágenes de Fondo
Habilita la opción background_image para tipos de paragraph hero. Los editores pueden cargar imágenes de fondo que se estilizan automáticamente con propiedades cover, creando secciones de página visualmente impactantes sin intervención del desarrollador.
Diferentes Opciones de Estilo por Tipo de Componente
Usando el sistema de contextos, proporciona diferentes opciones de estilo para diferentes componentes. Por ejemplo, ofrece clases de ancho para secciones de layout, colores de fondo para paragraphs y estilos de resaltado para bundles de paragraph específicos.
Estilización de Marca Específica del Tema
Define todas las opciones de estilo en el style_options.yml de tu tema personalizado. Esto mantiene las configuraciones de estilización específicas de la marca con el tema y permite actualizaciones fáciles al cambiar de marca modificando un único archivo de configuración.
Extensión con Plugins Personalizados
Los desarrolladores pueden crear plugins de opciones de estilo personalizados para necesidades especializadas, como fondos degradados, sombras de caja o disparadores de animación. El sistema de plugins extensible permite que cualquier propiedad de estilo sea configurable.
Tips
- Usa la clave '_defaults' en contextos para establecer opciones base para todos los layouts o tipos de paragraph, luego sobrescribe o deshabilita opciones específicas para componentes individuales
- La clave '_disable' en definiciones de contexto te permite eliminar selectivamente opciones heredadas de los valores predeterminados sin redefinir todo
- Almacena tu style_options.yml en tu tema personalizado en lugar de un módulo para mantener las configuraciones de estilización específicas de marca junto con los assets de tu tema
- Al crear opciones predefinidas para el plugin css_class, incluye una opción 'Ninguno' con un valor de clase vacío para permitir a los usuarios eliminar el estilo
- Usa la configuración 'description' en las opciones para proporcionar orientación a los editores sobre cuándo y cómo usar cada opción de estilo
- Para colores de fondo, configura una paleta que coincida con los colores de tu marca para asegurar consistencia en todo el sitio
- Al extender el módulo con plugins personalizados, implementa StyleOptionStyleTrait para un comportamiento de generación CSS consistente
- La configuración 'method' en los plugins background_color y background_image por defecto es 'css' que genera etiquetas de estilo; usa 'inline' solo cuando las etiquetas de estilo causan problemas
Technical Details
Admin Pages 1
/admin/config/style-options/migrate
Utilidad de migración para la transición de datos desde el módulo Option Plugin. Esta página proporciona un proceso de migración simple de un solo clic que convierte las configuraciones de paragraph behavior del formato option_plugin al formato style_options.
Hooks 2
hook_style_options_alter
Permite a los módulos alterar las definiciones de plugins de opciones de estilo. Es llamado por el gestor de plugins cuando se recopilan las definiciones de plugins.
hook_theme
Implementado por el módulo para registrar hooks de tema para las plantillas de estilo background_color y background_image.
Troubleshooting 6
Asegúrate de que tu definición de layout use StyleOptionLayoutPlugin como la clase o la extienda. Verifica que tu archivo style_options.yml esté correctamente formateado y ubicado en el directorio raíz de tu módulo/tema. Verifica que el contexto de layout esté configurado en la sección 'contexts.layout'.
Habilita el behavior 'Style Options' para el tipo de paragraph en la configuración del tipo de paragraph. Verifica que el bundle de paragraph esté configurado en la sección 'contexts.paragraphs' de tu archivo style_options.yml.
Instala la biblioteca Spectrum.js en /libraries/spectrum/spectrum.js y /libraries/spectrum/spectrum.css. Limpia las cachés de Drupal después de la instalación.
Asegúrate de que el directorio de carga exista y sea escribible. Verifica los permisos del sistema de archivos. Verifica que el esquema de archivos (public/private) esté correctamente configurado en tu definición de opción.
Limpia todas las cachés después de cambios de configuración. Verifica que los valores de las opciones se estén guardando revisando las configuraciones de behavior de paragraph/layout. Verifica que el método build esté añadiendo correctamente los estilos al render array.
Asegúrate de que los tipos de paragraph tengan disponibles tanto el behavior option_plugin como style_options. La migración solo procesa paragraphs donde el behavior option_plugin estaba habilitado. Revisa los errores en el log de Drupal.
Security Notes 4
- Las cargas de archivos a través del plugin background_image se validan por extensiones de archivo (solo gif, png, jpg, jpeg), tamaño de archivo y dimensiones de imagen
- Los archivos cargados se marcan como permanentes para prevenir la limpieza automática, pero se gestionan correctamente a través del sistema de archivos de Drupal
- Los valores CSS se renderizan a través de plantillas Twig que proporcionan auto-escape, pero los plugins personalizados deben asegurar la sanitización adecuada de la entrada del usuario
- El formulario de migración requiere el permiso 'administer site configuration' para prevenir modificaciones de datos no autorizadas