CONTEÚDO

01. INTRODUÇÃO / OBJETIVO

Temos como objetivo desta técnica, apresentar um MVP de como customizar as telas HTML, através de intervenções em API Rest no back-end Progress.O código de API abaixo pode possuir diferenças de estrutura comparado com a forma utilizada pelas equipes de negócio. Algumas equipes, por exemplo

Para que caso surja a necessidade do cliente final customizar o resultado de uma tela, ele possa fazer isso de forma dinâmica e em tempo de renderização.

Para isso vamos utilizar o Framework PO-UI como front-end e seus componentes dinâmicos, comunicando com back-end Datasul Progress.

Esta documentação pode ser usada tanto pelos desenvolvedores internos a fim de disponibilizar a customização no produto padrão, quanto pelos desenvolvedores externos que necessitam criar customizações nessas telas HTML. Porém, em algumas seções da documentação podem conter links disponíveis apenas para desenvolvedores internos. 

02. VISÃO GERAL

No PO-UI, uma tela dinâmica trabalha recebendo uma lista de informações que serão utilizadas para apresentar os componentes da tela, e uma outra lista contendo os dados que serão apresentados nestes componentes.

Nesta técnica, vamos apresentar como fornecer estas duas listas para o PO-UI, onde poderemos customizá-las de acordo com a necessidade.

Este guia será divido basicamente em duas partes, como vamos trabalhar no back-end Progress e acessar esses dados através do front-end PO-UI.

Abaixo temos um fluxo das informações do PO-UI até a UPC em Progress:

03. PRÉ-REQUISITOS

Temos como pré-requisito para execução da técnica citada abaixo: 

• API Rest desenvolvida no último padrão divulgado pelo Framework, utilizando a técnica de construção de APIs (Desenvolvimento de APIs para o produto Datasul);

• Utilização do Framework PO-UI na última versão disponível;

• Utilização do Framework Tomcat Datasul;

• Utilização da técnica de customização com EPC na api do programa a ser customizado;

• Tela preparada para a customização;

04. TÉCNICAS

Técnica Back-End Progress:

Introdução:

A técnica back-end Progress é formada pelos passos abaixo:

Construção de API REST para tela customizada:

Para que possamos customizar uma tela HTML construída em PO-UI, necessitamos que o back-end nos retorne qual o metadado e os valores da tela em questão através de uma API Rest.

Sendo assim essa API deve conter no mínimo dois endpoints básicos:

• Endpoint que retornará o metadados da tela;

• Endpoint para retornar os valores da tela;

Cadastro da API Rest no Cadastro de Programas (men012aa) com a respectiva UPC:

Tendo criado a API REST que retorna os dados básicos para a tela, partimos para o segundo passo, que é a preparação do endpoint da API para a customização.

Esta API deverá ser inserida no cadastro de programas (MEN012AA), onde poderemos também especificar a UPC que será utilizada.

Na técnica de construção de APIs REST é informado sobre a utilização da include "utp/ut-api.i", pois esta include identificará se a API possui uma UPC cadastrada ou não.

Técnica de customização com EPC

Utilizar a include "include/i-epcrest.i" para chamada UPC na API Rest :

Enfim para chamarmos um programa de customização, criamos uma include que fará esta chamada. Abaixo segue mais detalhes sobre esta include.

Ela encontra-se na pasta include e possui o nome i-epcrest.i, conforme o exemplo abaixo:

Pré-Processadores da include i-epcrest.i:

Abaixo temos a lista de pré-processadores que devem ser passados para a include i-epcrest.i:

Parâmetros recebidos na UPC da API REST:

Front-End PO-UI:

Introdução:

Para termos uma tela dinâmica, de acordo com o que o back-end retorna, precisamos utilizar os componentes dinâmicos ou as templates do PO-UI sendo eles:

Componentes:

• Dynamic-Form;

• Dynamic-View.

Templates:

• Page-Dynamic-Detail;

• Page-Dymic-Edit;

• Page-Dynamic-Search;

• Page-Dynamic-Table.

Comunicando com o Back-End Progress:

Basicamente para comunicar com o back-end teremos que ter dois serviços que irão alimentar as informações para tela:

• Metadado

  • Serviço que irá retornar os campos e as propriedades da tela;

• Values

  • Serviço que irá retornar os valores dos campos;

05. EXEMPLO DE UTILIZAÇÃO

Back-End Progress

Introdução:

