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, uma será 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. Após retornados os valores dos dados, é necessário buscar a lista de campos personalizados com a utilização do 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.
4) 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.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Tela do componente HTML com o resultado da personalização
Tela de Listagem
Tela de Criação/Edição
Tela de Detalhe/
...
Tela do componente HTML com o resultado da personalização
06. 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).
...
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.
...