Objetivo

Este documento tem o objetivo de apresentar o padrão que deverá ser utilizado para customização de campos em telas po-ui.

Esse padrão contempla cadastros (CRUDS), conforme lista publicada, nas seguintes situações:

Adição/edição de registros;
Detalhe de registros.

Local dos fontes específicos e padrão de nomenclatura

Para tratar os campos customizáveis, os fontes específicos do cliente deverão ser armazenados no caminho 'hgp/custom/<nome_da_tela>'. Como exemplo para este documento, vamos utilizar a tela Beneficiário X Fator Multiplicador (hfp.benefMultiplierFactor):

Linha Datasul > Novo conceito de customização em telas PO-UI > image2022-7-11_13-29-30.png

Padrão de nomenclatura para o diretório específico e nome dos programas:

O diretório onde são armazenados os fontes específicos deverá seguir o padrão '<módulo>.<nome técnico cadastrado no menu>'. Exemplo: hfp.benefMultiplierFactor, hvp.beneficiary, etc...;
O nome dos programas específicos deverá ser precedido pelo nome da aplicação separado por hífen + o sufixo referente a função do programa. O sufixos possíveis são:
- detail: programa chamado ao acessar a tela de detalhes do CRUD. Ele retornará os campos customizáveis com seus possíveis valores. Exemplo: benef-multiplier-factor-detail.p;
- edit: programa chamado ao acessar a tela de adição ou edição do CRUD. Exemplo: benef-multiplier-factor-edit.p;
- edit-validate: programa chamado para realizar a validação dos campos específicos do cliente. Exemplo: benef-multiplier-edit-validate.p;
- edit-save: programa chamado para realizar a gravação na base de dados dos campos específicos do cliente. Exemplo: benef-multiplier-edit-save.p.

Fluxo para busca e gravação dos campos customizáveis

No padrão denominado Custom Fields, o processo funciona da seguinte maneira:

Ao abrir a tela de adição de registros, o sistema realiza uma chamada ao endpoint hgp/v1/customFields/<nome_da_tela>/<nome_programa_específico>/new/. Este endpoint será responsável por retornar os campos específicos do cliente. No exemplo utilizado neste documento, a chamada seria equivalente a hgp/v1/customFields/hfp.benefMultiplierFactor/benef-multiplier-factor-edit/new/;
Ao acessar a tela de edição de registros, o sistema realiza uma chamada ao endpoint hgp/v1/customFields/<nome_da_tela>/<nome_programa_específico>/edit. Este endpoint será responsável por retornar os campos específicos do cliente. Exemplo: hgp/v1/customFields/hfp.benefMultiplierFactor/benef-multiplier-factor-edit/edit/;
Ao acessar a tela de detalhes, o endpoint acessado será hgp/v1/customFields/<nome_da_tela>/<nome_programa_específico_detalhes>/. Este retornará os campos específicos bem como seus valores. Exemplo: hgp/v1/customFields/hfp.benefMultiplierFactor/benef-multiplier-factor-detail/
Ao salvar um registro, o sistema realiza os seguintes passos:
- Realiza a chamada ao endpoint para validação dos campos customizáveis: hgp/v1/customFields/hfp.benefMultiplierFactor/benef-multiplier-factor-edit-validate/edit;
- Caso a validação dos campos específicos ocorra com sucesso, então o CRUD irá disparar o método insert ou update do produto padrão para salvar o registro em questão;
- Caso a gravação do registro padrão de produto ocorra com sucesso, então será disparado endpoint para gravação dos campos específicos: hgp/v1/customFields/hfp.benefMultiplierFactor/benef-multiplier-factor-edit-save/edit.

Customização com eventos no back-end utilizando componentes e templates dinâmicos

O uso dos componentes e templates dinâmicos permite a customização das páginas sem interferência no código-fonte do front-end, com eventos gerenciado pelo backend nas APIs utilizadas pela aplicação.

Pré-requisitos do back-end

