Tiles customizados

Quando os tipos de tile nativos não servem para o visual que você quer, o Saiku traz renderizadores customizados que vão mais longe sem deixar de ser seguros. Todos são declarativos — você descreve o resultado com dados, não com código.

Cada renderizador aparece como sua própria entrada no menu + Adicionar tile (em “Custom”). Escolher um solta um tile já ligado àquele renderizador; depois você o configura no editor ⚙ do tile exatamente como qualquer outro — escolha um cubo, monte uma consulta e forneça a configuração do renderizador.

Nota

Renderizadores customizados são habilitados por deployment. Se o menu ”+ Adicionar tile” mostra “No custom renderers installed”, o seu Saiku não os registrou — fale com o administrador.

Tile de lista ranqueada

O renderizador Lista ranqueada desenha o card de “movers” que a maioria dos dashboards de operação quer: uma sequência numerada de linhas, cada uma com um rótulo e um valor, com o valor colorido conforme subiu ou desceu.

Ligue-o a uma consulta que devolva uma coluna de rótulo e uma coluna de valor, e então configure:

Campo	O que significa
Subtítulo	Uma linha discreta sob o título do tile (“Product department · MoM”)
Coluna de rótulo	Em branco = inferida (veja abaixo)
Coluna de valor	Em branco = inferida (veja abaixo)
Formato do valor	Padrão de exibição opcional — $c1 → $27.4M. Em branco mantém a formatação do próprio cubo
Linhas	Quantas mostrar (padrão 6)
Ordem	Manter a ordem da consulta, maior primeiro, ou menor primeiro
Cor do valor	Por sinal (subiu verde / desceu vermelho) ou neutra
Mostrar números de rank	O 1, 2, 3… na frente

Deixadas em branco, as colunas são inferidas estruturalmente: o valor é a primeira coluna de medida do resultado e o rótulo é o que sobra. Isso vale mesmo quando as captions de uma dimensão parecem números — um decil de prescritores (10.0), um ano, um número de loja — que é justamente onde adivinhar pelo texto entenderia ao contrário.

Formato do valor usa o mesmo vocabulário de padrões do tile de KPI e do eixo de valores do ECharts: $cN moeda compacta, $N moeda simples, N% percentual, N casas decimais. Vale a pena em qualquer medida monetária — um card top-N de linhas cruas $27,432,535.99 é difícil de bater o olho.

A ordenação acontece antes do limite de linhas, então “maior primeiro, 3 linhas” é de fato o top três do resultado inteiro, não as três primeiras reordenadas. Cores e tipografia seguem o tema da App — sem CSS.

Dica

Esse card costumava ser feito estilizando um tile de Tabela com CSS customizado. Não faça — um tile de lista ranqueada se retematiza junto com a App, não colide com outras tabelas da página e é editável por quem herdar a sua App.

Tile de option do ECharts

O renderizador ECharts option deixa você criar um gráfico escrevendo direto um objeto option do ECharts. É a saída de emergência para formas que o tile de Gráfico nativo não expõe — arranjos de eixo sob medida, variantes rose, visual maps incomuns e por aí vai.

Cuidado

Confira antes O tile de Gráfico. Radar, dispersão, treemap, sunburst, heatmap e cascata são todos tipos de gráfico nativos, e eixos duplos, séries combo, linhas de tendência, Top N, formatação numérica e linhas de referência são todos opções nativas. Recorrer a uma option escrita à mão para conseguir uma dessas te custa a herança de tema, a formatação condicional e — acima de tudo — a capacidade de quem herdar a sua App mudar aquilo sem editar JSON.

Como a sua option é entregue a uma biblioteca de gráficos viva, ela é validada contra um subconjunto seguro antes mesmo de renderizar. As regras, aplicadas em toda profundidade do objeto:

• Nenhum valor de função. O ECharts chama coisas como formatter como funções com dados e DOM vivos, então qualquer função em qualquer lugar da option é rejeitada. (JSON puro não expressa função; a checagem protege de um objeto vivo enfiar uma.)

• Nenhuma URL remota. http(s): de outra origem, //host relativo ao protocolo, alvos url(...) apontando para fora da origem e URIs data: que não sejam imagem são todos rejeitados — são vetores de exfiltração / SSRF. Sobram referências de mesma origem e relativas, mais imagens data: somente em PNG, JPEG, GIF ou WebP.

  Note que SVG não está nessa lista, nem como imagem data:. Um SVG pode carregar script, então é excluído de propósito — use uma exportação raster se precisar de um ícone inline.

