Versões comparadas
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
Painel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
01. INTRODUÇÃO/OBJETIVO
Temos como objetivo, implementar técnicas para facilitar a personalização de telas TOTVS - Linha Datasul de forma lowcode, apenas com cadastro de campos por parte do cliente.
02. VISÃO GERAL
A partir da release 12.1.31, são disponibilizados as técnicas e cadastros para implementar a personalização em telas HTML da linha Datasul.
Nesta técnica de personalização, o desenvolvedor deverá realizar o cadastro dos campos a serem personalizados e criar alguns componentes em PO-UI que utilizem os componentes: PO-DYNAMIC-FORM, PO-DYNAMIC-VIEW e PO-PAGE-DYNAMIC-TABLE (este último somente se for necessário). Deve-se também implementar endpoint em Progress no qual será utilizado como fonte de dados para os campos personalizados.
03. PRÉ-REQUISITOS
Para utilização desta técnica será necessário ter um conhecimento de desenvolvimento com: APIs REST em Progress, Angular, TypeScript e PO-UI.
04. TÉCNICAS
A Técnica de personalização de telas HTML com PO-UI contempla os seguintes objetos:
Endpoint Progress do Framework
Retorna a lista de campos personalizados, que devem ser previamente cadastrados na tela de Personalização em HTML.
Neste item, deverá ser utilizado o endpoint Progress /api/btb/v1/personalizationView/metadata/ + código_do_programa ,onde deve ser passado o Código do Programa Datasul que conterá a lista de campos personalizados.
Exemplo: Implementação de personalização para o programa pedido-execucao-monitor, deve-se utilizar o endpoint "/api/btb/v1/personalizationView/metadata/pedido-execucao-monitor":
Bloco de código | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
{ "fields": [ { "visible": true, "gridColumns": 6, "disable": false, "property": "cod_idioma", "label": "Idioma", "type": "string" }, { "visible": true, "gridColumns": 6, "disable": false, "property": "cod_idiom_padr", "label": "Idioma Padrão", "type": "string" }, { "visible": true, "gridColumns": 6, "disable": false, "property": "des_idioma", "label": "Descrição", "type": "string" }, { "visible": false, "property": "id", "type": "number", "key": true } ] } |
Endpoint Progress que devem ser implementados na "área de negócio"
Deve retornar os dados que serão apresentados nos campos personalizados;
A tabela a ao lado demonstra os componentes dinâmicos do PO-UI com suas respectivas requisições à API REST.
Componente PO-UI | Endpoint | Tipo Requisição | Descrição |
---|---|---|---|
po-dynamic-view po-dynamic-form | /byid/nome_do_programa/id | GET | Retorna um registro único. Recebe no PathParms o "nome do programa" e o "id". |
po-page-dynamic-table | /nome_do_programa | GET | Retorna uma lista de registros. Recebe no PathParams o "nome do programa". |
po-dynamic-form | /validateForm/nome_do_programa | POST | Valida o formulário. Recebe no PathParams o "nome do programa". |
po-dynamic-form | /nome_do_programa | POST | Efetua a criação de um novo registro. Recebe no PathParams o "nome do programa". |
po-dynamic-form | /nome_do_programa/id | PUT | Efetua a alteração do registro, Recebe no PathParams o "nome do programa" e o "id". |
po-dynamic-form | /nome_do_programa/id | DELETE | Efetua a eliminação do registro. Recebe no PathParams o "nome do programa" e o "id". |
Aviso | ||
---|---|---|
| ||
Em todas os componentes dinâmicos da tabela apresentada, efetuará uma requisição para obter a lista de campos personalizados na API REST do Framework, com a utilização da requisição: "/api/btb/v1/personalizationView/metadata/" + código_do_programa |
Utilitário facilitador no Progress
Foi implementado no Progress um utilitário btb/personalizationUtil.p, com seu include btb/personalizationUtil.i, que deve ser utilizado para retornar à área de negócio a lista de campos personalizáveis de um determinado programa cujo o intuito é facilitar a implementação para que seja enviado somente os valores dos campos personalizáveis.
Devido a característica do PO-UI dinâmico, caso seja enviado os dados de campos que não estão na lista de campos, o PO-UI irá apresentar o valor do campo com uma label com o mesmo nome do campo. Com a obtenção da lista de campos, pode-se evitar o envio de informações que estão fora da lista de campos personalizados.
- Include btb/personalizationUtil.i
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
DEFINE TEMP-TABLE ttPersonalization NO-UNDO FIELD codProgDtsul AS CHARACTER FIELD codField AS CHARACTER FIELD codType AS CHARACTER FIELD codLabel AS CHARACTER FIELD codValid AS CHARACTER FIELD logReadOnly AS LOGICAL INITIAL FALSE FIELD logEnable AS LOGICAL INITIAL TRUE INDEX codigo IS PRIMARY codProgDtsul codField. |
- Procedures disponíveis no programa btb/personalizationUtil.p
Procedure | Parâmetros | Descrição/Exemplo | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
piGetTTPersonalization | INPUT cProg AS CHARACTER OUTPUT TABLE ttPersonalization | Retorna a temp-table ttPersonalization com a lista de campos personalizáveis de um determinado programa. Exemplo:
| |||||||||||||
piGetFieldList | INPUT cProg AS CHARACTER OUTPUT cList AS CHARACTER OUTPUT cTypeList AS CHARACTER | Retorna duas listas CHARACTER , sendo uma contendo com a lista de campos e uma lista dos a outra com os seus respectivos tipos, de um determinado programa. Observação: As listas usam como separador a vírgula ",". Exemplo:
|
Implementação pela área de negócio a interface em PO-DYNAMIC-FORM e PO-DYNAMIC-VIEW.
Todos os componentes dinâmicos do PO-UI realizam, no mínimo, duas requisições REST, uma para obter a lista de campos personalizáveis e outra para obter os dados a serem apresentados nesses campos.
Abaixo temos o papel de cada componente dinâmico que podemos utilizar:
PO-DYNAMIC-FORM: Para a edição e criação de um novo registro personalizado;
PO-DYNAMIC-VIEW Para a visualização do registro personalizado.
Dica | ||
---|---|---|
| ||
Pode-se implementar também um componente PO-PAGE-DYNAMIC-TABLE, para a navegação dos registros e permitir a visualização e edição dos mesmos. |
Em nossa técnica, em todas as requisições REST, será enviado:
- Para buscar a lista de campos personalizados utilizando o endpoint Progress fornecido pelo framework, que é o /api/btb/v1/personalizationView/metadata/ + codigo_do_programa;
- O código do programa personalizado e também um id do "registro corrente" para obtenção dos valores, necessários para buscar os valores dos dados a serem apresentados.
05. EXEMPLO DE UTILIZAÇÃO
Cadastro de campos personalizados
A seguir são apresentados as telas necessárias para a realização do cadastro dos campos personalizados.
Ao localizar no menu o programa "Campos personalizados (html.personalization-metadata)", é apresentada uma tela em formato de 'lista' que conterá todos os campos (metadados) cadastrados no produto Datasul. Para cadastrar um campo que será utilizado na personalização, basta clicar no botão +Adicionar.
A tela a seguir apresenta o cadastro do 'metadado' relacionado a um campo que pode ser apresentado no programa como personalizado.
Para alguns tipos de campo, é possível informar uma lista de opções apresentadas em tela, para isso basta informar os dados (chave, valor).
Campo | Descrição | Obrigatório | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Código Programa Datasul | Código do programa "base" que podem ser aplicadas as técnicas de personalização
| Sim | ||||||||||||||||||||||||||||
Identificador Campo | Identificador único do campo (por programa), necessário para a geração da tela personalizada (código do campo) | Sim | ||||||||||||||||||||||||||||
Nome Campo | Nome do campo que será apresentado na tela (label do campo) Caso o campo não seja informado, o nome do campo apresentado será o informado no identificador. | Não | ||||||||||||||||||||||||||||
Tipo Campo | Tipo do campo cadastrado Caso o campo não seja informado, será considerado que o campo é do tipo Character. Tipos de campos permitidos:
| Não | ||||||||||||||||||||||||||||
Lista Opções | Informa a lista de opções a serem apresentadas em conjunto com o tipo do componente especificado.
| |||||||||||||||||||||||||||||
Somente Leitura | Opção para que o campo seja apresentado como 'somente leitura' (torna o campo readOnly) | Sim | ||||||||||||||||||||||||||||
Habilita personalização | Opção para habilitar ou desabilitar a apresentação da personalização por campo (torna o campo visível) | Sim |
Após cadastrar o campo, o mesmo é apresentado na tela inicial onde pode ser realizado filtros sobre seus resultados, bem como efetuar ações de edição de campos, inclusão de atributos e exclusão de campos.
Ao clicar na opção de editar, não será possível modificar o código do programa Datasul vinculado e também seu identificador. Os demais campos estão habilitados para edição.
Atributos de campos personalizados
Com a configuração de atributos dos campo personalizado, é possível adicionar outras características tais como:
- Alteração de cor;
- Apresentação da ordem do campo no qual será visualizado em tela;
- Validações de interface;
- Máscara de apresentação do campo, entre muitos outros.
Ao clicar no botão "Atributos" apresentado na grid principal (Opções), uma tela de parametrizações é apresentada para que seja possível adicionar as novas características.
Ao renderizar os campos personalizados em tela, esses atributos serão inclusos no campo personalizado e enviados para tela.
Aviso | ||
---|---|---|
| ||
Os nomes dos atributos devem ser os mesmos que estão documentados nas propriedades do componente no PO-UI. Exemplo: Para personalizar um campo no formato CPF, criamos o campo COD_CPF e adicionamos um atributo do tipo "mask" que conterá o formato "999.999.999-99". O atributo "mask" corresponde a uma propriedade do componente PO-INPUT. |
Componentes em PO-UI
A seguir, são apresentados exemplos de códigos para a implementação com HTML e TypeScript:
Componente HTML (personalization-detail.component.html)
Expandir | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||
|
Componente TypeScript (personalization-detail.component.ts)
Expandir | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Componente HTML (personalization-edit.component.html)
Expandir | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||
|
Componente TypeScript (personalization-edit.component.ts)
Expandir | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Componente HTML (personalization-list.component.html)
Expandir | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
|
Componente TypeScript (personalization-list.component.ts)
Expandir | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||
|
Componente de serviço (personalization.service.ts)
Expandir | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Endpoint em Progress para a área de negócio
A seguir, são apresentados exemplos de endpoint em Progress, que deverão ser implementados pela área de negócio para obtenção dos valores a serem apresentados nos campos personalizados.
Obtenção dos valores dos campos personalizados (idiomaValues.p)
Expandir | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Aviso | ||
---|---|---|
| ||
Caso seja enviado valores da área de negócio que não estejam cadastrados como campos personalizados, o PO-UI, o padrão adicionará essa informação extra na tela, onde será apresentado em formato String sem uma label válida. |
Tela do componente HTML com o resultado da personalização
Tela de Listagem
Tela de Criação/Edição
Tela de Detalhe/Visualização
Dica | ||
---|---|---|
| ||
Os fontes de exemplo para a personalização também estão disponíveis em nosso GIT (fwk-totvs-jille) em "LINKS ÚTEIS". |
06. LINKS ÚTEIS
Documentação API Datasul:
https://tdninterno.totvs.com/display/public/FRAMJOI/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-View (https://po-ui.io/documentation/po-dynamic-view);
I18N (https://po-ui.io/documentation/po-i18n)
PO-UI (https://po-ui.io/documentation);
GIT Projeto:
fwk-tools-jille/DATASUL/personalization-poui/ ( https://github.com/totvs/fwk-tools-jille )
07. CONCLUSÃO
A ideia era apresentar uma técnica de construção para a personalização de um programa TOTVS da Liinha Datasul, de forma segura e simples.
Esta documentação trata-se de um MVP, que está sendo continuamente evoluída em nossas Sprints (SQUAD TOOLS).
HTML |
---|
<!-- esconder o menu --> <style> div.theme-default .ia-splitter #main { margin-left: 0px; } .ia-fixed-sidebar, .ia-splitter-left { display: none; } #main { padding-left: 10px; padding-right: 10px; overflow-x: hidden; } .aui-header-primary .aui-nav, .aui-page-panel { margin-left: 0px !important; } .aui-header-primary .aui-nav { margin-left: 0px !important; } </style> |