Para exemplificar a técnica citada acima, criamos uma API Rest que irá retornar os dados da tabela de idiomas, chamando uma UPC que acrescenta algumas informações da tabela usuar_mestre.

Cadastro da UPC:

Primeiramente temos que cadastrar a API REST no cadastro de programas (MEN012AA) e também especificar a UPC a ser utilizada, conforme o exemplo abaixo:

Na aba Opções, teremos que especificar o Template como "API REST", conforme o exemplo abaixo:

Acessar a opção "Grupo de segurança" e configurar os grupos de segurança que terão acesso à API que está sendo cadastrada.

API Rest com chamada de UPC:

Abaixo temos um exemplo de API REST com suas procedures que são:

• pGetMetaData que retorna os metadados das telas;

• pFindAll que retorna os valores dos campos em questão;

• pFindById que retorna um registro de um determinado ID;

• pCreate que cria um novo registro;

• pUpdateById que altera um registro de um determinado ID;

• pDeleteById que elimina 1 ou mais registros.

Como podemos verificar todas as procedures possuem chamadas para o programa de UPC:

Programa UPC:

Abaixo temos um exemplo de uma UPC criada para a API REST:

Resultado ao chamar à API tendo uma UPC cadastrada:

Ao fazer as requisições, virão os seguintes resultados na UPC.

Front-End PO-UI

Introdução:

Para este exemplo vamos criar um CRUD com template dinâmico, onde serão mostrados os dados de acordo com o que o back-end retornar.

O desenvolvimento do front-end utilizando este campo componente se divide basicamente em três partes:

• Routes:

  • Na definição da rota é onde vamos definir todos os caminhos dos componentes;

• HTML

  • No HTML basta colocarmos os componentes, pois o metadados irá retornar o que precisamos para renderizar o componente;

• TypeScript

  • No Typescript do componente vamos realizar uma pequena lógica para o tratamento dos dados de acordo com metadado;

Abaixo vamos mostrar como ficaram a parte de Listagem, Edição e Detalhe do nosso CRUD dinâmico.

Routes:

Abaixo segue exemplo de como ficará o arquivo de rotas de nossa aplicação CRUD.

Listagem:

É a tela inicial da nossa aplicação e mostra a lista de dados da tabela Idioma, onde foram adicionados através de customização três campos da tabela usuar_mestre. Esta tela dará acesso às outras funcionalidades como edição e detalhamento.

Edição: 

Esta tela permite a inclusão de um novo registro na tabela Idioma e também a alteração de registros já existentes.

Detalhe:

Esta tela apresenta os detalhes de um registro de Idioma, com suas customizações.

06. VALIDAÇÃO DE COMPONENTES

Para os itens a seguir, são apresentados algumas formas de interação com os componentes presentes na interface, bem como possíveis validações sobre os mesmos. 

Esconder ou visualizar os campos

Como a geração da tela dinâmica é automática, para esconder determinados campos basta setar o atributo visible para FALSE na montagem do JsonObject de retorno do metadados. 

Validação de componentes na interface

Uma boa prática em desenvolvimento de telas é a validação de alguns campos na própria interface, cujo intuito é reduzir requisições desnecessárias ao 'back-end'. As funcionalidades apresentadas a seguir podem ser utilizadas em conjunto com a validação do próprio Form ([p-disable-submit]="formEdit.form.invalid"), no qual pode desabilitar o botão de confirmação enquanto houver campos inválidos.

Utilização do pattern (RegEx)

Para a validação de campos textos, pode ser utilizado o atributo pattern qualquer expressão regular, caso não atenda ao RegEx, uma mensagem de erro definida em errorMessage é apresentada em tela. 

Utilização de limites em numeração

Com a utilização dos atributos minValue e maxValue, é possível efetuar a restrição de períodos da numeração que pode ser utilizado em conjunto com o type para restringir a digitação em somente números. Caso houver números inválidos, a mensagem definida em errorMessage é apresentada na tela.

Utilização de máscaras para os campos

Quando é definida uma máscara mask, ocorre a restrição de digitação no próprio campo. Para o exemplo abaixo, é permitido digitar somente números e ao efetuar a digitação, a máscara será aplicada automaticamente.

Validações no back-end

O po-dynamic-form permite dois tipos de validações, a validação do formulário completo ou por campo.

A validação do formulário completo vamos detalhar mais a frente.

A validação por campo é feito através da validação campo-a-campo, onde você conseguirá alterar algumas características do campo que esta sendo validado.

