Histórico da Página
...
- Visão Geral
- Construindo uma API de negócio para uso nos Monitores
- Api de negócio
- Classes Utilitárias (Felicitadores)
- Criando o seu primeiro monitor
01. VISÃO GERAL
Esse documento possui as informações necessárias para que uma pessoa com conhecimentos em programação na linguagem Progress 4GL possa desenvolver e integrar uma API específica para utilização no painel de Gestão à Vista. Serão detalhados os principais métodos, parâmetros e funções que deverão ser implementados na API para torná-la compatível com a aplicação.
...
Nome | Descrição |
---|---|
ChartBuilder | Utilitário para auxiliar na criação de monitores do tipo Gráficos. |
InfoBuilder | Utilitário para auxiliar na criação de monitores do tipo Texto. |
DetailBuilder | Utilitário para auxiliar na criação de interfaces de detalhamento dos dados de um monitor. |
02.A.1 Monitor tipo INFO
Esse tipo de monitor é bastante flexível, permitindo criar layouts diferenciados conforme necessário. Ele é formado por linhas, cuja aparência, altura, largura e conteúdo mudam conforme o retorno da API. É possível customizar cada uma dessas linhas com classes e estilos nativos do HTML, além de ícones do PO-UI. Se o monitor que você está planejando construir for do tipo INFO (texto), confira as informações abaixo:
Estrutura geral
Obs: As linhas seguem o grid system do PO-UI. Veja mais em https://po-ui.io/guides/grid-system
Implementação
A Procedure pi-get-monitor-data-info deve ser implementada pela API de negócio e deverá retornar um objeto JSON estruturado, ou a tabela RowErrors, caso tenha ocorrido algum erro. É passada como Input a ttVisaoMonitor que contém as informações de qual monitor está sendo processado nesse momento.
Informações | ||
---|---|---|
| ||
Certifique-se que os nomes das Procedures estejam exatamente iguais ao que consta na documentação (pi-get-monitor-data-info e/ou pi-get-monitor-data-chart), caso contrário o painel de Gestão à vista irá emitir um erro e os dados não serão carregados. |
Bloco de código | ||||
---|---|---|---|---|
| ||||
PROCEDURE pi-get-monitor-data-info:
DEFINE INPUT PARAMETER TABLE FOR ttVisaoMonitor.
DEFINE OUTPUT PARAMETER oOutput AS JsonObject.
DEFINE OUTPUT PARAMETER TABLE FOR RowErrors. |
O objeto JSON será construído através da classe utilitária InfoBuilder, que utiliza as seguintes temp-tables:
ttMonitorMetadados (opcional)
Guarda algumas configurações básicas que o monitor irá assumir, como alturas máximas e mínimas e cores do título e do widget principal. Se não forem definidas, serão utilizadas configurações padrões.
...
ttMonitorInfoLinha
Contém as linhas que formarão os dados do monitor. Cada registro da temp-table representa uma linha na aplicação, que será convertida em uma DIV no HTML. É possível customizar cada linha com classes e estilos HTML, além de ícones do PO-UI. Utilizando as classes do grid system do PO-UI, podemos montar um layout bastante flexível para o monitor.
...
ttTags(opcional)
Temp-table com as definições das PO-TAGS que serão exibidas abaixo do título do monitor.
...
Depois de criar os registros necessários nas temp-tables, a API deverá passá-las como parâmetro para o InfoBuilder para que o monitor seja criado, conforme exemplo:
Bloco de código | ||
---|---|---|
| ||
USING cdp.services.gestaoavista.*. //A classe InfoBuilder está definida aqui.
DEFINE VARIABLE InfoBuilder AS InfoBuilder NO-UNDO.
InfoBuilder = NEW InfoBuilder(INPUT TABLE ttVisaoMonitor).
// Setamos as tags, parâmetros e linhas que irão compor o monitor
InfoBuilder:setTags(INPUT TABLE ttTags).
InfoBuilder:setParameters(INPUT TABLE ttMonitorMetadados).
InfoBuilder:setLines(INPUT TABLE ttMonitorInfoLinha).
oOutput = NEW JsonObject().
oOutput = InfoBuilder:createMonitor(). // Chama o método que cria e devolve o monitor pronto
DELETE OBJECT InfoBuilder. |
Exemplo de retorno
Depois que a API de negócio chama o método createMonitor da classe InfoBuilder e o método pi-get-monitor-data-info finaliza sua execução, os dados serão enviá-los para o painel de monitoramento para visualização.
Bloco de código | ||
---|---|---|
| ||
Exemplo de JSON de retorno para um monitor do tipo INFO.
{
"alturaMaximaWidget": null,
"alturaMinimaWidget": null,
"corFundo": "#26BA41",
"corFundoPreenchidoProgresso": "#004e17",
"corFundoProgresso": "#FFFFFF",
"corTextoProgresso": "#FFFFFF",
"corTitulo": "#FFFFFF",
"linhas": [
{
"classeTexto": "po-font-title po-text-center po-sm-12 po-p-1 bold-text",
"icone": "po-icon-manufacture",
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Produzindo",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0 po-pt-1 po-clickable",
"icone": null,
"parametrosDetalhe": "detalhaOrdem:1003",
"styleTexto": "{\"color\":\"white\"}",
"texto": "Ordem <b> 1.003</b> <span class=\"po-icon po-icon-export\"></span>",
"tipo": null,
"tipoDetalhe": "externo",
"tituloProgresso": null,
"urlDetalhe": "html.productionOrder",
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0 no-overflow",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Item <b>sp-item-a</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Operação <b>10 - montar</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Split <b>1</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-sm-12 po-pr-1 po-pt-1 po-pl-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": null,
"texto": null,
"tipo": "progresso",
"tipoDetalhe": null,
"tituloProgresso": "% Conclusão: 50%",
"urlDetalhe": null,
"valorProgresso": 50
}
],
"tags": [
{
"colorTexto": "white",
"icone": "po-icon-manufacture",
"texto": "CT-SAME"
}
]
} |
Resultado:
02.A.2 Monitor tipo Gráfico (chart)
O monitor do tipo gráfico apresenta as informações de uma maneira visual, através do componente PO-CHART. Dependendo do monitor, podem ser utilizados os tipos Barra, Coluna, Pizza, Linhas ou Rosca. Os tipos de gráficos disponíveis dependem totalmente da API de negócio, portanto fica a cargo do programador prepará-la para suportar um ou mais tipos.
Estrutura geral
A API de negócio precisará implementar o método pi-get-monitor-data-chart que, da mesma forma que ocorre com o monitor do tipo Texto, irá devolver o JSON de retorno com o gráfico já estruturado. Esse objeto terá as mesmas propriedades de um PO-CHART (categorias e series), além das tags.
Bloco de código | ||||
---|---|---|---|---|
| ||||
PROCEDURE pi-get-monitor-data-chart:
DEFINE INPUT PARAMETER TABLE FOR ttVisaoMonitor.
DEFINE OUTPUT PARAMETER oOutput AS JsonObject.
DEFINE OUTPUT PARAMETER TABLE FOR RowErrors. |
O objeto JSON será construído através da classe utilitária ChartBuilder, que utiliza as seguintes temp-tables:
ttTags(opcional)
Temp-table com as definições das PO-TAGS que serão exibidas abaixo do título do monitor.
...
Propriedade na temp-table
...
Descrição
...
SERIALIZE-NAME (JSON)
...
ttCategorias
Define os nomes das categorias que serão plotadas no eixo X do gráfico caso seja do tipo colunas, ou então nos eixos Y do grid de gráficos dos tipos barras e linhas. Para maiores informações, consulte a documentação da propriedade categories do PO-CHART.
...
Propriedade na temp-table
...
Descrição
...
ttSeries
São os objetos de série do gráfico, que representam as colunas/fatias/linhas, conforme o tipo de gráfico. Possui as mesmas propriedades do objeto Series do PO-CHART.
...
Altura (opcional)
Altura que o gráfico terá dentro do widget. Para atribuir a altura, utilize o método setHeight() do ChartBuilder.
Depois de criar as temp-tables necessárias na aplicação, utilizamos a classe ChartBuilder para gerar o gráfico, conforme abaixo:
Bloco de código | ||
---|---|---|
| ||
USING cdp.services.gestaoavista.*. //A classe ChartBuilder está definida aqui.
DEFINE VARIABLE ChartBuilder AS ChartBuilder NO-UNDO.
// Instanciar a classe passando como parâmetro a ttVisaoMonitor, que contém as informações do monitor e visão que estão sendo processados nesse instante
ChartBuilder = NEW ChartBuilder(INPUT TABLE ttVisaoMonitor).
/* Depois que todas as entidades estão criadas, basta setá-las no objeto ChartBuilder */
ChartBuilder:setTags(INPUT TABLE ttTags).
ChartBuilder:setSeries(INPUT TABLE ttSeries).
ChartBuilder:setCategories(INPUT TABLE ttCategorias).
ChartBuilder:setHeight(290).
/* Chama o método para criar e devolver o gráfico completo e guarda o resultado na variável oOutput */
oOutput = ChartBuilder:createChart().
DELETE OBJECT ChartBuilder. |
Bloco de código | ||||
---|---|---|---|---|
| ||||
Exemplo de JSON para monitor do tipo Gráfico de Pizza
{
"altura": 290,
"categorias": [
"Estados dos CTs"
],
"series": [
{
"color": "#F50031",
"data": 1.0,
"label": "Parado",
"tooltip": "",
"type": "pie"
},
{
"color": "#26BA41",
"data": 2.0,
"label": "Produzindo",
"tooltip": "",
"type": "pie"
},
{
"color": "#007acc",
"data": 1,
"label": "Setup",
"tooltip": "",
"type": "pie"
},
{
"color": "#A0B9BF",
"data": 3.0,
"label": "Ocioso",
"tooltip": "",
"type": "pie"
}
],
"tags": [
{
"colorTexto": "",
"icone": "po-icon-pin",
"texto": "Área: 002"
},
{
"colorTexto": "",
"icone": "po-icon-manufacture",
"texto": "Produzido: 8,0000 "
},
{
"colorTexto": "",
"icone": "po-icon-document-filled",
"texto": "Previsto: 220,0000 "
},
{
"colorTexto": "",
"icone": "po-icon-minus-circle",
"texto": "Refugado: 2,0000"
}
]
} |
Resultado
02.B Endpoint api/cdp/v1/monitor/details
Endpoint que é chamado ao clicar na opção Detalhar localizada no drop-down (ícone ... ) ou sobre alguma Série do po-chart em monitores gráficos. Será utilizado quando o monitor possuir tipo de detalhe definido como modal ou detalhe.
O tipo de detalhe modal irá exibir uma janela simples, ocupando apenas parte da tela e sobrepondo o próprio monitor. O tipo detalhe irá navegar para uma nova página dentro do portal de monitoramento, com uma área maior para utilização. Ambos os tipos possuem a mesma estrutura geral, que é:
A API de negócio cadastrada para o monitor deverá possuir um método chamado pi-get-monitor-detail que precisará retornar a estrutura do detalhe. Ela receberá os seguintes parâmetros:
Bloco de código | ||
---|---|---|
| ||
PROCEDURE pi-get-monitor-detail:
DEFINE INPUT PARAM TABLE FOR ttVisaoMonitor.
DEFINE INPUT PARAM iPage AS INTEGER NO-UNDO.
DEFINE INPUT PARAM cSerie AS CHARACTER NO-UNDO.
DEFINE INPUT PARAM cCategory AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAM aItems AS JsonArray NO-UNDO.
DEFINE OUTPUT PARAM lHasNext AS LOGICAL NO-UNDO.
DEFINE OUTPUT PARAM lCanExportXLS AS LOGICAL INITIAL YES NO-UNDO.
DEFINE OUTPUT PARAM cModalMaxWidth AS CHARACTER INITIAL "1440px" NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR ttColunaDetalhe.
DEFINE OUTPUT PARAM TABLE FOR ttHeadersDetalhe.
DEFINE OUTPUT PARAM TABLE FOR ttMonitorTag.
DEFINE OUTPUT PARAM TABLE FOR RowErrors. |
Parâmetros de entrada
ttVisaoMonitor
Tabela utilizada em várias procedures para identificar qual monitor está sendo processado no momento e que contém os metadados e configurações dele. Se a API de negócio for responsável por mais de um monitor, essa temp-table pode ser usada para redirecionar para os métodos corretos.
...
iPage
Número da página atual para ser utilizada na paginação da query. Sempre que o usuário clicar em Exibir mais resultados na modal ou página de detalhe genérica, esse número será incrementado em 1.
cSerie
Se o usuário clicar sobre uma série do po-chart de um monitor do tipo gráfico, essa variável conterá o nome dessa série. Ela pode ser usada para aplicar um filtro na query para que sejam exibidos apenas os dados referentes à série na modal/página de detalhe.
cCategory
Se o monitor for do tipo Chart e possuir uma categoria, será passada através dessa variável.
Parâmetros de sáida
aItems
Array com os objetos de negócio que serão exibidos na tabela, que segue a mesma lógica dos itens da PO-TABLE. As propriedades de cada objeto devem bater com a definição de colunas existentes na propriedade Columns.
lHasNext
Utilizado para paginação. Caso o valor dessa propriedade seja True, o botão Buscar mais resultados ficará habilitado, tanto na modal quanto na tela de detalhe genérico.
lCanExportXLS (opcional)
Determina se o botão de Exportar para Planilha ficará habilitado na modal ou tela genérica de detalhe. A exportação é dinâmica e irá gerar um arquivo .csv com as definições de colunas e dados conforme o objeto retornado automaticamente.
cModalMaxWidth (opcional)
Se o detalhamento for via modal, essa propriedade define o tamanho máximo que ela poderá assumir na tela.
ttColunaDetalhe
Temp-table que herda a estrutura do PoTableColumn(https://po-ui.io/documentation/po-table)
e possui algumas propriedades adicionais, que servirão para aplicar a técnica de detalhamento de uma coluna da tabela (opcional). Ao clicar sobre uma coluna que possui detalhamento, será aberta uma tela HTML externa, que deverá estar preparada para verificar a LocalStorage do navegador e capturar os parâmetros que serão inclusos pelo painel de Monitoramento.
...
05. CRIANDO SEU PRIMEIRO MONITOR
Crie o seu primeiro monitor seguindo este guia de passo a passo: Criando seu primeiro Monitor Exclusivo (Getting Started)
ttHeadersDetalhe (opcional)
Temp-table contendo registros que serão renderizados no cabeçalho da Modal ou na tela de detalhe genérico na forma de um quadrado que pode ser estilizado através dos campos classe-header e estilo-header. Útil para criar um “cabeçalho” para contextualizar as informações que estão contidas na tabela.
...
ttMonitorTag (opcional)
Temp-table contendo registros que se tornarão PO-TAGS, que pode ser usado para exibir dados importantes e concisos de forma compacta. As tags ficarão abaixo dos headers, se existirem.
...
Depois que a API de negócio retornar as temp-tables detalhadas acima, elas serão convertidas num JSON com o seguinte formato:
Bloco de código |
---|
Query params:
codMonitor=<monitor>&codVisao=<visao>&sequencia=<seq>&pagina=1
&tipo=<tipo>&subtipo=<sub>&serie=<serie>
Estrutura do JSON
{
"canExportXLS": true,
"columns": [
{
"detailUrl": "string (opcional)",
"format": "string (opcional)",
"label": "string",
"property": "string",
"type": "string (opcional)",
"width": "string (opcional)",
"parameterLabels": [
"string (opcional)"
],
"parameterProperty": [
"string (opcional)"
],
}
],
"items": [
{
<Objeto de negócio>
}
],
"headers": [
{
"headerText":"string (opcional)",
"headerClass":"string (opcional)",
"headerStyle":"string (opcional)"
}
],
"tags": [
{
"colorTexto": "string (opcional)",
"icone": "string (opcional)",
"texto": "string (opcional)"
}
],
"modalMaxWidth": "string",
"hasNext": boolean,
} |
Bloco de código |
---|
Exemplo detalhamento via Modal com coluna detalhe externo
{
"columns": [
{
"label": "Ordem",
"property": "productionOrderNumber",
"type": "cellTemplate",
"detailUrl": "html.productionOrder",
"format": null,
"parameterLabels": [
"detalhaOP"
],
"parameterProperty": [
"productionOrderNumber"
],
},
{
"label": "Item",
"property": "itemCode",
"type": null,
"format": null
}
[...]
],
"items": [
{
"itemCode": "me2017a",
"productionOrderNumber": "1035"
[...]
}
],
"tags": [
{
"colorTexto": null,
"icone": null,
"texto": "GGF sem ACA"
}
],
"hasNext": false,
"modalMaxWidth": "1440px",
} |
Resultado:
Repare que o campo Ordem está destacado. Isso acontece quando a coluna correspondente à informação possui o tipo cellTemplate, e indica que o campo é clicável. Caso o usuário clique em alguma ordem, o sistema irá incluir novas entradas no LocalStorage do navegador, com chave:valor conforme as propriedades parameterLabels e parameterProperty da coluna.
Utilizando o exemplo acima, considerando que o usuário clicou na ordem 1051 ficaria:
Bloco de código |
---|
{
"detalhaOP": "1051"
} |
São suportados até 10 parâmetros pra cada coluna. Dessa forma, quando a tela externa for chamada, poderá buscar na localStorage pelos parâmetros e posicionar na listagem/detalhe o registro que foi clicado. Deve-se atentar para que cada chave:valor fique na mesma posição de index em seus respectivos arrays.
Bloco de código |
---|
Exemplo detalhamento via Detalhe genérico
{
"items": [
{
"H6_FILIAL": "01",
"H6_OP": " ",
"H6_PRODUTO": "MOD000000001 ",
"B1_DESC": "MOD000000001 ",
"H6_OPERAC": " ",
"G2_DESCRI": "",
"H6_RECURSO": "000001",
"H1_DESCRI": "RECURSO 000001",
"H6_DTAPONT": "2023-03-29",
"H6_DATAINI": "2023-03-29",
"H6_HORAINI": "10:00",
"H6_DATAFIN": "2023-03-29",
"H6_HORAFIN": "10:30",
"H6_TEMPO": "0.5",
"H6_QTDPROD": 0,
"H6_QTDPERD": 0.5,
"H6_TIPO": "I"
},
{ ...demais itens... }
],
"columns": [
{
"property": "H6_FILIAL",
"label": "Filial",
"type": "string",
"visible": false
},
{
"property": "H6_TIPO",
"label": "Tp Apon",
"type": "cellTemplate",
"labels": [
{
"value": "I",
"color": "rgb(241,143,136)",
"label": "Improdutivo",
"textColor": "rgb(255,255,255)"
},
{
"value": "P",
"color": "rgb(126,226,148)",
"label": "Produtivo",
"textColor": "rgb(255,255,255)"
}
],
"visible": true
},
{
"property": "H6_RECURSO",
"label": "Recurso",
"type": "string",
"visible": true
},
{
"property": "H1_DESCRI",
"label": "Desc Recurso",
"type": "string",
"visible": false
},
{
"property": "H6_OP",
"label": "OP",
"type": "string",
"visible": true
},
{
"property": "H6_PRODUTO",
"label": "Produto",
"type": "string",
"visible": true
},
{
"property": "B1_DESC",
"label": "Desc Produto",
"type": "string",
"visible": false
},
{
"property": "H6_OPERAC",
"label": "Operação",
"type": "string",
"visible": true
},
{
"property": "G2_DESCRI",
"label": "Desc Oper",
"type": "string",
"visible": false
},
{
"property": "H6_TEMPO",
"label": "Tempo",
"type": "string",
"visible": true
},
{
"property": "H6_DTAPONT",
"label": "Dt Apont",
"type": "date",
"visible": false
},
{
"property": "H6_DATAINI",
"label": "Dt Ini",
"type": "date",
"visible": true
},
{
"property": "H6_HORAINI",
"label": "Hora Ini",
"type": "string",
"visible": false
},
{
"property": "H6_DATAFIN",
"label": "Dt Fin",
"type": "date",
"visible": false
},
{
"property": "H6_HORAFIN",
"label": "Hora Fin",
"type": "string",
"visible": false
},
{
"property": "H6_QTDPROD",
"label": "Qtd Prod",
"type": "number",
"visible": false
},
{
"property": "H6_QTDPERD",
"label": "Qtd Perda",
"type": "number",
"visible": false
}
],
"canExportCSV": true,
"tags": [
{
"icone": "po-icon-calendar",
"texto": "12/02/23 - 02/06/23",
"colorTexto": ""
},
{
"icone": "po-icon-calculator",
"texto": "Semanal",
"colorTexto": ""
},
{
"icone": "po-icon-star-filled",
"texto": "Tempo Prod. Total: 31.58 Horas",
"colorTexto": ""
}
],
"hasNext": true
} |
Resultado:
03. TELA XXXXX
Outras Ações / Ações relacionadas
...
04. TELA XXXXX
Principais Campos e Parâmetros
...
Card documentos | ||||
---|---|---|---|---|
|
...