Widgets

Conceito

O cadastro de Widget define, de forma reutilizável, a fonte de dados e a aparência de um item que poderá ser exibido em um ou mais Dashboards. É neste cadastro que fica a Expressão SQL responsável por buscar os dados, além de todas as configurações visuais: tipo de exibição, cores, fontes, legendas e formatação dos valores. Um mesmo Widget pode ser configurado como Gráfico (barra, linha ou pizza), como Indicador (um único valor em destaque) ou como Grade (uma tabela com as linhas da consulta), conforme o Tipo de Widget escolhido.

O que é

A tela de cadastro de Widget é dividida em abas: Geral, Campo X, Colunas, Campos e Expressão SQL. Nem todas se aplicam a todos os tipos:

• Gráfico: utiliza todas as abas.
• Indicador: o próprio Campo X fornece o valor único exibido no card, e a aba Colunas não é utilizada.
• Grade: a aba Colunas define as colunas da tabela; da aba Campo X, somente o Campo Ordenação e o Ranking se aplicam.

A Expressão SQL deve retornar as linhas de detalhe, sem GROUP BY. No Gráfico e no Indicador, quem agrupa pelo Campo X (e Campo Série, quando configurado) e soma cada Coluna de valor é o próprio Widget, automaticamente, na hora de montar o gráfico. Na Grade, as linhas são exibidas como vierem da consulta, sem agrupamento. Isso permite que qualquer campo retornado pela consulta — mesmo um que não apareça diretamente no Widget — possa ser usado como Filtro do Item no Dashboard.

Para que serve

Quando compreendemos a funcionalidade do cadastro de Widget, conseguimos criar visualizações próprias — números em destaque, gráficos e tabelas — para acompanhar qualquer informação do sistema, sem depender de um relatório específico, e reaproveitar essa mesma visualização em quantos dashboards forem necessários.

Quais os benefícios e/ou ganhos de uso

Ao centralizar em um único cadastro a consulta e a aparência de um Widget, diferentes dashboards podem reaproveitar o mesmo sem retrabalho, garantindo que todos que o utilizam enxerguem a informação da mesma forma. Isso também facilita ajustes futuros: ao alterar o Widget uma única vez, a mudança se reflete em todos os dashboards que o utilizam.

Exemplos

Um Widget do tipo Gráfico pode ser criado, por exemplo, para exibir em barras verticais o total vendido por vendedor, em linha a evolução de um valor ao longo de um período, ou em pizza a participação de cada categoria em um total. Um Widget do tipo Indicador pode destacar, por exemplo, o total de pedidos em aberto, o valor total de contas a receber vencidas, ou a quantidade de itens abaixo do estoque mínimo. Um Widget do tipo Grade pode listar, por exemplo, o saldo e o saldo previsto de cada conta bancária, com o total das contas no rodapé.

Cadastro

O cadastro de Widget é organizado nas abas Geral, Campo X, Colunas, Campos e Expressão SQL.

Geral

• Nome: Nome interno do widget.
• Título: Título exibido no widget.
• Tamanho Fonte Título: Tamanho da fonte utilizada no título.
• Tipo de Widget: Define se este widget é um Gráfico, um Indicador ou uma Grade. Os campos abaixo marcados como "somente Gráfico" só têm efeito nesse tipo.
• Tipo de Gráfico (somente Gráfico): Define o formato de exibição (veja tabela de tipos abaixo).
• Exibir o Título: Define se o título é exibido.
• Exibir valores (somente Gráfico): Define se os valores são exibidos junto aos elementos do gráfico.
• Data/Hora: Data e horário da última alteração. Preenchido automaticamente pelo sistema.

Tipo de Gráfico	Descrição
Barra Horizontal	Exibe os valores em barras dispostas horizontalmente.
Barra Vertical	Exibe os valores em barras dispostas verticalmente (colunas).
Linha	Exibe os valores como uma série contínua, indicada para visualizar tendências ao longo de um período.
Pizza	Exibe os valores como percentual de participação em relação ao total.

Campo X

