Funções personalizadas nos Componentes principais do Forms adaptável

Este artigo descreve como criar funções personalizadas com o componente principal de formulário adaptável mais recente, que tem os recursos mais recentes, como:

Defina a versão mais recente do formulário no ambiente do Componente principal do AEM Forms para usar os recursos mais recentes nas Funções personalizadas.

Introdução

O AEM Forms 6.5 inclui funções do JavaScript que permitem definir regras de negócios complexas usando o editor de regras. Embora o AEM Forms ofereça várias funções personalizadas prontas para uso, muitos casos de uso exigem a definição de suas próprias funções personalizadas para serem usadas em vários formulários. Essas funções personalizadas aprimoram os recursos de formulários permitindo que a manipulação e o processamento dos dados inseridos atendam a requisitos específicos. Além disso, elas permitem a alteração dinâmica do comportamento do formulário com base nos critérios predefinidos.

Usos de funções personalizadas uses-of-custom-function

As vantagens de usar funções personalizadas nos Componentes principais do Forms adaptável são:

As funções personalizadas são essencialmente bibliotecas de clientes adicionadas ao arquivo do JavaScript. Depois de criar uma Função personalizada, ela fica disponível no editor de regras para seleção pelo usuário em um Formulário adaptável. As funções personalizadas são identificadas pelas anotações do JavaScript no editor de regras.

Anotações do JavaScript compatíveis com a função personalizada js-annotations

