Diagrama

Tipo

Referência

Para

Analista, Desenvolvedor

Na tela

DataViz › Aplicação › Dashboards › Editando Widget › Diagrama

O Diagrama é um desenho livre, feito no editor do draw.io, com valores da aplicação escritos dentro das formas. Cobre o que nenhum gráfico desenha: um fluxo de processo com o volume de cada etapa, a planta de um armazém com o estoque de cada setor, um organograma com o resultado de cada área.

O valor entra no desenho por uma variável. Uma forma com o texto Setor A: {{EstoqueA}} mostra, no Dashboard, o valor da variável EstoqueA no lugar da marcação.

Aba Geral

Na tela	O que faz
Gráfico com fundo transparente	Tira o fundo, a borda e a sombra do widget, e o desenho fica sobre a cor do Dashboard.
Alinhamento	O desenho à esquerda, no centro (padrão) ou à direita do widget.
Desenhar Diagrama	Abre o Editor de Diagrama, com o draw.io e, ao lado, o painel Variáveis disponíveis, que lista cada marcação com o valor atual. Ao salvar, o desenho volta para o widget.
Variáveis	A lista de variáveis do desenho. Adicionar nova variável cria uma, com Nome da Variável. Configurar Variável abre as opções e Excluir Varíavel a remove.
Filtros Pré-aplicados	Filtros que valem para todas as variáveis do widget. Veja Filtros.

O nome da variável é o que vai entre chaves duplas no desenho: a variável Vendas aparece como {{Vendas}}. A marcação pode estar em qualquer texto do desenho, inclusive no meio de uma frase.

Opções da Variável

Tipo de Variável escolhe de onde vem o valor.

Tipo	Campos	Valor
Aplicação	Coluna de dados, Filtros (só desta variável) e Formato do Número	O total da coluna com os filtros do widget e os da variável, já formatado.
Expressão	Uma regra em JavaScript, escrita pelo botão Editar	O que a regra devolver.

Com a variável configurada, Resultado da Variável: mostra o valor calculado. Esse resultado calcula a variável sozinha: uma expressão que lê outras variáveis mostra undefined no lugar delas aqui, mas funciona no widget. Salvar e Fechar grava.

Aba Comportamento

Gerar Link Externo transforma o widget inteiro num link. Em Link Externo, o endereço, que abre numa aba nova, como a página de um sistema interno.

Regras em JavaScript

Uma variável do tipo Expressão recebe:

Variável	O que é
this.variables	Os valores das variáveis já calculadas, por nome: this.variables["Vendas"].
this.app	A aplicação, já com os Filtros Pré-aplicados. this.app.fetchMatrix consulta dados e this.app.formatValue formata um valor pela máscara da coluna.
this.datefns	A biblioteca de datas.

O código roda numa função assíncrona, então await funciona. Veja Regras em JavaScript para a janela de edição. Aqui o painel Documentação vem vazio: os valores de this são os da tabela acima.

As variáveis do tipo Aplicação são calculadas primeiro, e as de Expressão depois, na ordem da lista. Uma expressão enxerga todas as variáveis de aplicação e as expressões que estão acima dela; uma que está abaixo ainda não existe e chega como undefined.

As variáveis de aplicação chegam formatadas, como texto ("R$ 1.234,56"), qualquer que seja o Formato do Número. Para fazer conta, consulte o valor bruto com this.app.fetchMatrix em vez de reaproveitar a variável.

Se a expressão devolve um objeto, cada chave vira uma variável. Uma expressão Totais que devolve { vendas: 10, pedidos: 2 } cria {{vendas}}, {{pedidos}}, {{Totais_vendas}} e {{Totais_pedidos}}.

Exemplo, a data de hoje:

return this.datefns.format(new Date(), "dd/MM/yyyy");

this.datefns não traz os idiomas da biblioteca: nomes de mês e de dia saem em inglês.

Consultar dados com this.app.fetchMatrix

this.app.fetchMatrix consulta qualquer coluna da aplicação, esteja ou não em outro widget. A coluna vai como [Tabela]."COLUNA" (ou [Tabela].[Rótulo]; uma expressão como ["Rótulo"]) seguida da agregação, que é obrigatória: :SUM para somar, :AGP para agrupar. O resultado vem em Result, uma linha por item e uma posição por coluna, na ordem pedida, com até 500 linhas (para mais, passe options: { limit: 2000 }); os metadados das colunas vêm em Columns.

// Total de vendas de um vendedor
const dados = await this.app.fetchMatrix({
  columns: ['[Vendas]."VALOR_TOTAL":SUM'],
  filters: [{
    column: '[Vendas]."NOME_VENDEDOR":AGP',
    operator: "=",
    value: "Ana Souza",
  }],
});

if (dados.Result.length > 0) {
  return this.app.formatValue(dados.Result[0][0], dados.Columns[0]);
}
return "Sem vendas";

O código roda no navegador de quem vê o Dashboard, então fetch também funciona para chamar uma API externa, desde que ela aceite chamadas do navegador (CORS).

Limites

• Uma variável de aplicação traz um número só, o total da coluna. Para uma lista ou um valor por categoria, use uma expressão com this.app.fetchMatrix.
• Porcentagem no formato da variável multiplica por 100 duas vezes. Veja o aviso em Formato do Número.
• Uma expressão que dá erro derruba o widget inteiro: no lugar do desenho aparece "Erro executando expressão JS:" seguido da mensagem.
• Uma variável de aplicação cuja coluna não existe mais aparece como -FIELD NOT FOUND-; sem coluna escolhida, como -.
• Clicar numa forma não filtra o Dashboard. O único clique é o Link Externo, que vale para o widget inteiro.

Pelo Lumo CLI

Este widget também pode ser criado e versionado em YAML, com type: Diagram. Veja a referência de app.