• Campo X (Gráfico e Indicador): Campo, catalogado a partir da Expressão SQL (veja Campos abaixo), utilizado como rótulo/categoria no Gráfico ou como valor exibido no Indicador.
• Tamanho da Fonte (somente Gráfico): Tamanho da fonte utilizado nos rótulos do eixo.
• Posição da Legenda (somente Gráfico): Define onde a legenda é exibida (Superior, Esquerda, Direita, Inferior ou Dentro do gráfico).
• Cor da Barra ou Linha (Gráfico) / Cor do Valor (Indicador): mesmo campo, reaproveitado com papel diferente conforme o Tipo de Widget.
• Cor do Fundo da Barra (Gráfico) / Cor de Fundo do Card (Indicador): mesmo campo, reaproveitado com papel diferente conforme o Tipo de Widget.
• Cor de Identificação (somente Indicador): Cor do texto de identificação/título do card.
• Tipo de Série / Campo Série (somente Gráfico, opcional): permite que uma mesma consulta gere várias séries lado a lado (ex.: uma barra por vendedor dentro de cada mês), a partir do valor de um campo adicional da Expressão SQL. Sem essa configuração, o gráfico exibe uma série única.
• Campo Ordenação (Gráfico e Grade, opcional): campo, catalogado a partir da Expressão SQL, usado para ordenar os dados. No Gráfico, serve para quando o próprio Campo X não ordena da forma esperada (por exemplo, Campo X trazendo o nome do mês abreviado, que ordenaria em ordem alfabética em vez de cronológica); sem essa configuração, a ordenação segue o próprio Campo X. Na Grade, define a ordem das linhas: crescente, ou decrescente quando o campo é do tipo valor; sem essa configuração, as linhas seguem a ordem em que a consulta as devolver.
• Ranking (Gráfico e Grade, opcional): No Gráfico, limita a exibição às categorias de maior valor. Na Grade, é o limite de linhas exibidas; em branco ou zero, a grade exibe até 500 linhas. Quando a consulta traz mais linhas que o limite, a grade avisa que está exibindo somente as primeiras.
• Destacar Diferença (somente Gráfico, opcional): em vez da barra partir sempre do zero, passa a partir de perto do menor valor da série — útil quando os valores são próximos entre si e distantes de zero, tornando a diferença entre eles mais visível.
• Arredondamento inicial da barra de fundo / Arredondamento inicial da barra (somente Gráfico): Controlam o arredondamento no início da barra e do seu fundo.
• Arredondamento final da barra de fundo / Arredondamento final da barra (somente Gráfico): Controlam o arredondamento no final da barra e do seu fundo.
• Exibir o fundo da barra (somente Gráfico): Define se o fundo/trilho da barra é exibido.

Colunas (Gráfico e Grade) No Gráfico, cada linha desta grade representa uma série de valores exibida no gráfico. Na Grade, cada linha representa uma coluna da tabela, na ordem da Sequência.

• Sequência: Ordem da série no Gráfico, ou da coluna na Grade.
• Legenda: Texto de legenda da série no Gráfico, ou título da coluna na Grade. Na Grade, em branco, é usado o nome do campo.
• Campo Valor: Campo, catalogado a partir da Expressão SQL. No Gráfico, precisa ser do tipo valor, e seu valor é somado e exibido na série. Na Grade, pode ser de qualquer tipo (texto, data ou valor) e é o conteúdo exibido na coluna.
• Exibir Percentual: Quando marcado, exibe o percentual sobre o total da série (Gráfico) ou sobre o total da coluna (Grade), em vez do valor. Na Grade, somente para campos do tipo valor.
• Totalizar (somente Grade): Quando marcado, a coluna é somada no rodapé da grade. Somente para campos do tipo valor. O total considera todas as linhas da consulta, inclusive as que passaram do limite de linhas.
• Cor da Fonte do Valor / Cor da Fonte do Valor (alternativa): No Gráfico, cores utilizadas no texto do valor, sendo a segunda aplicada quando o valor é exibido sobre um fundo colorido (dentro da barra ou fatia). Na Grade, a primeira é a cor do texto da coluna e a segunda, a cor dos valores negativos.
• Formato: Máscara de formatação numérica do valor (separador de milhar, casas decimais). Vem preenchida automaticamente conforme o tipo do campo ao catalogá-lo (veja Campos abaixo).