As anotações do JavaScript fornecem metadados para o código JavaScript. Inclui comentários que começam com símbolos específicos, por exemplo, /** e @. As anotações fornecem informações importantes sobre funções, variáveis e outros elementos no código. O Formulário adaptável é compatível com as seguintes anotações do JavaScript para funções personalizadas:

Nome

O Name é usado para identificar a função personalizada no editor de regras de um formulário adaptável. As seguintes sintaxes são usadas para nomear uma Função Personalizada:

Parâmetro

O Parâmetro é uma lista de argumentos usados por funções personalizadas. Uma função pode suportar vários parâmetros. As sintaxes a seguir são usadas para definir um parâmetro em uma função personalizada:

O tipo Parameter é não diferencia maiúsculas de minúsculas e espaços não são permitidos no nome do parâmetro.

<Parameter Description> contém detalhes sobre a finalidade do parâmetro. Ele pode ter várias palavras.

Tipo de retorno

O tipo de retorno especifica o tipo de valor que a função personalizada retorna após a execução. As sintaxes a seguir são usadas para definir um tipo de retorno em uma função personalizada:

O tipo de retorno não diferencia maiúsculas de minúsculas.

Privado

A função personalizada, declarada como privada, não aparece na lista de funções personalizadas no editor de regras de um formulário adaptável. Por padrão, as funções personalizadas são públicas. A sintaxe para declarar função personalizada como privada é @private.

Diretrizes ao criar funções personalizadas considerations

Para listar as funções personalizadas no editor de regras, você pode usar qualquer um dos seguintes formatos:

Instrução Function com ou sem comentários jsdoc

Você pode criar uma função personalizada com ou sem comentários jsdoc.

    function functionName(parameters)
        {
            // code to be executed
        }

Se o usuário não adicionar anotações do JavaScript à função personalizada, ela será listada no editor de regras pelo nome da função. No entanto, é recomendável incluir anotações do JavaScript para melhorar a legibilidade das funções personalizadas.

Função de seta com anotações ou comentários obrigatórios do JavaScript

É possível criar uma função personalizada com uma sintaxe de função de seta:

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

Se o usuário não adicionar anotações JavaScript à função personalizada, a função personalizada não será listada no editor de regras de um Formulário adaptável.

Expressão de função com anotações ou comentários obrigatórios do JavaScript

Para listar funções personalizadas no editor de regras de um Formulário adaptável, crie funções personalizadas no seguinte formato:

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

Se o usuário não adicionar anotações JavaScript à função personalizada, a função personalizada não será listada no editor de regras de um Formulário adaptável.

Pré-requisitos para criar uma função personalizada

Antes de começar a adicionar uma função personalizada ao Adaptive Forms, verifique se você tem o seguinte Software instalado em sua máquina:

Criar uma função personalizada create-custom-function

As etapas para criar funções personalizadas são:

Criar uma biblioteca do cliente usando o Arquétipo de projeto AEM create-client-library-archetype

Você pode adicionar funções personalizadas adicionando uma biblioteca do cliente ao projeto criado usando o Arquétipo de Projeto AEM.
Se você tiver um projeto existente , poderá adicionar diretamente funções personalizadas ao seu projeto local.

Depois de criar um Projeto do Arquétipo ou usar um projeto existente, crie uma biblioteca do cliente. Para criar uma biblioteca do cliente, execute as seguintes etapas:

Adicionar uma pasta da biblioteca do cliente

Para adicionar uma nova pasta da biblioteca do cliente ao seu [diretório do projeto AEM], siga estas etapas:

Adicionar arquivos e pastas à pasta da Biblioteca do Cliente

Adicione o seguinte à pasta da biblioteca do cliente adicionada:

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

Incluir a nova pasta no filter.xml:

Criar e implantar funções personalizadas por meio do CRXDE create-add-custom-function

Se você estiver usando o complemento mais recente do AEM Forms e do Forms, poderá criar uma função personalizada por meio do CRXDE para usar as atualizações mais recentes de funções personalizadas. Para fazer isso, execute as seguintes etapas:

Você pode consultar a seguinte pasta função personalizada. Baixe e instale essa pasta na instância do AEM.

Agora, você pode usar a função personalizada no Formulário adaptável adicionando a biblioteca do cliente.

Adicionar biblioteca do cliente em um Formulário adaptável add-client-library

Depois de implantar a biblioteca do cliente no ambiente do AEM Forms, use os recursos dela no Formulário adaptável. Para adicionar a biblioteca do cliente no Formulário adaptável

Agora, é possível criar uma regra para usar funções personalizadas no editor de regras:

Agora, vamos entender como configurar e usar uma função personalizada usando o serviço Chamar do Editor de regras no AEM Forms 6.5

Utilização da função personalizada em um formulário adaptável use-custom-functions

Em um Formulário adaptável, você pode usar Funções personalizadas no editor de regras.
Vamos adicionar o seguinte código ao arquivo JavaScript (arquivo Function.js) para calcular a idade com base na Data de Nascimento (AAAA-MM-DD). Crie uma função personalizada como calculateAge() que use a data de nascimento como entrada e retorne a idade:

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

No exemplo acima, quando o usuário insere a data de nascimento no formato (AAAA-MM-DD), a função personalizada calculateAge é invocada e retorna a idade.

Vamos visualizar o formulário para observar como as funções personalizadas são implementadas por meio do editor de regras:

Suporte para funções assíncronas em funções personalizadas support-of-async-functions

As funções personalizadas assíncronas não aparecem na lista do editor de regras. No entanto, é possível chamar funções assíncronas em funções personalizadas criadas usando expressões de função síncrona.

Examine o código abaixo para ver como podemos chamar funções assíncronas usando funções personalizadas:

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

No exemplo acima, a função asyncFunction é um asynchronous function. Ele executa uma operação assíncrona fazendo uma solicitação GET para https://petstore.swagger.io/v2/store/inventory. Ele aguarda a resposta usando await, analisa o corpo da resposta como JSON usando response.json() e retorna os dados. A função callAsyncFunction é uma função personalizada síncrona que chama a função asyncFunction e exibe os dados de resposta no console. Embora a função callAsyncFunction seja síncrona, ela chama a função asyncFunction assíncrona e manipula seu resultado com instruções then e catch.

Para ver seu funcionamento, vamos adicionar um botão e criar uma regra para o botão que chama a função assíncrona em um clique de botão.

Consulte a ilustração da janela de console abaixo para demonstrar que, quando o usuário clica no botão Fetch, a função personalizada callAsyncFunction é invocada, o que, por sua vez, chama uma função assíncrona asyncFunction. Inspect na janela do console para exibir a resposta ao clicar no botão:

Vamos analisar os recursos de funções personalizadas.

Vários recursos para funções personalizadas

Você pode usar funções personalizadas para adicionar recursos personalizados a formulários. Essas funções oferecem suporte a várias habilidades, como trabalhar com campos específicos, usar campos globais ou armazenar em cache. Essa flexibilidade permite personalizar formulários de acordo com os requisitos de sua organização.

Objetos de escopo de campo e global em funções personalizadas support-field-and-global-objects

Objetos de campo referem-se aos componentes ou elementos individuais em um formulário, como campos de texto e caixas de seleção. O objeto Globals contém variáveis somente leitura, como instância de formulário, instância de campo de destino e métodos para fazer modificações de formulário em funções personalizadas.

Saiba como as funções personalizadas usam campos e objetos globais com a ajuda de um formulário Contact Us usando diferentes casos de uso.

Caso de uso: mostrar um painel usando a regra SetProperty

Adicione o seguinte código na função personalizada, como explicado na seção create-custom-function, para definir o campo de formulário como Required.

    /**
    * enablePanel
    * @name enablePanel
    * @param {object} field1
    * @param {object} field2
    * @param {scope} globals
    */

    function enablePanel(field1,field2, globals)
    {
       if(globals.functions.validate(field1).length === 0)
       {
       globals.functions.setProperty(field2, {visible: true});
       }
    }

