PHSYS - Wiki

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) ou como Indicador (um único valor em destaque), 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. As abas Campo X e Colunas só se aplicam quando o Tipo de Widget é Gráfico — quando é Indicador, o próprio Campo X passa a fornecer o valor único exibido no card, e a aba Colunas não é utilizada.

A Expressão SQL deve retornar as linhas de detalhe, sem GROUP BY: 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. Isso permite que qualquer campo retornado pela consulta — mesmo um usado só para calcular o Campo X, sem aparecer diretamente no gráfico — 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 — tanto números em destaque quanto gráficos — 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.

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 ou um Indicador. 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: 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 (somente Gráfico, opcional): campo, catalogado a partir da Expressão SQL, usado para ordenar o gráfico 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.
• 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 (somente Gráfico) Cada linha desta grade representa uma série de valores exibida no gráfico:

• Sequência: Ordem da coluna de valores.
• Legenda: Texto de legenda associado a essa série.
• Campo Valor: Campo, catalogado a partir da Expressão SQL, cujo valor será somado e exibido nesta série.
• Cor da Fonte do Valor / Cor da Fonte do Valor (alternativa): Cores utilizadas no texto do valor, sendo a segunda aplicada quando o valor é exibido sobre um fundo colorido (dentro da barra ou fatia).
• 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.
• Formato: Máscara de formatação, preenchida automaticamente para campos do tipo valor.
• Incluir Campos: Botão que executa a Expressão SQL e catalога 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 — 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.

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 ou Indicador) e, se Gráfico, o Tipo de Gráfico. 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 Gráfico, na aba Colunas cadastre uma ou mais colunas de valor, selecionando o Campo Valor já catalogado, a legenda e a cor. 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 — o próprio widget agrupa e soma os dados a partir do Campo X, Campo Série e das Colunas de valor configuradas.
• 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.
• 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 ou como Indicador. 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

Dashboard