Este artigo contémOverride form submission success and error handlerscomo um recurso de pré-lançamento. O recurso de pré-lançamento pode ser acessado somente por meio de canal de pré-lançamento.

Funções personalizadas no Adaptive Forms (Componentes principais)

Versão
Link do artigo
AEM 6.5
Clique aqui
AEM as a Cloud Service
Este artigo

Introdução

O AEM Forms é compatível com funções personalizadas, permitindo que os usuários definam funções JavaScript para implementar regras de negócios complexas. Essas funções personalizadas estendem os recursos dos formulários facilitando a manipulação e o processamento dos dados inseridos para atender a requisitos especificados. Elas também permitem a alteração dinâmica do comportamento do formulário com base em critérios predefinidos.

NOTE
Certifique-se de que o componente principal está definido com a versão mais recente para usar os recursos mais recentes.

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

As vantagens de usar funções personalizadas no Adaptive Forms são:

  • Tratamento de dados: as funções personalizadas ajudam a processar dados inseridos nos campos de formulários.
  • Validação de dados: As funções personalizadas permitem que você execute verificações personalizadas nas entradas do formulário e forneça mensagens de erro especificadas.
  • Comportamento dinâmico: as funções personalizadas permitem controlar o comportamento dinâmico dos formulários com base em condições específicas. Por exemplo, você pode mostrar/ocultar campos, modificar valores de campo ou ajustar a lógica do formulário dinamicamente.
  • Integração: você pode usar funções personalizadas para integrar-se a APIs ou serviços externos. Ele ajuda a buscar dados de fontes externas, enviar dados para endpoints Rest externos ou executar ações personalizadas com base em eventos externos.

As funções personalizadas são essencialmente bibliotecas de clientes adicionadas ao arquivo 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 JavaScript no editor de regras.

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

As anotações JavaScript são usadas para fornecer 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 JavaScript para funções personalizadas:

Nome

O nome é 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:

  • @name [functionName] <Function Name>
  • @function [functionName] <Function Name>
  • @func [functionName] <Function Name>.
    functionName é o nome da função. Espaços não são permitidos.
    <Function Name> é o nome de exibição da função no editor de regras de um Formulário adaptável.
    Se o nome da função for idêntico ao nome da própria função, você poderá omitir [functionName] na sintaxe.

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:

  • @param {type} name <Parameter Description>

  • @argument {type} name <Parameter Description>

  • @arg {type} name <Parameter Description>.
    {type} representa o tipo de parâmetro. Os tipos de parâmetros permitidos são:

    • string: representa um único valor de string.
    • number: representa um único valor numérico.
    • booleano: representa um único valor booleano (verdadeiro ou falso).
    • string[]: representa uma matriz de valores de cadeia de caracteres.
    • número[]: representa uma matriz de valores numéricos.
    • booleano[]: representa uma matriz de valores booleanos.
    • date: representa um único valor de data.
    • data[]: representa uma matriz de valores de data.
    • array: representa uma matriz genérica contendo valores de vários tipos.
    • object: representa o objeto de formulário passado para uma função personalizada em vez de passar seu valor diretamente.
    • escopo: representa o objeto global, que contém variáveis somente leitura, como instâncias de formulário, instâncias de campo de destino e métodos para executar modificações de formulário em funções personalizadas. Ele é declarado como o último parâmetro nas anotações JavaScript e não está visível no editor de regras de um Formulário adaptável. O parâmetro scope acessa o objeto do formulário ou componente para acionar a regra ou o evento necessário para o processamento do formulário. Para obter mais informações sobre o objeto Globals e como usá-lo, clique aqui.

O tipo de parâmetro 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.

Parâmetros opcionais
Por padrão, todos os parâmetros são obrigatórios. Você pode definir um parâmetro como opcional adicionando = após o tipo de parâmetro ou ao delimitar o nome do parâmetro em []. Os parâmetros definidos como opcionais nas anotações JavaScript são exibidos como opcionais no editor de regras.
Para definir uma variável como parâmetro opcional, você pode usar qualquer uma das seguintes sintaxes:

  • @param {type=} Input1

Na linha de código acima, Input1 é um parâmetro opcional sem nenhum valor padrão. Para declarar parâmetro opcional com valor padrão:
@param {string=<value>} input1

input1 como um parâmetro opcional com o valor padrão definido como value.

  • @param {type} [Input1]

