Block Class
Permite asignar clases CSS personalizadas, atributos HTML e IDs a los bloques a través de la interfaz de usuario sin modificar las plantillas del tema.
block_class
Install
composer require 'drupal/block_class:^4.0'
Overview
Block Class proporciona una solución completa para agregar clases CSS personalizadas, atributos HTML e IDs a cualquier bloque a través de la interfaz estándar de configuración de bloques de Drupal. Esto elimina la necesidad de modificar plantillas del tema o tener conocimientos técnicos para controlar la salida HTML de los bloques.
El módulo almacena la configuración de estilos de bloques en el sistema de configuración de Drupal usando third_party_settings, facilitando la exportación y despliegue de cambios entre entornos. Se integra perfectamente con todos los módulos API del núcleo de Drupal y funciona con cualquier tema que renderice correctamente los atributos de bloque.
La versión 4.x proporciona características avanzadas incluyendo múltiples campos de texto para clases, funcionalidad de autocompletado, operaciones masivas para gestionar clases en todos los bloques, y configuraciones completas para controlar el comportamiento de los campos. El módulo soporta conversión a mayúsculas/minúsculas, manejo de caracteres especiales y filtrado personalizado de identificadores CSS.
Features
- Agregar clases CSS personalizadas a cualquier bloque a través del formulario de configuración de bloques
- Sobrescribir o eliminar el ID HTML de los bloques (usar <none> para eliminar el ID completamente)
- Agregar atributos HTML personalizados a los bloques en formato clave|valor (ej., data-block-type|info)
- Funcionalidad de autocompletado para clases y atributos usados previamente
- Modo de múltiples campos de texto permitiendo una clase por campo con botones de agregar/eliminar
- Operaciones masivas para insertar, actualizar, convertir mayúsculas/minúsculas o eliminar clases y atributos en todos los bloques
- Vista de lista de bloques mostrando todas las clases y atributos configurados con enlaces de editar/eliminar
- Vistas de lista de clases y lista de atributos mostrando todos los valores definidos
- Longitud máxima configurable para campos de clase, atributo e ID
- Configuración de peso para controlar el orden de los campos en formularios de bloques
- Conversión de mayúsculas/minúsculas (mayúsculas, minúsculas o estándar)
- Filtrado de caracteres especiales con configuración personalizable de Html::cleanCssIdentifier
- Configuración exportada junto con los ajustes del bloque para fácil despliegue
Use Cases
Agregar clases CSS para estilizado de diseño
Agregar clases CSS como 'footer-left', 'sidebar-promo' o 'hero-section' a los bloques para habilitar estilizado CSS específico sin modificar plantillas del tema. Navegue a la configuración del bloque, ingrese sus clases en el campo de clase CSS (una por línea en modo múltiple o separadas por espacios en modo campo de texto), y guarde. Las clases se agregarán al div contenedor del bloque.
Agregar atributos data para funcionalidad JavaScript
Agregar atributos data personalizados a los bloques para interacciones JavaScript. Habilite los atributos en los ajustes del módulo, luego al editar un bloque, agregue atributos como 'data-behavior|accordion' o 'data-tracking|header-cta' en los campos de atributos. Estos se renderizarán como data-behavior="accordion" en el HTML del bloque.
Estandarizar IDs de bloques entre entornos
Usar la característica de reemplazo de ID para establecer IDs de bloque consistentes independientemente del ID de bloque autogenerado por Drupal. Ingrese su ID personalizado en el campo ID. Use '<none>' para eliminar completamente el atributo ID de un bloque por razones de accesibilidad o estilizado.
Actualización masiva de nombres de clases durante rebranding
Cuando un rebranding requiere actualizar nombres de clases en todos los bloques, use la página de Operaciones masivas. Seleccione 'Actualizar clase', ingrese el nombre de clase actual y el nuevo nombre de clase, y la operación encontrará y reemplazará esa clase en todos los bloques.
Aplicar convenciones de nomenclatura de clases CSS
Configure el módulo para aplicar solo clases en minúsculas para consistencia del equipo. En los ajustes, establezca Mayúsculas/minúsculas por defecto a 'Minúsculas' y deshabilite caracteres especiales. Todas las clases se convertirán automáticamente a minúsculas al guardar.
Exportar estilizado de bloques con la configuración
Dado que Block Class almacena la configuración en third_party_settings, todas las clases CSS, atributos e IDs personalizados se exportan con la configuración del bloque. Use la exportación/importación de configuración de Drupal para desplegar cambios de estilizado de bloques entre entornos.
Tips
- Use el modo de múltiples campos de texto para una gestión de clases más limpia - previene errores tipográficos y facilita eliminar clases individuales
- La característica de autocompletado recuerda todas las clases usadas previamente, haciendo más rápido aplicar estilizado consistente entre bloques
- Cuando se usa '<none>' como valor de ID, el atributo ID del bloque se elimina completamente de la salida HTML
- Las clases se sanitizan automáticamente usando Html::cleanCssIdentifier a menos que los caracteres especiales estén habilitados
- Use los ajustes Avanzados para configurar reglas de reemplazo de caracteres si tiene convenciones de nomenclatura específicas
- El módulo se integra con todos los tipos de bloques incluyendo bloques de Views, bloques personalizados y bloques de módulos contrib
- Exporte su configuración a control de versiones para rastrear cambios en el estilizado de bloques a lo largo del tiempo
- Use operaciones masivas para aplicar rápidamente una clase común a todos los bloques al implementar cambios de estilizado en todo el sitio
Technical Details
Admin Pages 6
/admin/config/content/block-class/settings
Configurar ajustes globales para el módulo Block Class incluyendo tipos de campo, longitudes máximas, pesos y opciones de características para clases, atributos y reemplazo de ID.
/admin/config/content/block-class/list
Ver todos los bloques que tienen configuración de Block Class (clases o atributos) con opciones para editar o eliminar la configuración.
/admin/config/content/block-class/bulk-operations
Realizar operaciones masivas en clases y atributos en todos los bloques incluyendo operaciones de insertar, actualizar, convertir mayúsculas/minúsculas y eliminar.
/admin/block-class/help
Muestra información de ayuda sobre el módulo Block Class incluyendo instrucciones de uso, opciones de configuración y enlaces a páginas de administración.
/admin/config/content/block-class/class-list
Ver todas las clases CSS que se han usado en configuraciones de bloques. Útil como referencia al agregar clases a nuevos bloques.
/admin/config/content/block-class/attribute-list
Ver todos los atributos que se han usado en configuraciones de bloques en formato inline.
Permissions 1
Hooks 4
hook_block_presave
Procesa la configuración de clases de bloque antes de guardar, incluyendo conversión de mayúsculas/minúsculas y almacenamiento de clases/atributos para autocompletado.
hook_form_block_form_alter
Agrega campos de clase CSS, atributos e ID al formulario de configuración de bloques.
hook_preprocess_block
Agrega las clases CSS, atributos e ID configurados a las variables del render array del bloque.
hook_help
Proporciona texto de ayuda para la página de ayuda del módulo Block Class.
Troubleshooting 7
Asegúrese de que la plantilla de bloque de su tema renderice correctamente la variable de atributos. Verifique que {{ attributes }} o similar esté presente en block.html.twig. Las clases se agregan a $variables['attributes']['class'] durante el preprocesamiento.
Verifique que 'Habilitar autocompletado' esté marcado en los ajustes del módulo. Las clases se almacenan cuando se guardan los bloques, por lo que necesita guardar al menos un bloque con una clase antes de que aparezca en el autocompletado.
Por defecto, los caracteres especiales están deshabilitados. Vaya a /admin/config/content/block-class/settings y marque 'Habilitar caracteres especiales' para permitirlos. Note que los nombres de clase CSS válidos aún tienen restricciones.
Si su ajuste de Mayúsculas/minúsculas por defecto entra en conflicto con la operación masiva (ej., intentar convertir a mayúsculas cuando se aplican minúsculas), la operación mostrará un error. Cambie primero el ajuste de Mayúsculas/minúsculas por defecto o establézcalo a 'Mayúsculas y minúsculas' para permitir ambos.
El número de campos de clase se controla por 'Cantidad de clases por bloque' en los ajustes. Aumente este valor si necesita más campos. El módulo se expandirá automáticamente más allá de este límite si un bloque ya tiene más clases.
Verifique que 'Habilitar atributos' esté marcado en los ajustes del módulo en /admin/config/content/block-class/settings.
Estos están reservados. Use el campo dedicado de Clase para clases CSS. Para ID, use la característica de reemplazo de ID en lugar de atributos.
Security Notes 4
- El permiso 'Administrar clases de bloques' está marcado como restringido y solo debe otorgarse a roles de confianza
- Los valores de atributos HTML se sanitizan usando Html::escape() para prevenir ataques XSS
- Los identificadores CSS se procesan a través de Html::cleanCssIdentifier() a menos que los caracteres especiales estén explícitamente habilitados
- El módulo valida que 'id' y 'class' no puedan usarse como claves de atributos para prevenir conflictos