Neste exemplo, a validação do painel personaldetails ocorre ao clicar no botão. Se nenhum erro for detectado no painel, outro painel, o painel feedback, ficará visível ao clicar no botão.

Vamos criar uma regra para o botão Next, que valida o painel personaldetails e torna o painel feedback visível quando o usuário clica no botão Next.

Consulte a ilustração abaixo para demonstrar onde o painel personaldetails é validado ao clicar no botão Next. Caso todos os campos em personaldetails sejam validados, o painel feedback ficará visível.

Se houver erros nos campos do painel personaldetails, eles serão exibidos no nível do campo ao clicar no botão Next e o painel feedback permanecerá invisível.

Caso de uso: validar o campo.

Adicione o seguinte código na função personalizada conforme explicado na seção create-custom-function para validar o campo.

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

Neste exemplo, um padrão de validação personalizado é aplicado ao campo contact. Os usuários precisam inserir um número de telefone começando com 10 seguido de 8 dígitos. Se o usuário digitar um número de telefone que não comece com 10 ou contenha mais ou menos de 8 dígitos, uma mensagem de erro de validação será exibida ao clicar no botão:

Agora, a próxima etapa é criar uma regra para o botão Next que valide o campo contact no clique de botão.

Consulte a ilustração abaixo para demonstrar que, se o usuário digitar um número de telefone que não comece com 10, uma mensagem de erro será exibida no nível do campo:

Se o usuário digitar um número de telefone válido e todos os campos no painel personaldetails forem validados, o painel feedback aparecerá na tela:

Caso de uso: redefinir um painel

Adicione o seguinte código na função personalizada, como explicado na seção create-custom-function, para redefinir o painel.

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

Neste exemplo, o painel personaldetails é redefinido ao clicar no botão Clear. A próxima etapa é criar uma regra para o botão Clear que redefina o painel no clique do botão.

Consulte a ilustração abaixo para mostrar que, se o usuário clicar no botão clear, o painel personaldetails será redefinido:

Caso de uso: para exibir uma mensagem personalizada no nível do campo e marcar o campo como inválido

Você pode usar a função markFieldAsInvalid() para definir um campo como inválido e definir uma mensagem de erro personalizada em nível de campo. O valor fieldIdentifier pode ser fieldId, field qualifiedName ou field dataRef. O valor do objeto nomeado option pode ser {useId: true}, {useQualifiedName: true} ou {useDataRef: true}.
As sintaxes usadas para marcar o campo como inválido e definir uma mensagem personalizada são:

Adicione o seguinte código na função personalizada conforme explicado na seção create-custom-function para habilitar a mensagem personalizada no nível do campo.

    /**
    * customMessage
    * @name customMessage
    * @param {object} field
    * @param {scope} globals
    */
    function customMessage(field, globals) {
    const minLength = 15;
    const comments = field.$value.trim();
    if (comments.length < minLength) {
        globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
    }
}

Neste exemplo, se o usuário inserir menos de 15 caracteres na caixa de texto comentários, uma mensagem personalizada será exibida no nível do campo.

A próxima etapa é criar uma regra para o campo comments:

Veja a demonstração abaixo para mostrar que inserir comentários negativos no campo comments aciona a exibição de uma mensagem personalizada no nível do campo:

Se o usuário inserir mais de 15 caracteres na caixa de texto de comentários, o campo será validado e o formulário será enviado:

Caso de uso: enviar dados alterados para o servidor

A seguinte linha de código:
globals.functions.submitForm(globals.functions.exportData(), false); é usado para enviar os dados do formulário após manipulação.

Adicione o seguinte código na função personalizada, conforme explicado na seção create-custom-function, para enviar os dados manipulados no servidor:

    /**
    * submitData
    * @name submitData
    * @param {object} field
    * @param {scope} globals
    */
    function submitData(globals)
    {

    var data = globals.functions.exportData();
    if(!data.comments) {
    data.comments = 'NA';
    }
    console.log('After update:{}',data);
    globals.functions.submitForm(data, false);
    }

Neste exemplo, se o usuário deixar a caixa de texto comments vazia, o NA será enviado ao servidor no envio do formulário.

Agora crie uma regra para o botão Submit que envia dados:

Consulte a ilustração da console window abaixo para demonstrar que, se o usuário deixar a caixa de texto comments vazia, o valor como NA será enviado ao servidor:

Você também pode inspecionar a janela do console para visualizar os dados enviados para o servidor:

Suporte de cache para função personalizada

O Forms adaptável implementa o armazenamento em cache de funções personalizadas para melhorar o tempo de resposta ao recuperar a lista de funções personalizadas no editor de regras. Uma mensagem como Fetched following custom functions list from cache aparece no arquivo error.log.

Caso as funções personalizadas sejam modificadas, o armazenamento em cache é invalidado e é analisado.

Resolução de problemas troubleshooting

Considerações