Campos Grade com os campos catalogados a partir do resultado da Expressão SQL — é dessa lista que vêm as opções disponíveis para seleção em Campo X, Campo Série, Campo Ordenação (aba Campo X) e Campo Valor (aba Colunas).

• Nome: Nome do campo, igual ao nome da coluna retornada pela Expressão SQL.
• Tipo: Tipo do campo (texto, data ou valor), identificado automaticamente a partir do tipo de dado retornado pela consulta. Na Grade, define o alinhamento e a exibição da coluna: valores à direita com o Formato do campo, datas no formato dia/mês/ano.
• Formato: Máscara de formatação, preenchida automaticamente para campos do tipo valor.
• Incluir Campos: Botão que executa a Expressão SQL e cataloga nesta grade os campos do resultado que ainda não estiverem cadastrados.

Expressão SQL Aba onde é escrita a consulta SQL responsável por buscar os dados do widget. A consulta deve retornar as linhas de detalhe, sem GROUP BY. No Gráfico e no Indicador, não é ela quem soma ou agrupa os valores: isso é feito automaticamente a partir do que for configurado em Campo X/Campo Série/Colunas. Na Grade, cada linha da consulta é uma linha da tabela.

Como Configurar um Widget

Esta seção resume o que precisa ser feito para deixar um Widget pronto para uso em um Dashboard.

Na aba Expressão SQL, escreva a consulta que retorna os dados desejados, sem agrupar ou somar nada — cada linha do resultado deve ser um registro de detalhe. Na aba Campos, clique em "Incluir Campos" para catalogar os campos retornados pela consulta. Na aba Geral, informe Nome, Título e escolha o Tipo de Widget (Gráfico, Indicador ou Grade) e, se Gráfico, o Tipo de Gráfico. Se o Tipo de Widget for Gráfico ou Indicador, na aba Campo X selecione o Campo X (categoria, no Gráfico, ou o próprio valor, no Indicador) dentre os campos já catalogados, e configure a aparência (cores, arredondamento, fundo, legenda). Se precisar de séries lado a lado ou de uma ordenação diferente do Campo X, configure também Campo Série e Campo Ordenação. Se o Tipo de Widget for Grade, na aba Campo X informe, se desejar, o Campo Ordenação e o Ranking (limite de linhas). Se o Tipo de Widget for Gráfico, na aba Colunas cadastre uma ou mais colunas de valor, selecionando o Campo Valor já catalogado, a legenda e a cor. Se o Tipo de Widget for Grade, na aba Colunas cadastre uma linha para cada coluna da tabela, selecionando o Campo Valor, a legenda (título da coluna) e, nas colunas de valor, se devem ser totalizadas. Salve o cadastro. O Widget já pode ser selecionado no campo Widget de um Item do Dashboard.

Pontos de atenção

• A Expressão SQL não deve conter GROUP BY — no Gráfico e no Indicador, o próprio widget agrupa e soma os dados a partir do Campo X, Campo Série e das Colunas de valor configuradas; na Grade, as linhas são exibidas como vierem da consulta.
• Campo X, Campo Série, Campo Ordenação e Campo Valor só oferecem para seleção os campos já catalogados na aba Campos ("Incluir Campos") — se alterar a Expressão SQL depois, catalogue os campos novamente.
• Na Grade, Totalizar e Exibir Percentual só se aplicam a colunas cujo campo é do tipo valor.
• Qualquer campo retornado pela Expressão SQL (mesmo que não usado em Campo X, Série ou Colunas) fica disponível para ser usado como Filtro do Item no Dashboard.

Conclusão

O cadastro de Widget é o responsável por definir, em um único lugar, tanto a origem dos dados (a Expressão SQL) quanto a forma como eles são apresentados visualmente — seja como Gráfico, Indicador ou Grade. Por ser independente do Dashboard em si, um mesmo Widget pode ser reaproveitado em diferentes dashboards, facilitando a manutenção e garantindo consistência visual entre eles.

Assuntos Relacionados

Dashboards