• Só chaves da allowlist. São aceitas apenas chaves de topo curadas (title, grid, xAxis, yAxis, series, legend, tooltip, color, backgroundColor, visualMap, radar, polar e mais algumas) e um conjunto curado de campos por series. Qualquer coisa fora da allowlist é rejeitada em vez de silenciosamente descartada — o validador falha fechado.

Se a sua option viola alguma regra, o tile mostra um erro de validação em vez de renderizar, para você corrigir. A consulta que você liga fornece os dados (categorias + séries) que a option desenha.

Tema primeiro, option depois

Sua option é sobreposta à linha de base tematizada da App. O que ela declara vence; o que ela deixa de dizer — cor do título, cor dos rótulos de eixo, linhas de grade, a paleta de séries — é herdado do tema.

Escreva só as partes que são genuinamente sob medida. Uma option cheia de hexadecimais fixos fica idêntica no primeiro dia e para de combinar com a App na primeira vez que alguém troca o preset.

Nota

Componentes são decorados, nunca introduzidos. No ECharts, mencionar um componente o liga — então a linha de base só estiliza uma legenda, um tooltip ou um eixo se a sua option já declarar um. Um gráfico de pizza não ganha eixos porque o tema tem opinião sobre eles.

Formatando o eixo de valores

Como funções são rejeitadas, você não formata um eixo do jeito habitual do ECharts — axisLabel.formatter teria que ser uma função. Em vez disso o editor tem um campo Formato do eixo de valores que aceita o mesmo padrão que o tile de KPI usa:

Padrão	Renderiza
$c0	$149K — moeda compacta
$c1	$48.2K
$2	$99.50
1%	15.6%
0	1,234

É aplicado a todo eixo type: "value" e compilado no momento do render, então você nunca fornece código e a regra de nada-de-funções continua absoluta. Eixos de categoria ficam intocados — um template de string como "W{value}" na sua option ainda funciona lá, já que aquilo é declarativo.

Tile de grafo

O renderizador Grafo transforma os registros de uma consulta num grafo de nós e arestas — uma árvore de propriedade, um mapa de relações, um fluxo entre entidades. Em vez de um objeto option, você dá a ele um mapeamento de colunas: quais colunas do seu resultado são as pontas, ids, rótulos e pesos.

Campo	Obrigatório	O que significa
sourceCol	sim	Coluna com a ponta de origem de cada linha
targetCol	sim	Coluna com a ponta de destino de cada linha
idCol	sim	Coluna com o id canônico de um nó (para um rótulo grudar no nó certo). Para uma lista de arestas simples, deixe igual a sourceCol
labelCol	não	Coluna com um nome amigável de exibição para o nó de idCol
valueCol	não	Coluna numérica levada para cada aresta e somada no peso do nó
layout	não	force (padrão) ou circular

Cada linha vira uma aresta dirigida origem → destino; os nós são coletados de cada ponta e deduplicados por id. Linhas sem uma ponta são puladas. Quando você define valueCol, o valor dela pesa tanto a aresta quanto seus nós de ponta — o tamanho do nó é escalado relativo aos pesos daquele grafo, então o nó mais pesado sempre alcança o topo da faixa de tamanho, sejam quais forem as unidades da medida. Um peso zero ou negativo é o nó mais leve, não um sem peso.

Configurando um tile customizado

O fluxo é o mesmo para todos:

1. + Adicionar tile → Ranked list (ou ECharts option, ou Graph).
2. Abra o editor ⚙ do tile.
3. Ligue uma consulta — escolha o cubo e monte a consulta cujo resultado alimenta o tile.
4. Forneça a configuração — os campos da lista ranqueada, o objeto option do ECharts, ou o mapeamento de colunas do grafo.
5. Salve. Configuração inválida aparece como erro inline em vez de um render quebrado.

Relacionado

• Construindo páginas e tiles — os tipos de tile nativos e como a ligação funciona.
• O tile de Gráfico — confira aqui antes de escrever uma option do ECharts na mão.
• Plugins — o tile avançado, instalado pelo administrador, com JS em sandbox para widgets totalmente sob medida.