Na linha de código acima, Input1 é um parâmetro opcional sem nenhum valor padrão. Para declarar parâmetro opcional com valor padrão:
@param {array} [input1=<value>]
input1 é um parâmetro opcional do tipo matriz com o valor padrão definido como value.
Certifique-se de que o tipo de parâmetro esteja entre chaves {} e o nome do parâmetro está entre colchetes.

Considere o seguinte trecho de código, em que input2 é definido como um parâmetro opcional:

        /**
         * optional parameter function
         * @name OptionalParameterFunction
         * @param {string} input1
         * @param {string=} input2
         * @return {string}
        */
        function OptionalParameterFunction(input1, input2) {
        let result = "Result: ";
        result += input1;
        if (input2 !== null) {
            result += " " + input2;
        }
        return result;
        }

A ilustração a seguir é exibida usando o OptionalParameterFunction função personalizada no editor de regras:

Parâmetros opcionais ou obrigatórios

Você pode salvar a regra sem especificar um valor para os parâmetros necessários, mas a regra não é executada e exibe uma mensagem de aviso como:

aviso de regra incompleta

Quando o usuário deixa o parâmetro opcional vazio, o valor "Indefinido" é passado para a função personalizada do parâmetro opcional.

Para saber mais sobre como definir parâmetros opcionais em JSDocs, clique aqui.

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:

  • @return {type}

  • @returns {type}
    {type} representa o tipo de retorno da função. Os tipos de retorno permitidos são:

    • string: representa um único valor de string.
    • number: representa um único valor numérico.
    • booleano: representa um único valor booleano (verdadeiro ou falso).
    • string[]: representa uma matriz de valores de cadeia de caracteres.
    • número[]: representa uma matriz de valores numéricos.
    • booleano[]: representa uma matriz de valores booleanos.
    • date: representa um único valor de data.
    • data[]: representa uma matriz de valores de data.
    • array: representa uma matriz genérica contendo valores de vários tipos.
    • object: representa o objeto de formulário diretamente em vez do seu valor.

    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

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 JavaScript à função personalizada, ela será listada no editor de regras pelo nome da função. No entanto, é recomendável incluir anotações 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.

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

Crie uma biblioteca do cliente para chamar funções personalizadas no editor de regras. Para obter mais informações, consulte Uso de bibliotecas do lado do cliente.

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

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:

  • Editor de texto sem formatação (IDE): Embora qualquer editor de texto simples possa funcionar, um IDE (Integrated Development Environment, ambiente de desenvolvimento integrado), como o Microsoft Visual Studio Code, oferece recursos avançados para facilitar a edição.

  • Git: Este sistema de controle de versão é necessário para gerenciar alterações de código. Se não estiver instalado, baixe-o de https://git-scm.com.

Criar uma biblioteca do cliente create-client-library

É possível adicionar funções personalizadas adicionando uma biblioteca do cliente. Para criar uma biblioteca do cliente, execute as seguintes etapas:

Clonar o repositório

Clonar seu Repositório as a Cloud Service do AEM Forms:

  1. Abra a linha de comando ou a janela do terminal.

  2. Navegue até o local desejado na máquina em que deseja armazenar o repositório.

  3. Execute o seguinte comando para clonar o repositório:

    git clone [Git Repository URL]

Este comando faz o download do repositório e cria uma pasta local do repositório clonado no computador. Neste guia, nos referimos a essa pasta como a [Diretório de projeto do AEMaaCS].

Adicionar uma pasta da biblioteca do cliente

Para adicionar uma nova pasta da biblioteca do cliente à [Diretório de projeto do AEMaaCS], siga estas etapas:

  1. Abra o [Diretório de projeto do AEMaaCS] em um editor.

    estrutura de pasta de função personalizada

  2. Localizar ui.apps.

  3. Adicionar nova pasta. Por exemplo, adicione uma pasta chamada como experience-league.

  4. Navegue até /experience-league/ e adicionar uma ClientLibraryFolder. Por exemplo, crie uma pasta da biblioteca do cliente chamada como customclientlibs.

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

Adicionar arquivos e pastas à pasta Biblioteca do cliente