A adição da tag validate na definição do campo, onde deverá ser especificado a URL de validação, fará com que sempre que o campo for alterado pelo usuário, será enviado uma requisição para o back-end para realizar a validação desse campo.

JSon que recebemos da tela HTML

O componente PO-DYNAMIC-FORM, quando ocorre alguma alteração em seus campos, no LEAVE do campo, ele enviará um JSon com o seguinte formato para o back-end:

Onde o back-end receberá o seguinte JSon:

JSon que retornamos para a tela HTML

A validação do campo, aguarda o seguinte formato de JSon:

O back-end, após processar e realizar a validação necessária, retornará para o front-end o seguinte JSon:

Para utilizarmos a UPC de customização, tivemos que encapsular o JSon recebido no back-end, dentro da procedure pValidateField, e também o JSon a ser enviado para a tela HTML, conforme o exemplo abaixo:

Neste nosso exemplo, nós dividimos o JSon a ser enviado para UPC em três partes, que são:

Exemplo de JSon recebido pela UPC:

Após a customização pela UPC, será devolvida para a API Rest apenas a tag root, com as customizações necessárias, conforme o exemplo abaixo onde temos o resultado de uma customização:

07. VALIDAÇÃO DE FORMULÁRIOS

O quê deve ser alterado no componente PO-DYNAMIC-FORM

Para validarmos um formulário, temos que configurar primeiro o nosso componente po-dynamic-form para ficar apto a enviar as ocorrências de validações. Para isso temos que especificar algumas propriedades no componente po-dynamic-form, são elas:

• p-validate: onde informamos a URL que fará a validação do formulário, neste exemplo será "/api/trn/v1/idiomas/validateForm".

• p-validate-fields: somente o p-validate não fará com que as requisições de validação sejam executadas, é preciso definir a propriedade p-validate-fields que recebe um array de strings (Ex.: ['codIdioma','desIdioma']) com os campos que irão disparar a requisição ao serviço indicado na propriedade validate, quando estes forem alterados. Essa informação deve vir no metadata de edição para que seja possível customizar as validações de formulário.

JSon que recebemos da tela HTML

O componente PO-DYNAMIC-FORM, quando ocorre alguma alteração nos campos indicados no validateFields e ao sair destes campos, realizará uma requisição ao endPoint de validateForm e enviará um JSon com o seguinte formato para o back-end:

Exemplo de Json:

JSon que teremos que retornar para a tela HTML

As validações do formulário, aguardam o seguinte formato de JSon:

Para retornar as informações para o PO-UI, temos que devolver o seguinte JSon:

Para utilizarmos a UPC de customização, tivemos que encapsular o JSon recebido no back-end, dentro da procedure pValidateForm, e tambem o JSon a ser enviado para a tela HTML, conforme o exemplo abaixo:

Neste nosso exemplo, nós dividimos o JSon a ser enviado para UPC em três partes, que são:

Exemplo de JSon recebido pela UPC:

Após a customização pela UPC, será devolvido para a API Rest apenas o conteúdo da propriedade root, com as customizações necessárias, conforme o exemplo abaixo onde temos o resultado de uma customização:

Trabalhando com vários formulários (Dynamic Form)

Em algumas situações precisamos utilizar vários componentes Dynamic Form em uma tela, quando precisamos agrupar campos seja utilizando um po-tabs ou po-accordion, por exemplo.
Nesse caso, há uma questão com relação a validação de formulários. Quando um campo dispara uma validação que altera características de um campo que está em outro formulário, essa validação não é realizada, sendo necessário realizar um tratamento diferente no front-end para o correto funcionamento.

A técnica consiste em atribuir uma função typescript ao p-validate do formulário, nessa função realizar a requisição ao back-end para o endpoint de validação e com o resultado dessa validação atualizar as variáveis de modelo utilizadas em todos os formulários.
Para facilitar esse tratamento foi criada a classe ValidateService no pacote de utilitários Dts-Backoffice-Utils. Você pode utilizar esse pacote para facilitar o desenvolvimento, ou caso prefira, pode copiar o tratamento realizado para o seu projeto.

Segue abaixo os links do projeto:

• NPM: https://www.npmjs.com/package/dts-backoffice-util

• Documentação da Classe: https://github.com/ModernizaDatasul/dts-backoffice-util/blob/master/projects/dts-backoffice-util/README.md#validateservice

• Código da Classe: https://github.com/ModernizaDatasul/dts-backoffice-util/blob/master/projects/dts-backoffice-util/src/lib/services/validate.service.ts  

08. FACILITADORES PROGRESS

Criamos facilitadores para auxiliar no desenvolvimento das API's, ficam localizados na classe Progress "com.totvs.framework.api.JsonAPIUtils":

09. TÉCNICA PARA TRADUÇÃO

A técnica para tradução de label, possui como base as recomendações de i18n do PO UI (https://po-ui.io/documentation/po-i18n) com algumas características adicionais. A seguir serão apresentadas alguns trechos de código que representam a utilização desta técnica de tradução em conjunto com formulários dinâmicos.

Para diferenciar a label que devem ser traduzida, deve-se inserir a key de tradução entre os caracteres chaves. Exemplo: { key }

Conforme a arquitetura de customização apresentada anteriormente, deve-se aguardar o resultado da requisição ao serviço metadata e posteriormente, efetuar os seus devidos tratamentos de tradução. 

Para que o ponto de tradução seja único e compatível com as técnicas recomendadas pelo PO UI, deve-se efetuar o tratamento no front-end. Recomenda-se que seja realizado na função que retorna a lista de fields pois neste momento, são carregados todos os campos correspondentes à tela. 

A arquitetura de tradução do PO UI cita: "... Existe também a possibilidade de utilizar ambos, onde será feito a busca das literais nas constantes e depois efetua a busca no serviço ...". Portanto pode-se configurar os arquivos de tradução com um serviço (URL) que retorna as literais adicionais desenvolvidas no "back-end", sendo assim, um complemento ao arquivo.

Observação: O exemplo da URL abaixo não segue as recomendações do PO UI (api/translations/idiomas). Foi desenvolvido em uma estrutura diferente para facilitar os códigos a conceito de POC.  

Para o endpoint de tradução, pode ser utilizado uma chamada UPC conforme trecho de código a seguir:

A Procedure correspondente ao serviço (URL) citado anteriormente, deve retornar um objeto no formato JSON de acordo com o idioma enviado por parâmetro.

10. COMO DOCUMENTAR A TELA QUE PERMITE CUSTOMIZAÇÃO

11. DICAS PARA DESENVOLVER UMA CUSTOMIZAÇÃO

As informações do que pode ser customizado na tela, qual API REST deve ser cadastrada a UPC, quais os pontos e eventos de UPC, entre outras informações, podem ser localizadas no documento de customização da tela. 
Esse documento geralmente é disponibilizado juntamente com o documento de referência da tela.
Porém, em alguns casos pode ainda não ter haver essa documentação para algumas telas que permitem a customização, então abaixo seguem algumas dicas onde podem ser obtidas algumas informações.

12. LINKS ÚTEIS

Documentação API Datasul:

Desenvolvimento de APIs para o produto Datasul

PO-UI:

• Migração THF PO-UI (https://po-ui.io/guides/migration-thf-to-po-ui)

• Dynamic-Form (https://po-ui.io/documentation/po-dynamic-form);

• Dynamic-View (https://po-ui.io/documentation/po-dynamic-view);

• Page-Dynamic-Detail (https://po-ui.io/documentation/po-page-dynamic-detail);

• Page-Dymic-Edit (https://po-ui.io/documentation/po-page-dynamic-edit);

• Page-Dynamic-Search (https://po-ui.io/documentation/po-page-dynamic-search);

• Page-Dynamic-Table (https://po-ui.io/documentation/po-page-dynamic-table);

• I18N (https://po-ui.io/documentation/po-i18n)

13. CONCLUSÃO

A ideia era apresentar uma técnica para que possibilita-se as áreas de negócio, de forma segura e simples, disponibilizarem pontos de customização em suas API’s REST.

Acreditamos que a técnica apresentada permite que o back-end Progress acompanhe a evolução dos componentes PO-UI.

Com a parte de validação do formulário é possível tratar e validar os campos de acordo com a lógica de negócio que ocorre no back-end, onde sempre será recebido na API REST o campo que está sendo alterado e todos os valores dos demais campos da tela.

Na parte de validação por campo, é recebido na API REST somente o nome do campo e o seu valor atual. Acho importante informar que não é enviado o ID do registro, onde teremos que tomar cuidado para não perder o contexto do registro que estamos validando.

Contamos com seu feedback e sugestões para manter a melhoria continua nas documentações.