Histórico da Página
| Informações | ||
|---|---|---|
| ||
|
| 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, o qual será utilizado como fonte de dados para os campos personalizados.
03. PRÉ-REQUISITOS
Para utilização desta técnica será necessário
...
possuir 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":
...
...
...
...
...
...
...
...
...
...
...
2) Endpoint progress da área de negócio - Serve para obter os dados que serão apresentados nos campos personalizados;
...
Endpoint Progress que devem ser implementados na "área de negócio"
Deve retornar os dados que serão apresentados nos campos personalizados;
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Utilitário facilitador no Progress
Foi
...
implementado no
...
Progress o
...
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.
...
...
...
...
...
...
...
...
...
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 |
...
, |
...
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:
2) Para buscar os valores dos dados a serem apresentados, será enviado o código do programa personalizado e também um id do "registro corrente" para obtenção dos valores;
...
- Para buscar a lista de campos personalizados utilizando o endpoint
...
Progress fornecido pelo framework, que é o /api/btb/v1/personalizationView/metadata/ + codigo_do_programa
...
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.
...
Código do programa "base" que podem ser aplicadas as técnicas de personalização
| Nota | ||
|---|---|---|
| ||
É possível cadastrar os campos somente em programas que permitem a personalização |
...
Identificador Campo
...
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.
...
Tipo do campo cadastrado
Caso o campo não seja informado, será considerado que o campo é do tipo string.
Tipos de campos permitidos:
| Tipo JavaScript | Tipo Progress | Descrição |
|---|---|---|
| boolean | logical | Valores lógicos |
| currency | decimal | Valores monetários |
| date | date | Valores de datas. Aceita os tipos string e Date padrão do Javascript, por exemplo: '2017-11-28' ou new Date(2017, 10, 28). |
| datetime | datetime | Valor de data com horário. Aceita o tipo string no formato ISO-8601 estendido 'yyyy-mm-ddThh:mm:ss+|-hh:mm' e o tipo Date padrão |
| number | integer | Valores numéricos |
| string | character | Textos |
| Informações | ||
|---|---|---|
| ||
Sugerimos a utilização do facilitador progress "com.totvs.framework.api.JsonAPIUtils", que faz a conversão dos tipos da dados do progress para tipo de dados JavaScript e contêm o método abaixo : Assinatura: convertAblTypeToHtmlType (INPUT cType AS CHARACTER) Exemplo: ASSIGN cType = JsonAPIUtils:convertAblTypeToHtmlType ("integer"). O retorno no cType será "number", que é um formato reconhecido pelo PO-UI. |
...
Caso o campo possuir alguma validação de máscaras, restrição de valores, é necessário informar neste campo (máscara de formatação do campo)
Exemplos:
Em um campo personalizado CNPJ, utilizamos o formato de exibição '99.999.999/9999-99'.
...
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 ou exclusão.
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.
Componentes PO-UI
Abaixo temos os códigos da parte HTML e TypeScript, que são:
1) Componente HTML (personalization-detail.component.html)
...
| language | xml |
|---|---|
| firstline | 1 |
| title | Componente PO-UI |
| linenumbers | true |
| collapse | true |
...
;
- 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.
Atributos de campos personalizados
Com a configuração de atributos dos campos personalizados, é 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 | ||
|---|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
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.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
| Aviso | ||
|---|---|---|
| ||
Caso seja enviado valores da área de negócio que não estejam cadastrados como campos personalizados, o PO-UI por padrão adicionará essa informação extra na tela, onde será apresentado como String sem um label válido. |
Tela do componente HTML com o resultado da personalização
Listagem:
06. LINKS ÚTEIS
Documentação API 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)
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).
...
Tela do componente HTML com o resultado da personalização
Tela de Listagem
Tela de Criação/Edição
Tela de Detalhe/Visualização
05. LINKS ÚTEIS
Documentação API Datasul:
Desenvolvimento de APIs para o produto DatasulPO-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);
06. CONCLUSÃO
A ideia era apresentar uma técnica de construção para a personalização de um programa TOTVS da Linha Datasul, de forma segura e simples.
Contamos com seu feedback e sugestões para manter a melhoria continua da documentação.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas