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)

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.

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

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

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:

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 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:

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.

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:

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:

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:

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:

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:

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

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.

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

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:

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

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 é 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.

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:

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.

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.

    /**
    * 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});
       }
    }

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

        globals.functions.validate(field);

    }

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

        globals.functions.reset(field);

    }

    /**
    * 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 });
    }
}

    /**
    * 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);
    }

/**
 * 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);
}