Charts
Una API de gráficos para Drupal que permite crear gráficos dinámicos sin código, con integración para Views, Fields y Blocks.
charts
Install
composer require 'drupal/charts:^5.1'
Overview
El módulo Charts transforma datos en información visual proporcionando una API de gráficos completa para Drupal. Permite a los constructores de sitios crear gráficos dinámicos sin necesidad de escribir código, mientras ofrece una potente API para desarrolladores que necesitan control programático.
Charts soporta cinco bibliotecas de gráficos principales de forma nativa: Billboard.js, C3.js, Chart.js, Google Charts y Highcharts. Cada biblioteca tiene sus propias ventajas, desde las bibliotecas de código abierto basadas en D3 hasta las características premium de Highcharts. El módulo abstrae la complejidad de estas bibliotecas, proporcionando una interfaz unificada para la creación de gráficos.
El módulo ofrece tres métodos principales para crear gráficos a través de la interfaz: integración con Views (para visualización dinámica de datos), Chart Fields (para incrustar gráficos en entidades) y Chart Blocks (para colocar gráficos mediante Layout Builder o ubicación de bloques). Para desarrolladores, los render arrays con elementos de gráfico proporcionan control programático completo.
Features
- Soporte para 5 bibliotecas de gráficos: Billboard.js, C3.js, Chart.js, Google Charts y Highcharts
- 14 tipos de gráficos incluyendo área, barra, columna, línea, circular, dona, medidor, dispersión, burbuja, spline, boxplot, vela, mapa de calor y rango de área
- Integración con Views con formato de visualización Chart para visualización dinámica de datos
- Tipo de campo Chart para incrustar gráficos en entidades de contenido con entrada manual de datos
- Chart Block para Layout Builder y ubicación tradicional de bloques
- Chart Attachments en Views para crear gráficos combinados con múltiples tipos de gráfico
- Soporte para eje Y secundario para gráficos de doble eje
- Capacidad de apilamiento de datos para series de gráficos agrupados
- Personalización de colores con 25 colores predeterminados y asignación de color por serie
- Agrupación de entidades con selección de color por referencia de entidad, propiedad de campo o campo de color
- Soporte CDN para bibliotecas externas con opción de usar copias locales
- Modo de depuración para mostrar el JSON generado para solución de problemas
- API de Render Element para creación programática de gráficos
- Hooks alter para personalizar gráficos y definiciones específicas de biblioteca
- Dimensiones responsivas con ancho/alto configurables y unidades
Use Cases
Panel de análisis de contenido
Crear un panel basado en Views que muestre estadísticas de contenido como vistas de página, engagement de usuarios y tendencias de creación de contenido a lo largo del tiempo. Usar el formato de display Chart para visualizar conteos de nodos por tipo de contenido como un gráfico circular, y creación mensual de contenido como un gráfico de línea.
Informes de ventas de productos
Usar Chart Fields para incrustar gráficos de rendimiento de ventas directamente en nodos de producto. Almacenar datos de ventas trimestrales en el campo de gráfico y mostrarlo como un gráfico de columnas que muestra tendencias de ventas. El gráfico aparece automáticamente en la página del producto.
Bloques de monitoreo de KPI
Usar Charts Blocks para crear gráficos de medidor que muestren indicadores clave de rendimiento. Colocar estos bloques en un layout de panel usando Layout Builder. Configurar zonas del medidor (verde/amarillo/rojo) para indicar umbrales de rendimiento.
Gráficos combinados para comparación
Crear un gráfico combinado basado en Views que muestre tanto valores absolutos como tendencias. Usar el display principal Chart para datos de columna, luego adjuntar un display de attachment Chart con tipo de gráfico de línea para superponer líneas de tendencia en el mismo gráfico.
Datos dinámicos de fuentes externas
Usar la API de Charts para crear gráficos programáticamente desde fuentes de datos externas. Construir render arrays con #type 'chart', agregar elementos chart_data para series y configurar ejes. El módulo de ejemplo de API demuestra este enfoque en /charts/example/display.
Series de gráfico coloreadas por taxonomía
Al agrupar datos de Views por término de taxonomía, usar la característica de selección de color de agrupación de entidades para asignar automáticamente colores a las series del gráfico basándose en el término de taxonomía. Los colores pueden establecerse por entidad, por valor de propiedad de campo, o desde un color_field en la entidad referenciada.
Tips
- Comenzar con un display de tabla de Views para entender la estructura de tus datos, luego convertir a formato Chart una vez que los campos de datos estén correctamente configurados.
- Usar el módulo Charts API Example (/charts/example/display) como referencia al construir gráficos programáticos.
- La propiedad #raw_options permite pasar opciones específicas de biblioteca que no están expuestas en la configuración estándar.
- Para gráficos combinados que combinen múltiples tipos de gráfico, crear displays de attachment Chart y adjuntarlos al display de gráfico padre.
- Habilitar el modo de depuración durante el desarrollo para ver el JSON que se pasa a la biblioteca de gráficos - útil para solución de problemas y pruebas en playgrounds de bibliotecas.
- Al usar agrupación de Views con referencias de entidad, aprovechar la selección de color de agrupación de entidades para colorear automáticamente las series del gráfico por taxonomía u otras entidades referenciadas.
- Los datos de Chart Field pueden ingresarse mediante pegado de CSV o entrada manual en tabla - CSV es más rápido para conjuntos de datos grandes.
- Instalar las bibliotecas de gráficos localmente usando npm o Composer para mejor rendimiento y confiabilidad comparado con CDN.
Technical Details
Admin Pages 2
/admin/config/content/charts
Configurar los ajustes predeterminados para todos los gráficos creados en el sitio. Estos valores predeterminados se aplican a nuevos gráficos pero no afectan a los gráficos existentes.
/admin/config/content/charts/advanced
Configurar opciones avanzadas para depuración de gráficos y uso de CDN.
Permissions 1
Hooks 5
hook_chart_alter
Alterar un gráfico individual antes de que se imprima. Permite modificar las propiedades del gráfico antes del renderizado.
hook_chart_CHART_ID_alter
Alterar un gráfico específico identificado por su ID de gráfico. Igual que hook_chart_alter pero apunta a un gráfico específico.
hook_chart_definition_alter
Alterar la representación raw de biblioteca de un gráfico después de la conversión del módulo Charts. Proporciona acceso a opciones específicas de la biblioteca pero puede fallar al cambiar de bibliotecas.
hook_chart_definition_CHART_ID_alter
Alterar la definición raw de biblioteca de un gráfico específico por ID de gráfico.
hook_charts_plugin_supported_chart_types_alter
Modificar la lista de tipos de gráfico soportados para un plugin de biblioteca de gráficos. Requiere definir tipos de gráfico en un archivo .charts_types.yml.
Troubleshooting 6
Habilitar al menos un submódulo de biblioteca de gráficos (charts_billboard, charts_c3, charts_chartjs, charts_google o charts_highcharts) en /admin/modules.
Verificar los ajustes avanzados en /admin/config/content/charts/advanced y asegurar que 'Usar CDN por defecto' esté habilitado. Tener en cuenta que el uso de CDN puede causar problemas con Ajax y BigPipe.
Asegurar que al menos un campo tenga 'Provides Data' marcado en los ajustes de Chart. El campo de etiqueta no puede ser también proveedor de datos. Verificar que los campos numéricos estén configurados correctamente.
Diferentes bibliotecas soportan diferentes tipos de gráfico. El módulo Charts solo muestra tipos de gráfico soportados por la biblioteca actualmente seleccionada. Cambiar de biblioteca o consultar la documentación de la biblioteca para ver los tipos soportados.
Habilitar 'Charts Debug' en /admin/config/content/charts/advanced. Un elemento details colapsable aparecerá debajo de cada gráfico mostrando la configuración JSON enviada a la biblioteca.
Highcharts es gratuito solo para uso no comercial. Para proyectos comerciales, comprar una licencia en highcharts.com o usar una biblioteca alternativa de código abierto como Chart.js o Billboard.js.
Security Notes 3
- El permiso 'access all charts' debe otorgarse con cuidado ya que proporciona control administrativo sobre la funcionalidad de gráficos.
- Los títulos y etiquetas de gráficos están sanitizados pero las raw_options personalizadas se pasan directamente a la biblioteca JavaScript.
- El uso de CDN significa que se cargan recursos externos; para entornos de alta seguridad, instalar las bibliotecas localmente.