API

Além da API para retorno e tratamento dos dados (como inclusão, alteração, exclusão) será necessário endpoints que possibilitem:

Retorno das informações da página, conhecido como metadado, contendo campos e ações
Validar os dados informados pelo usuário
Opcionalmente retornar separado as informações customizadas

Os endpoints descritos acima devem ser do tipo POST para receberem as informações da interface (por exemplo PoDynamicFormLoad, PoDynamicFormField). As propriedades enviadas no formato JSON estão descritas na documentação das interfaces de cada componente ou template.

Estes endpoints podem ser implementados de diversas formas, como abaixo (sendo o endpoint de dados http://localhost:8080/api/v1/people):

Extensão do endpoint de dados:
- endpoint de metadado:
  http://localhost:8080/api/v1/people/metadata
- endpoint de validação:
  
  http://localhost:8080/api/v1/people/validate
Endpoint agrupador específico:
- endpoint de metadado:
  http://localhost:8080/api/v1/metadata/people ou http://localhost:8080/api/v1/metadata?resource=people
- endpoint de validação:
  
  http://localhost:8080/api/v1/validate/people
  ou
  http://localhost:8080/api/v1/validate?resource=people

Formato JSON

O endpoint de retorno e tratamento de dados deve seguir o padrão definido no Guia de Construção de API da TOTVS:

Para os endpoints de metadado e validação verifique a documentação de cada componente ou template do PO UI, como por exemplo para carga do metadado veja a documentação da interface descrita na propriedade p-load, que deve ser retornada como JSON (o mesmo vale para outras interfaces descritas na documentação):

{
    "fields":
        [
            {"property": "name", "label": "Nome"}
        ],
    "value": {"name": "Seu nome"}
}

Forma de utilização:

Deverá ser criado um programa progress no seguinte diretório, conforme explicado anteriormente:

hgp\custom\"nomedomenu"\"nomedoprogramahtml".p(.r)

Exemplo:

hgp\custom\portalempresa\edit-beneficiary.p

Este programa deverá ter os métodos e parâmetros:

getCustomFields

Utilizado para buscar os campos que serão acrescentados no formulário e seus respectivos valores.

Parâmetros:

define input        parameter pathParams as JsonArray no-undo. /* Array contendo parâmetros de entrada */
define output       parameter table for ttCustomField. /*Definido no item Tabelas Temporárias Utilizadas (hgp\bosau\bosau-custom.i)*/
define output       parameter table for ttCustomValue. /*Definido no item Tabelas Temporárias Utilizadas (hgp\bosau\bosau-custom.i)*/
define input-output parameter table for rowErrors. /*Definida através da include (rtp\rtrowerror.i)*/

Exemplo:

procedure getCustomFields:

    define input        parameter pathParams as JsonArray no-undo.
    define output       parameter table for ttCustomField.
    define output       parameter table for ttCustomValue.
    define input-output parameter table for rowErrors.


   define variable cd-modalidade-aux        as int          no-undo.
   define variable nr-proposta-aux          as int          no-undo.
   define variable cd-usuario-aux           as int          no-undo.

   assign
        cd-modalidade-aux = int(pathParams:getCharacter(3))
        nr-proposta-aux   = int(pathParams:getCharacter(4))
        cd-usuario-aux    = int(pathParams:getCharacter(5))
        no-error.

    find first usuario where usuario.cd-modalidade = cd-modalidade-aux and
        usuario.nr-proposta = nr-proposta-aux and
        usuario.cd-usuario-aux = cd-usuario-aux no-lock no-error.


    create ttCustomField.
    assign
        ttCustomField.ds-type = "boolean"
        ttCustomField.ds-boolean-false = "Campo específico"
        ttCustomField.ds-boolean-true = "Campo específico"
        ttCustomField.lg-disabled = true
        ttCustomField.ds-property = "u_log_1".

    create ttCustomValue.
    assign ttCustomValue.ds-property = "u_log_1"
        ttCustomValue.lg-value = usuario.u-log-1.
end.

Tabelas Temporárias Utilizadas:

define temp-table ttCustomField
    field ds-boolean-false as char serialize-name "booleanFalse" init ?     /*Texto exibido quando o valor do componente for false.*/
    field ds-boolean-true as char serialize-name "booleanTrue" init ?       /*Texto exibido quando o valor do componente for true.*/
    field ds-columns as char serialize-name "columns"  init ?               /*Não disponível*/
    field lg-disabled as logical serialize-name "disabled" init ?           /*Desabilita o campo caso informar o valor true.*/
    field ds-divider as char serialize-name "divider" init ?                /*Exibirá um divisor acima, utilizando o seu conteudo como título.*/
    field nr-grid as int serialize-name "gridColumns" init ?                /*Tamanho de exibição do campo em telas. Deve ser usado o sistema de grid do THF (1 ... 12 c
    field nr-grid-lg-columns as int serialize-name "gridLgColumns" init ?   /*Tamanho de exibição do campo em telas grandes (lg).*/
    field nr-grid-md-columns as int serialize-name "gridMdColumns" init ?   /*Tamanho de exibição do campo em telas médias (md)*/
    field nr-grid-sm-columns as int serialize-name "gridSmColumns" init ?   /*Tamanho de exibição do campo em telas menores (sm)*/
    field nr-grid-xl-columns as int serialize-name "gridXlColumns" init ?   /*Tamanho de exibição do campo em telas extra grandes (xl)*/
    field ds-help as char serialize-name "help" init ?                      /*Texto de ajuda*/
    field lg-key as logical serialize-name "key" init ?                     /*Identificador*/
    field ds-label as char serialize-name "label" init ?                    /*Rótulo*/
    field ds-mask as char serialize-name "mask" init ?                      /*Máscara*/
    field nr-max-length as int serialize-name "maxLength" init ?            /*Tamanho máximo de caracteres.*/
    field ds-max-value as char serialize-name "maxValue" init ?             /*Valor máximo*/
    field nr-min-length as int serialize-name "minLength" init ?            /*Tamanho mínimo*/
    field ds-min-value as char serialize-name "minValue" init ?             /*Valor mínimo*/
    field ds-options as char serialize-name "options" init ?                /*Não disponível*/
    field lg-options-multi as logical serialize-name "optionsMulti" init ? /* Permite que o usuário faça múltipla seleção */
    field ds-options-service as char serialize-name "optionsService" init ? /* Serviço utilizado para buscar itens */
    field ds-pattern as char serialize-name "pattern" init ?                /*Regex para validação */
    field ds-property as char serialize-name "property" init ?              /*Nome de referência do campo */
    field lg-required as logical serialize-name "required" init ?           /*Indicador de obrigatoriedade*/
    field nr-rows as int serialize-name "rows" init ?                       /*Quantidade de linhas exibidas*/
    field ds-search-service as char serialize-name "searchService" init ?   /*Não disponível*/
    field lg-secret as logical serialize-name "secret" init ?               /*Esconde a informação estilo password, pode ser utilizado quando o tipo de dado for string*/
    field ds-type as char serialize-name "type" init ?.                     /*Tipo do valor do campo. Tipos Válidos: boolean, currency, date, dateTime, number, string e time.*/

define temp-table ttCustomValue
    field ds-property as char serialize-hidden /*Referente ao ds-property utilizado anteriormente para criar os campos em tela através da temp-table ttCustomFields*/
    field in-value as int serialize-hidden init ? /*Valor do campo caso seja inteiro*/
    field ds-value as char serialize-hidden init ? /*Valor do campo caso seja string*/
    field lg-value as log serialize-hidden init ? /* Valor do campo caso seja lógico*/
    field dc-value as dec serialize-hidden init ? /* Valor do campo caso seja decimal*/
    field dt-value as date serialize-hidden init ?. /*Valor do campo caso seja data*/