Diagrama

O Widget Diagrama é uma das ferramentas mais flexíveis do DataViz, permitindo desenhar fluxogramas, mapas de processo, plantas baixas ou qualquer visualização customizada e injetar dados reais da Aplicação nesses elementos.

🔧 Funcionalidades

• Editor Completo: Acesso total às ferramentas de desenho do Draw.io (formas, setas, ícones, imagens)
• Vínculo com Dados: Capacidade de criar variáveis que buscam dados do Dashboard e as exibem dentro do desenho
• Interatividade: Suporte a links externos configuráveis (drill-through manual)

---

⚙️ Como Configurar

1. Criando o Desenho

Na aba Geral, clique em Desenhar Diagrama para abrir o editor.

• Desenhe seu processo ou visualização
• Para exibir um dado (Valor de Vendas), é necessário usar uma Variável
• O formato para usar uma variável no texto de qualquer forma é: {{NomeDaVariavel}}

2. Configurando Variáveis

Abaixo do botão de desenho, é possível criar e gerenciar as variáveis.

• Adicionar nova variável: Cria um novo vinculador de dados
• Nome da Variável: O identificador utilizado no desenho (se o nome for Vendas, no desenho utilize {{Vendas}})
• Configurar Variável: Abre as opções de dados para esta variável

Tipos de Variável:

1. Aplicação:
   • Coluna de dados: Busca o valor de uma métrica (Sum(Valor))
   • Filtros: Permite filtrar especificamente este dado (Trazer apenas vendas da "Loja A")
   • Formato do Número: Moeda, Porcentagem, Inteiro, etc.
2. Expressão:
   • Permite escrever uma fórmula JavaScript para calcular o valor. Veja detalhes avançados abaixo

3. Exemplo Prático: Planta de Loja

Imagine que se deseja mostrar o estoque de 3 setores de uma loja em uma planta baixa.

1. Crie 3 variáveis: EstoqueA, EstoqueB, EstoqueC.
2. Configure cada uma filtrando pelo respectivo setor.
3. Abra o Desenhar Diagrama.
4. Desenhe 3 retângulos representando os setores.
5. Dentro de cada retângulo, escreva o texto: "Setor A: {{EstoqueA}}".
6. Salve. Ao visualizar o Dashboard, {{EstoqueA}} será substituído pelo número real.

---

🎯 Aba Comportamento

• Gerar Link Externo: Transforma todo o Widget em um botão clicável que leva para uma URL externa (abrir um sistema legado ou página da intranet)
• Gráfico com fundo transparente: Remove o fundo branco, útil para integrar o desenho visualmente com o fundo do Dashboard

---

🎨 Configuração Visual

• Aparência: O diagrama pode ter fundo Padrão, Transparente (para se misturar ao fundo do Dashboard) ou Destacado
• Alinhamento: O desenho pode ser alinhado à esquerda, centro ou direita dentro do contêiner

---

💻 Programação Avançada (JavaScript)

Ao selecionar o tipo de variável Expressão, há acesso total a um ambiente JavaScript assíncrono para buscar e manipular dados.

IMPORTANT

O código roda dentro de uma função async. É possível usar await livremente. O contexto (this) contém ferramentas para acessar a Aplicação e bibliotecas utilitárias.

O Objeto this

O contexto da função expõe os seguintes objetos principais:

• this.app: Acesso à loja da Aplicação atual (dados, filtros, metadados)
• this.variables: Acesso ao valor de outras variáveis já calculadas neste Widget
• this.datefns: Biblioteca date-fns completa para manipulação de datas

1. Buscando Dados Internos (this.app)

É possível usar this.app.fetchMatrix para buscar qualquer dado da Aplicação, independentemente do que está na tela.

TIP

Ao referenciar colunas, é obrigatório incluir a expressão de agregação (:SUM, :AGP), caso contrário o filtro falhará.

// Exemplo: Buscar o total de vendas de um vendedor específico
const dados = await this.app.fetchMatrix({
  columns: [
    '[Vendas]."VALOR_TOTAL":SUM'  // Coluna calculada
  ],
  filters: [{
    column: '[Vendas]."NOME_VENDEDOR":AGP', // Coluna de filtro
    operator: "=",
    value: "João Silva"
  }]
});

// O resultado vem em uma matriz 2D (linhas x colunas)
if (dados.Result && dados.Result.length > 0) {
  const valor = dados.Result[0][0]; // Primeira linha, primeira coluna
  
  // Formatando o valor usando a máscara da coluna
  const colunaMetadata = dados.Columns[0];
  return this.app.formatValue(valor, colunaMetadata);
}

return "Sem Vendas";

2. Buscando Dados Externos (fetch)

Como o ambiente é JavaScript padrão, é possível buscar dados de APIs externas, como previsão do tempo, cotação de moedas ou status de servidores.

// Exemplo: Buscar a temperatura atual de uma API pública
try {
  const response = await fetch('https://api.weatherapi.com/v1/current.json?q=Sao Paulo');
  const data = await response.json();
  
  return data.current.temp_c + "°C";
} catch (error) {
  return "Erro de conexão";
}

3. Usando Outras Variáveis

É possível combinar variáveis simples para criar cálculos complexos.

// Exemplo: Calcular Ticket Médio baseado em duas outras variáveis do widget
// Variáveis já criadas: {{TotalVendas}} e {{QtdPedidos}}

// Importante: Variáveis de aplicação podem vir formatadas (string com R$), 
// então é bom garantir que sejam números para cálculo.

const vendas = this.variables['TotalVendas']; // Supondo que retorne o valor bruto
const pedidos = this.variables['QtdPedidos'];

if (pedidos > 0) {
    return (vendas / pedidos).toFixed(2);
}
return 0;

4. Manipulação de Datas (this.datefns)

// Exemplo: Retornar o nome do mês atual em português
const hoje = new Date();
return this.datefns.format(hoje, 'MMMM', { locale: this.datefns.locale.ptBR }); 
// Resultado: "dezembro"

5. Ordem de Execução e Dependências

É comum querer usar o resultado de uma variável dentro de outra. Para isso, é fundamental entender a ordem em que o sistema calcula os dados:

1. Variáveis de Aplicação (Dados): São sempre calculadas primeiro.
   • Consequência: Uma variável de Expressão pode acessar qualquer variável de Aplicação com segurança.
2. Variáveis de Expressão (JavaScript): São calculadas em seguida, na ordem em que aparecem na lista de configuração.
   • Consequência: Se a ExpressaoB depende da ExpressaoA, a ExpressaoA deve aparecer antes (acima) na lista de variáveis do Widget.

Se houver tentativa de acessar this.variables['Futura'] (uma variável que ainda não foi calculada), o valor será undefined.