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.
...
- 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:
...
...
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:
...
- 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.
define output parameter table for ttCustomField.
define output parameter table for ttCustomValue.
define input-output parameter table for rowErrors.
|
- 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*/
|