Adicione o seguinte à pasta da biblioteca do cliente adicionada:

  • arquivo .content.xml
  • arquivo js.txt
  • pasta js

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

  1. No .content.xml adicione as seguintes linhas de código:

    code language-javascript
    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:ClientLibraryFolder"
    categories="[customfunctionscategory]"/>
    
    note note
    NOTE
    Você pode escolher qualquer nome para client library folder e categories propriedade.
  2. No js.txt adicione as seguintes linhas de código:

    code language-javascript
          #base=js
        function.js
    
  3. No js , adicione o arquivo javascript como function.js que inclui as funções personalizadas:

    code language-javascript
     /**
         * 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;
     }
    
  4. Salve os arquivos.

estrutura de pasta de função personalizada

Incluir a nova pasta no filter.xml:

  1. Navegue até a /ui.apps/src/main/content/META-INF/vault/filter.xml arquivo em seu [Diretório de projeto do AEMaaCS].

  2. Abra o arquivo e adicione a seguinte linha no final:

    <filter root="/apps/experience-league" />

  3. Salve o arquivo.

xml de filtro de função personalizada

Implante a pasta da biblioteca do cliente recém-criada no ambiente AEM

Implantar o AEM as a Cloud Service, [Diretório de projeto do AEMaaCS], para o ambiente de Cloud Service. Para implantar no ambiente de Cloud Service:

  1. Confirmar as alterações

    1. Adicione, confirme e envie as alterações no repositório usando os comandos abaixo:
    code language-javascript
        git add .
        git commit -a -m "Adding custom functions"
        git push
    
  2. Implante o código atualizado:

    1. Acione uma implantação do seu código por meio do pipeline de pilha completa existente. Isso cria e implanta automaticamente o código atualizado.

Se você ainda não tiver configurado um pipeline, consulte o manual sobre como configurar um pipeline para o AEM Forms as a Cloud Service.

Depois que o pipeline for executado com êxito, a função personalizada adicionada à biblioteca do cliente ficará disponível no Editor de regras do Formulário adaptável.

Adicionar a biblioteca do cliente a um Formulário adaptável use-custom-function

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

  1. Abra o formulário no modo de edição. Para abrir um formulário no modo de edição, selecione um formulário e Editar.

  2. Abra o Navegador de conteúdo e selecione a variável Contêiner do guia componente do seu Formulário adaptável.

  3. Clique nas propriedades do Container do guia Propriedades do guia ícone. A caixa de diálogo Contêiner de formulário adaptável é aberta.

  4. Abra o Básico e selecione o nome da variável categoria da biblioteca do cliente na lista suspensa (nesse caso, selecione customfunctionscategory).

    Adição da biblioteca de cliente de função personalizada

    note note
    NOTE
    É possível adicionar várias categorias especificando uma lista separada por vírgulas na Categoria da biblioteca do cliente campo.
  5. Clique em Concluído.

Você pode usar a função personalizada no editor de regras de um Formulário adaptável usando o Anotações JavaScript.

Uso de uma função personalizada em um Formulário adaptável

Em um Formulário adaptável, é possível usar funções personalizadas no editor de regras. Vamos adicionar o seguinte código ao arquivo JavaScript (Function.js arquivo) para calcular a idade com base na Data de nascimento (AAAA-MM-DD). Criar uma função personalizada como calculateAge() que toma a data de nascimento como entrada e retorna 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 é chamado e retorna a idade.

Função personalizada Calcular idade no Editor de regras

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

Função personalizada Calcular Idade na Visualização de Formulário do Editor de Regras

NOTE
Você pode consultar o seguinte função personalizada pasta. Baixe e instale essa pasta na instância do AEM usando o Gerenciador de pacotes.

Definir as opções da lista suspensa usando funções personalizadas

O Editor de regras nos Componentes principais não oferece suporte a Definir Opções de propriedade para definir as opções da lista suspensa no tempo de execução. No entanto, é possível definir as opções da lista suspensa usando funções personalizadas.

Examine o código abaixo para ver como podemos definir as opções da lista suspensa usando funções personalizadas:

    /**
    * @name setEnums
    * @returns {string[]}
    **/
    function setEnums() {
    return ["0","1","2","3","4","5","6"];
    }

    /**
    * @name setEnumNames
    * @returns {string[]}
    **/
    function setEnumNames() {
    return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
    }

No código acima, setEnums é usado para definir o enum propriedade e setEnumNames é usado para definir o enumNames propriedade do menu suspenso.

Vamos criar uma regra para o Next botão, que define o valor da opção de lista suspensa quando o usuário clica no Next botão:

Opções da lista suspensa

Consulte a ilustração abaixo para demonstrar onde as opções da lista suspensa são definidas ao clicar no botão Display:

Opções suspensas no 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.

Função personalizada síncrona e assíncrona

