Introdução às funções personalizadas para o Forms adaptável com base nos Componentes principais

O AEM Forms é compatível com funções personalizadas, permitindo que os usuários definam funções do 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. Eles permitem a alteração dinâmica do comportamento do formulário com base em critérios predefinidos. As funções personalizadas também permitem que os desenvolvedores apliquem uma lógica de validação complexa, executem cálculos dinâmicos e controlem a exibição ou o comportamento de elementos de formulário com base em interações do usuário ou 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 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 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 do 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 delimitando o nome do parâmetro em []. Os parâmetros definidos como opcionais nas anotações do 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.
Verifique se o tipo de parâmetro está entre chaves {} e se 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 a função personalizada OptionalParameterFunction no editor de regras:

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:

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 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óxima etapa

Para criar e usar uma função personalizada no formulário adaptável, consulte o artigo Criar uma função personalizada para um formulário adaptável com base nos componentes principais.

Consulte também