Histórico da Página
Painel | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
...
icon | false |
---|
...
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
...
03. PRÉ-REQUISITOS
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;
3) Criação de um componente com PO-UI, pela área de negócio, que utilize o componente PO-DYNAMIC-VIEW. Nele será utilizado a lista de campos personalizados e os dados a serem apresentados..
Explicando o funcionamento da técnica:
O componente criado pela área de negócio com o PO-DYNAMIC-VIEW deverá fazer duas requisições ao servidor REST, que são:
1) Para buscar os valores dos dados a serem apresentados, onde poderá ser passados o código do programa personalizado e também um id do "registro corrente" para obtenção dos valores.
2) 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.
Componente HTML com PO-DYNAMIC-VIEW
Abaixo temos os códigos da parte HTML, que são:
1) Componente HTML (personalization.component.html)
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
<po-loading-overlay
[hidden]="!showLoading">
</po-loading-overlay>
<po-page-detail
p-title="Personalização"
[p-breadcrumb]="breadcrumb"
(p-edit)="editClick()"
(p-back)="goBackClick()">
<po-dynamic-view
[p-fields]="fields"
[p-value]="record">
</po-dynamic-view>
</po-page-detail> |
2) Componente TypeScript (personalization.component.ts)
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
import { Component, OnInit } from '@angular/core';
import { PoBreadcrumb, PoBreadcrumbItem, PoNotificationService } from '@po-ui/ng-components';
import { PersonalizationService } from './personalization.service';
@Component({
selector: 'app-personalization',
templateUrl: './personalization.component.html',
styleUrls: ['./personalization.component.css']
})
export class PersonalizationComponent implements OnInit {
// definicao das variaveis utilizadas
public currentId: string;
public fields: Array<any> = [];
public record = {};
public showLoading = false;
public cProg = 'pedido-execucao-monitor';
public breadcrumb: PoBreadcrumb = { items: [] };
public breadcrumbItem: PoBreadcrumbItem;
// construtor com os servicos necessarios
constructor(
private service: PersonalizationService,
private poNotification: PoNotificationService
) { }
// load do componente
public ngOnInit(): void {
this.showLoading = true;
this.record = {};
// busca os valores dos dados a serem apresentados
this.service.loadValues(this.cProg, 'esp').subscribe(resp => {
console.log(resp);
Object.keys(resp).forEach((key) => this.record[key] = resp[key]);
// carrega a lista de campos somente apos receber o registro a ser apresentado
if (this.fields === null || this.fields.length === 0) {
this.service.loadMetadata(this.cProg).subscribe(metadata => {
// tslint:disable-next-line:no-string-literal
this.fields = metadata['fields'];
this.showLoading = false;
});
}
});
this.setBreadcrumb();
}
private setBreadcrumb(): void {
this.breadcrumbItem = { label: 'Home', link: '/' };
this.breadcrumb.items = this.breadcrumb.items.concat(this.breadcrumbItem);
this.breadcrumbItem = { label: 'Personalização' };
this.breadcrumb.items = this.breadcrumb.items.concat(this.breadcrumbItem);
}
// Redireciona quando clicar no botao Edit
public editClick(): void {
this.poNotification.information('Voce clicou na edição dos dados');
}
// Redireciona quando clicar no botao Voltar
public goBackClick(): void {
this.poNotification.information('Voce clicou para retornar para a tela anterior');
}
} |
3) Componente de serviço (personalization.service.ts)
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
import { HttpClient, HttpHeaders } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { PoNotificationService } from '@po-ui/ng-components';
const httpOptions: object = {
headers: new HttpHeaders({
'Content-Type': 'application/json',
})
};
@Injectable({
providedIn: 'root'
})
export class PersonalizationService {
// Endpoint progress do framework para obtencao da lista de campos personalizados
private urlMetadata = '/api/btb/v1/personalizationView/metadata/';
// Endpoint progress da area de negocio para obtencao dos valores dos campos personalizados
private urlArea = '/api/trn/v1/idiomaValues/';
private fieldList: Array<any> = [];
constructor(
private http: HttpClient,
private poNotification: PoNotificationService,
) { }
public loadMetadata(cProg) {
return this.http.post<any[]>(this.urlMetadata + cProg, httpOptions).pipe();
}
public loadValues(cProg, cId) {
return this.http.get<any[]>(this.urlArea + cProg + '/' + cId, httpOptions).pipe();
}
public getUrlArea(): string {
return this.urlArea;
}
} |
Endpoint em Progress da área de negócio
Abaixo temos o endpoint progress que deverá ser criado pela área de negócio para obtenção dos valores a serem apresentados nos campos personalizados.
Endpoint progress da área de negócio para obtenção dos valores dos campos personalizados (idiomaValues.p)
...
language | java |
---|---|
firstline | 1 |
title | Endpoint Progress |
linenumbers | true |
collapse | true |
...
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 |
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.
Atributos de campos personalizados
Com a configuração de atributos dos campos personalizados, é possível adicionar outras características tais como:
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.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Retorno do endpoint da área de negócio com os valores dos campos personalizados:
...
language | xml |
---|---|
firstline | 1 |
title | Retorno do Endpoint da área de negócio |
linenumbers | true |
collapse | true |
...
...
...
...
...
...
...
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
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/customization-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.
...