Los ocho tipos de gráfico cubren casi todo. Cuando lo que tienes en la cabeza no es ninguno de ellos —un semáforo, una tarjeta con tu marca, una tabla con formato propio, un indicador con forma de medidor— puedes escribirlo tú.
Cuándo usarlo
La regla honesta: si un widget normal lo hace, usa el widget normal. Es más rápido de montar, se entiende sin abrir nada y no depende de que alguien mantenga ese código. El de código propio es para lo que de verdad no encaja.
Casos donde compensa:
- Un panel para colgar en una pantalla del local, con tu tipografía y tus colores.
- Un semáforo: verde si la tasa de asistencia supera el 80 %, rojo si baja del 60 %.
- Una tabla con formato condicional, resaltando lo que se sale de lo normal.
- Un texto que redacte el número en una frase, para quien no lee gráficos.
Cómo funciona
Se elige el tipo «código», se define la consulta igual que en cualquier otro widget —medidas, dimensiones, filtros— y luego se escribe el HTML, el CSS y el JavaScript que la dibujan.
Dibuja distinto; no consigue los datos distinto
Las plantillas de arranque
No hace falta empezar de cero. El editor trae siete puntos de partida, y en el panel se llaman así:
- Tarjeta grande — un número destacado con su etiqueta. Es la plantilla con la que nace todo widget de código.
- Ranking con barras — el top de una dimensión, ordenado.
- Medidor — un valor sobre un objetivo.
- Barras de progreso — varias categorías con su avance.
- Tabla con semáforo — filas con formato condicional por color.
- SVG a medida (se redibuja al cambiar de tamaño) — un dibujo propio que se vuelve a pintar cuando agrandas o achicas el widget.
- En blanco — el esqueleto mínimo, para partir de cero con la estructura ya puesta.
Eliges una en el desplegable y pulsas Empezar desde esta plantilla. Como reemplaza lo que hayas escrito, pide confirmarlo con Sí, reemplazar. Luego cambias los textos y ya está.
Cómo llegan los datos
Tu código recibe un objeto ctx con el resultado de la consulta, el tamaño del widget y la versión del entorno, y además un formateador de números y fechas (ctx.format), los colores del panel (ctx.theme) y la moneda del negocio. Lo básico es leer las filas y pintarlas. Usa ctx.format para los importes: llegan en céntimos y él ya sabe dividirlos y poner el símbolo de tu moneda.
const clave = ctx.fields.metrics[0]; // la primera medida de la consulta
const columna = ctx.data.columns.find((c) => c.key === clave);
const total = ctx.data.rows.reduce((suma, f) => suma + (Number(f[clave]) || 0), 0);
ctx.el.querySelector('#total').textContent = ctx.format.value(total, columna.unit);Cuando cambian los datos o el tamaño
El widget avisa cuando llegan datos nuevos —al cambiar el periodo, por ejemplo— y cuando alguien lo redimensiona en el lienzo:
ctx.on('update', () => dibujar());
ctx.on('resize', () => dibujar());Qué NO puede hacer, y por qué
El widget corre aislado. No es una restricción de configuración: es el muro que permite que un informe con código escrito por una persona lo pueda mirar todo el equipo sin riesgo.
- No accede a la red. Ni a nuestra API, ni a una externa. No puede pedir datos ni enviarlos.
- No ve tu sesión. No alcanza las cookies del panel ni la página que lo contiene.
- No puede abrir ventanas ni avisos del navegador. Para depurar están los mensajes de consola, que el editor te enseña.
- No carga librerías externas. Consecuencia directa de lo primero.
Un bucle infinito congela la pestaña
Los topes
- 8.000 caracteres de HTML y 8.000 de CSS.
- 20.000 caracteres de JavaScript.
- 120.000 caracteres de código sumando todos los widgets de un informe.
Dan de sobra para un widget bien escrito. Si te quedas corto, casi siempre es que el widget está haciendo trabajo que le correspondería a la consulta: agrupar, filtrar o calcular en JavaScript lo que el explorador ya sabe hacer.