NOTE
A vantagem de chamar funções assíncronas em funções personalizadas é que as funções assíncronas permitem a execução simultânea de várias tarefas, com o resultado de cada função usada nas funções personalizadas.

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 é uma asynchronous function. Ele executa uma operação assíncrona tornando um GET solicitação para https://petstore.swagger.io/v2/store/inventory. Ele aguarda a resposta usando await, analisa o corpo da resposta como JSON usando o response.json()e retorna os dados. A variável callAsyncFunction é uma função personalizada síncrona que chama a variável asyncFunction e exibe os dados de resposta no console. Embora a callAsyncFunction é síncrona, ela chama a função assíncrona asyncFunction e lida com seu resultado com then e catch declarações.

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.

criando regra para função assíncrona

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

Janela do console

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

Os objetos Field 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.

NOTE
A variável param {scope} globals deve ser o último parâmetro e não é exibido no editor de regras de um Formulário adaptável.

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

Formulário Contate-nos

Caso de uso: mostrar um painel usando o SetProperty regra

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

code language-javascript

    /**
    * 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});
       }
    }
note note
NOTE
  • É possível configurar as propriedades do campo usando as propriedades disponíveis localizadas em [form-path]/jcr:content/guideContainer.model.json.
  • As modificações feitas no formulário usando o setProperty O método do objeto Globals é de natureza assíncrona e não é refletido durante a execução da função personalizada.

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

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

Definir propriedade

Consulte a ilustração abaixo para demonstrar onde a variável personaldetails for validado ao clicar no link Next botão. Caso todos os campos dentro do personaldetails forem validados, a variável feedback painel fica visível.

Definir propriedade para visualização do formulário

Se houver erros nos campos do personaldetails são exibidos no nível do campo ao clicar no botão Next e o botão feedback permanece invisível.

Definir propriedade para visualização do formulário

Caso de uso: valide o campo.

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

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

        globals.functions.validate(field);

    }
note note
NOTE
Se nenhum argumento for transmitido na variável validate() valida o formulário.

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

Padrão de validação do endereço de email

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

Padrão de validaçã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 é exibida no nível do campo:

Padrão de validação do endereço de email

Se o usuário digitar um número de telefone válido e todos os campos na variável personaldetails forem validados, a variável feedback será exibido na tela:

Padrão de validação do endereço de email

Caso de uso: redefinir um painel

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

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

        globals.functions.reset(field);

    }
note note
NOTE
Se nenhum argumento for transmitido na variável reset() valida o formulário.

Neste exemplo, a variável personaldetails O painel é redefinido ao clicar no ícone Clear botão. A próxima etapa é criar uma regra para o Clear botão que redefine o painel no clique de botão.

Botão Limpar

Consulte a ilustração abaixo para exibir que, se o usuário clicar no ícone clear botão, o botão personaldetails o painel é redefinido:

Redefinir formulário

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

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

  • globals.functions.markFieldAsInvalid(field.$id,"[custom message]",{useId: true});
  • globals.functions.markFieldAsInvalid(field.$qualifiedName, "[custom message]", {useQualifiedName: true});
  • globals.functions.markFieldAsInvalid(field.$dataRef, "[custom message]", {useDataRef: true});

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

code language-javascript
    /**
    * 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 comments campo:

Marcar campo como inválido

Consulte a demonstração abaixo para exibir que inserir feedback negativo na comments aciona a exibição de uma mensagem personalizada no nível do campo:

Marcar campo como Formulário de visualização inválido

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:

Marcar campo como formulário de Visualização válido

Caso de uso: Enviar os 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.

  • O primeiro argumento diz respeito aos dados a apresentar.
  • O segundo argumento representa se o formulário deve ser validado antes do envio. É necessário optional e definir como true por padrão.
  • O terceiro argumento é contentType do envio, que também é opcional com o valor padrão como multipart/form-data. Os outros valores podem ser application/json e application/x-www-form-urlencoded.

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

code language-javascript
    /**
    * 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 variável comments caixa de texto vazia, a variável NA é enviado ao servidor no envio do formulário.

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

Enviar dados

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

Enviar dados na janela do console

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

Dados do Inspect na janela do console

Caso de uso: substituição de manipuladores de erro e de sucesso no envio do formulário

Adicione a seguinte linha de código, conforme explicado na create-custom-function para personalizar a mensagem de envio ou de falha para envios de formulário e exibir as mensagens de envio de formulário em uma caixa modal:

code language-javascript
/**
 * Handles the success response after a form submission.
 *
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitSuccessHandler(globals) {
    var event = globals.event;
    var submitSuccessResponse = event.payload.body;
    var form = globals.form;

    if (submitSuccessResponse) {
        if (submitSuccessResponse.redirectUrl) {
            window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
        } else if (submitSuccessResponse.thankYouMessage) {
            showModal("success", submitSuccessResponse.thankYouMessage);
        }
    }
}

/**
 * Handles the error response after a form submission.
 *
 * @param {string} customSubmitErrorMessage - The custom error message.
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
    showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
    // Remove any existing modals
    var existingModal = document.getElementById("modal");
    if (existingModal) {
        existingModal.remove();
    }

    // Create the modal dialog
    var modal = document.createElement("div");
    modal.setAttribute("id", "modal");
    modal.setAttribute("class", "modal");

    // Create the modal content
    var modalContent = document.createElement("div");
    modalContent.setAttribute("class", "modal-content");

    // Create the modal header
    var modalHeader = document.createElement("div");
    modalHeader.setAttribute("class", "modal-header");
    modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";

    // Create the modal body
    var modalBody = document.createElement("div");
    modalBody.setAttribute("class", "modal-body");
    modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";

    // Create the modal footer
    var modalFooter = document.createElement("div");
    modalFooter.setAttribute("class", "modal-footer");

    // Create the close button
    var closeButton = document.createElement("button");
    closeButton.setAttribute("class", "close-button");
    closeButton.innerHTML = "Close";
    closeButton.onclick = function() {
        modal.remove();
    };

    // Append the elements to the modal content
    modalFooter.appendChild(closeButton);
    modalContent.appendChild(modalHeader);
    modalContent.appendChild(modalBody);
    modalContent.appendChild(modalFooter);

    // Append the modal content to the modal
    modal.appendChild(modalContent);

    // Append the modal to the document body
    document.body.appendChild(modal);
}

Neste exemplo, quando o usuário usa a variável customSubmitSuccessHandler e customSubmitErrorHandler funções personalizadas, as mensagens de sucesso e falha são exibidas em uma modal. A função JavaScript showModal(type, message) é usado para criar e exibir dinamicamente uma caixa de diálogo modal em uma tela.

Agora, crie uma regra para o envio bem-sucedido do formulário:

Êxito no envio do formulário

Consulte a ilustração abaixo para demonstrar que, quando o formulário for enviado com êxito, a mensagem de sucesso será exibida em uma modal:

Mensagem de sucesso de envio de formulário

Da mesma forma, vamos criar uma regra para envios de formulários com falha:

Falha no envio do formulário

Consulte a ilustração abaixo para demonstrar que, quando o envio do formulário falhar, a mensagem de erro será exibida em uma modal:

Mensagem de falha no envio do formulário

Para exibir o sucesso e a falha no envio do formulário de maneira padrão, a variável Default submit Form Success Handler e Default submit Form Error Handler As funções do estão disponíveis imediatamente.

Caso o manipulador de envio personalizado não seja executado conforme esperado em projetos ou formulários AEM existentes, consulte solução de problemas seção.

Caso de uso: Execute ações em uma instância específica do painel repetível

As regras criadas usando o editor visual de regras em um painel repetível se aplicam à última instância do painel repetível. Para escrever uma regra para uma instância específica do painel repetível, podemos usar uma função personalizada.

Vamos criar outro formulário para coletar informações sobre os viajantes que estão indo para um destino. Um painel de viagens é adicionado como um painel repetível, em que o usuário pode adicionar detalhes para 5 viajantes usando o Add Traveler botão.

Informações do viajante

Adicione a seguinte linha de código, conforme explicado na create-custom-function para executar ações em uma instância específica do painel repetível, diferente da última:

code language-javascript
/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
    var repeatablePanel = globals.form.travelerinfo;
    // hides a panel inside second instance of repeatable panel
    globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}

Neste exemplo, a variável hidePanelInRepeatablePanel a função personalizada executa uma ação em uma instância específica do painel repetível. No código acima, travelerinfo representa o painel repetível. A variável repeatablePanel[1].traveler, {visible: false} o código do oculta o painel na segunda instância do painel repetível.

Vamos adicionar um botão rotulado Hide e adicione uma regra para ocultar a segunda ocorrência de um painel repetível.

Ocultar regra de Painel

Consulte o vídeo abaixo para demonstrar que, quando a variável Hide for clicado, o painel na segunda instância repetível ficará oculto:

embed

https://video.tv.adobe.com/v/3429554?quality=12&learn=on

Caso de uso: Preencha previamente o campo com um valor quando o formulário for carregado

Adicione a seguinte linha de código, conforme explicado na seção create-custom-function para carregar o valor pré-preenchido em um campo quando o formulário for inicializado:

code language-javascript
/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

No código acima referido, a testImportData A função preenche o Booking Amount campo de caixa de texto quando o formulário é carregado. Vamos supor que o formulário de reserva exige que o valor mínimo de reserva seja 10,000.

Vamos criar uma regra na inicialização do formulário, em que o valor no campo Booking Amount o campo textbox é pré-preenchido com um valor especificado quando o formulário é carregado:

Importar Regra de Dados

Consulte a captura de tela abaixo, que demonstra que, quando o formulário é carregado, o valor na variável Booking Amount A caixa de texto é pré-preenchida com um valor especificado:

Formulário de Regra de Importação de Dados

Caso de uso: Defina o foco no campo específico

Adicione a seguinte linha de código, conforme explicado na seção create-custom-function para definir o foco no campo especificado quando a variável Submit é clicado.:

code language-javascript
/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

Vamos adicionar uma regra ao Submit botão para definir o foco na variável Email ID campo de caixa de texto ao clicar:

Definir regra de foco

Consulte a captura de tela abaixo, que demonstra que, quando a variável Submit for clicado, o foco será definido na variável Email ID campo:

Definir regra de foco

note note
NOTE
Você pode usar o $focusOption parâmetro, se você quiser se concentrar no campo seguinte ou anterior relativo ao email campo.
Caso de uso: adicione ou exclua o painel repetível usando o dispatchEvent propriedade

Adicione a seguinte linha de código, conforme explicado na seção create-custom-function para adicionar um painel quando a variável Add Traveler é clicado usando o dispatchEvent propriedade:

code language-javascript
/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

Vamos adicionar uma regra ao Add Traveler botão para adicionar o painel repetível quando for clicado:

Adicionar regra do painel

Consulte o gif abaixo, que demonstra que, quando o Add Traveler for clicado, o painel será adicionado usando o dispatchEvent propriedade:

Adicionar painel

Da mesma forma, adicione a seguinte linha de código, conforme explicado na seção create-custom-function para excluir um painel quando a variável Delete Traveler é clicado usando o dispatchEvent propriedade:

code language-javascript
/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

Vamos adicionar uma regra ao Delete Traveler botão para excluir o painel repetível quando for clicado:

Excluir regra do painel

Consulte o gif abaixo, que demonstra que, quando o Delete Traveler for clicado, o painel viajante será excluído usando a dispatchEvent propriedade:

Excluir painel

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 na guia error.log arquivo.

função personalizada com suporte a cache

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

Resolução de problemas troubleshooting

  • Se o manipulador de envio personalizado não funcionar conforme esperado em projetos ou formulários AEM existentes, execute as seguintes etapas:

    • Certifique-se de que o a versão dos componentes principais foi atualizada para 3.0.18 e posterior. No entanto, para projetos e formulários AEM existentes, há etapas adicionais a seguir:

    • Para o projeto AEM, o usuário deve substituir todas as instâncias de submitForm('custom:submitSuccess', 'custom:submitError') com submitForm() e implante o projeto por meio do pipeline do Cloud Manager.

    • Para formulários existentes, se os manipuladores de envio personalizados não estiverem funcionando corretamente, o usuário precisará abrir e salvar o submitForm regra no Enviar usando o Editor de regras. Essa ação substitui a regra existente de submitForm('custom:submitSuccess', 'custom:submitError') com submitForm() no formulário.

  • Se o arquivo JavaScript que contém o código para funções personalizadas tiver um erro, as funções personalizadas não serão listadas no editor de regras de um Formulário adaptável. Para verificar a lista de funções personalizadas, você pode navegar até a error.log para o erro. No caso de um erro, a lista de funções personalizadas aparece vazia:

    arquivo de log de erros

    Caso não haja erro, a função personalizada é buscada e aparece no error.log arquivo. Uma mensagem como Fetched following custom functions list aparece na guia error.log arquivo:

    arquivo de log de erros com função personalizada adequada

Considerações

  • A variável parameter type e return type não oferecem suporte None.

  • As funções não suportadas na lista de funções personalizadas são:

    • Funções geradoras
    • Funções assíncronas/Await
    • Definições de método
    • Métodos de classe
    • Parâmetros padrão
    • Parâmetros rest

Consulte também see-also

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab