Funciones personalizadas en Forms adaptable (componentes principales)

Introducción

AEM Forms admite funciones personalizadas, lo que permite a los usuarios definir funciones de JavaScript para implementar reglas comerciales complejas. Estas funciones personalizadas amplían las capacidades de los formularios al facilitar la manipulación y el procesamiento de los datos introducidos para satisfacer requisitos específicos. También permiten la modificación dinámica del comportamiento del formulario en función de criterios predefinidos.

Usos de las funciones personalizadas uses-of-custom-function

Las ventajas de utilizar funciones personalizadas en Forms adaptable son:

Las funciones personalizadas son esencialmente bibliotecas de cliente que se agregan en el archivo JavaScript. Una vez creada una función personalizada, esta estará disponible en el editor de reglas para que la seleccione el usuario en un formulario adaptable. Las funciones personalizadas se identifican mediante las anotaciones de JavaScript en el editor de reglas.

Anotaciones de JavaScript compatibles con funciones personalizadas js-annotations

Las anotaciones de JavaScript se utilizan para proporcionar metadatos para el código de JavaScript. Incluye comentarios que comienzan con símbolos específicos, por ejemplo, /** y @. Las anotaciones proporcionan información importante sobre funciones, variables y otros elementos del código. El formulario adaptable admite las siguientes anotaciones de JavaScript para funciones personalizadas:

Nombre

El nombre se utiliza para identificar la función personalizada en el editor de reglas de un formulario adaptable. Se utilizan las siguientes sintaxis para asignar un nombre a una función personalizada:

Parámetro

El parámetro es una lista de argumentos que utilizan las funciones personalizadas. Una función puede admitir varios parámetros. Las siguientes sintaxis se utilizan para definir un parámetro en una función personalizada:

El tipo de parámetro no distingue entre mayúsculas y minúsculas y no se permiten espacios en el nombre del parámetro.

<Parameter Description> contiene detalles sobre el propósito del parámetro. Puede tener varias palabras.

Parámetros opcionales
De forma predeterminada, todos los parámetros son obligatorios. Puede definir un parámetro como opcional agregando = después del tipo de parámetro o incluyendo el nombre del parámetro en []. Los parámetros definidos como opcionales en las anotaciones de JavaScript se muestran como opcionales en el editor de reglas.
Para definir una variable como parámetro opcional, puede utilizar cualquiera de las siguientes sintaxis:

En la línea de código anterior, Input1 es un parámetro opcional sin ningún valor predeterminado. Para declarar un parámetro opcional con el valor predeterminado:
@param {string=<value>} input1

input1 como parámetro opcional con el valor predeterminado establecido en value.

En la línea de código anterior, Input1 es un parámetro opcional sin ningún valor predeterminado. Para declarar un parámetro opcional con el valor predeterminado:
@param {array} [input1=<value>]
input1 es un parámetro opcional de tipo matriz con el valor predeterminado establecido en value.
Asegúrese de que el tipo de parámetro está entre llaves {} y el nombre del parámetro está entre corchetes.

Considere el siguiente fragmento de código, donde input2 se define como un 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;
        }

La siguiente ilustración muestra el uso de la función personalizada OptionalParameterFunction en el editor de reglas:

Puede guardar la regla sin especificar un valor para los parámetros necesarios, pero la regla no se ejecuta y muestra un mensaje de advertencia como:

Cuando el usuario deja vacío el parámetro opcional, el valor "Undefined" se pasa a la función personalizada para el parámetro opcional.

Para obtener más información acerca de cómo definir parámetros opcionales en JSDocs, haga clic aquí.

Tipo de devolución

El tipo de valor devuelto especifica el tipo de valor que la función personalizada devuelve después de la ejecución. Las siguientes sintaxis se utilizan para definir un tipo de valor devuelto en una función personalizada:

Privado

La función personalizada, declarada como privada, no aparece en la lista de funciones personalizadas del editor de reglas de un formulario adaptable. De forma predeterminada, las funciones personalizadas son públicas. La sintaxis para declarar la función personalizada como privada es @private.

Directrices al crear funciones personalizadas

Para enumerar las funciones personalizadas en el editor de reglas, puede utilizar cualquiera de los siguientes formatos:

Instrucción de función con o sin comentarios jsdoc

Puede crear una función personalizada con o sin comentarios jsdoc.

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

Si el usuario no agrega ninguna anotación de JavaScript a la función personalizada, se muestra en el editor de reglas por su nombre de función. Sin embargo, se recomienda incluir anotaciones de JavaScript para mejorar la legibilidad de las funciones personalizadas.

Función de flecha con anotaciones o comentarios JavaScript obligatorios

Puede crear una función personalizada con una sintaxis de función de flecha:

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

Si el usuario no agrega ninguna anotación de JavaScript a la función personalizada, la función personalizada no aparece en la lista del editor de reglas de un formulario adaptable.

Expresión de función con anotaciones o comentarios JavaScript obligatorios

Para enumerar funciones personalizadas en el editor de reglas de un formulario adaptable, cree funciones personalizadas en el siguiente 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
        }

Si el usuario no agrega ninguna anotación de JavaScript a la función personalizada, la función personalizada no aparece en la lista del editor de reglas de un formulario adaptable.

Creación de una función personalizada create-custom-function

Cree una biblioteca de cliente para llamar a funciones personalizadas en el editor de reglas. Para obtener más información, consulte Uso de bibliotecas del lado del cliente.

Los pasos para crear funciones personalizadas son los siguientes:

Requisitos previos para crear una función personalizada

Antes de empezar a agregar una función personalizada a su Forms adaptable, asegúrese de que dispone de lo siguiente:

Software:

Crear una biblioteca de cliente create-client-library

Puede agregar funciones personalizadas agregando una biblioteca de cliente. Para crear una biblioteca de cliente, realice los siguientes pasos:

Clonar el repositorio

Clonar su repositorio as a Cloud Service de AEM Forms:

Este comando descarga el repositorio y crea una carpeta local del repositorio clonado en el equipo. En esta guía, nos referimos a esta carpeta como el [directorio del proyecto AEMaaCS].

Agregar una carpeta de biblioteca de cliente

Para agregar una nueva carpeta de biblioteca de cliente al [directorio del proyecto AEMaaCS], siga estos pasos:

Agregar archivos y carpetas a la carpeta Biblioteca de cliente

Agregue lo siguiente a la carpeta de biblioteca de cliente agregada:

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

Incluir la nueva carpeta en filter.xml:

AEM Implemente la carpeta Client library recién creada en su entorno de la biblioteca de cliente

Implemente AEM as a Cloud Service, [directorio del proyecto AEMaaCS], en su entorno de Cloud Service. Para implementarlo en el entorno de Cloud Service:

Si aún no ha configurado una canalización, consulte la guía sobre cómo configurar una canalización para AEM Forms as a Cloud Service.

Una vez que la canalización se haya ejecutado correctamente, la función personalizada agregada en la biblioteca de cliente estará disponible en el editor de reglas de formularios adaptables.

Agregar una biblioteca de cliente a un formulario adaptable use-custom-function

Una vez que haya implementado la biblioteca de cliente en el entorno de Forms CS, utilice sus funcionalidades en el formulario adaptable. Para agregar la biblioteca de cliente en el formulario adaptable

Puede usar la función personalizada en el editor de reglas de un formulario adaptable mediante las anotaciones de JavaScript.

Usar una función personalizada en un formulario adaptable

En un formulario adaptable, puede usar funciones personalizadas dentro del editor de reglas. Agregue el siguiente código al archivo JavaScript (archivo Function.js) para calcular la edad en función de la fecha de nacimiento (DD-MM-AAAA). Cree una función personalizada como calculateAge() que tome la fecha de nacimiento como entrada y devuelva la edad:

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

En el ejemplo anterior, cuando el usuario introduce la fecha de nacimiento con el formato (AAAA-MM-DD), se invoca la función personalizada calculateAge y se devuelve la edad.

Vamos a previsualizar el formulario para observar cómo se implementan las funciones personalizadas a través del editor de reglas:

Establecer las opciones de la lista desplegable mediante funciones personalizadas

El editor de reglas de los componentes principales no admite la propiedad Set Options of para establecer las opciones de la lista desplegable durante la ejecución. Sin embargo, puede establecer las opciones de la lista desplegable mediante funciones personalizadas.

Consulte el siguiente código para ver cómo podemos establecer las opciones de la lista desplegable con funciones 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"];
    }

En el código anterior, setEnums se usa para establecer la propiedad enum y setEnumNames se usa para establecer la propiedad enumNames de la lista desplegable.

Vamos a crear una regla para el botón Next, que establece la opción de valor de la lista desplegable cuando el usuario haga clic en el botón Next:

Consulte la siguiente ilustración para demostrar dónde están configuradas las opciones de la lista desplegable al hacer clic en el botón Mostrar:

Compatibilidad con funciones asincrónicas en funciones personalizadas support-of-async-functions

Las funciones personalizadas asincrónicas no aparecen en la lista del editor de reglas. Sin embargo, es posible invocar funciones asincrónicas dentro de funciones personalizadas creadas mediante expresiones de función sincrónicas.

Consulte el siguiente código para ver cómo se pueden invocar funciones asincrónicas mediante funciones 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);
    });
}

En el ejemplo anterior, la función asyncFunction es un asynchronous function. Realiza una operación asincrónica realizando una solicitud GET a https://petstore.swagger.io/v2/store/inventory. Espera la respuesta con await, analiza el cuerpo de la respuesta como JSON con response.json() y, a continuación, devuelve los datos. La función callAsyncFunction es una función sincrónica personalizada que invoca la función asyncFunction y muestra los datos de respuesta en la consola. Aunque la función callAsyncFunction es sincrónica, llama a la función asyncFunction asincrónica y controla su resultado con instrucciones then y catch.

Para ver cómo funciona, vamos a agregar un botón y crear una regla para el botón que invoca la función asincrónica al hacer clic en un botón.

Consulte la ilustración de la ventana de la consola siguiente para demostrar que cuando el usuario hace clic en el botón Fetch, se invoca la función personalizada callAsyncFunction, que a su vez llama a una función asincrónica asyncFunction. Inspect abre la ventana de la consola para ver la respuesta al botón y hacer clic en:

Vamos a profundizar en las funciones personalizadas.

Varias funciones para funciones personalizadas

Puede utilizar funciones personalizadas para agregar características personalizadas a los formularios. Estas funciones admiten varias capacidades, como trabajar con campos específicos, utilizar campos globales o almacenar en caché. Esta flexibilidad le permite personalizar formularios según los requisitos de su organización.

Objetos Field y Global scope en funciones personalizadas support-field-and-global-objects

Los objetos de campo hacen referencia a los componentes o elementos individuales de un formulario, como campos de texto o casillas de verificación. El objeto Globals contiene variables de solo lectura como la instancia de formulario, la instancia del campo de destino y los métodos para realizar modificaciones de formulario dentro de funciones personalizadas.

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo con la ayuda de un formulario Contact Us que utiliza diferentes casos de uso.

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

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

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

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

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

/**

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

Compatibilidad de almacenamiento en caché para función personalizada

Los Forms adaptables implementan el almacenamiento en caché de funciones personalizadas para mejorar el tiempo de respuesta al recuperar la lista de funciones personalizadas en el editor de reglas. Aparece un mensaje como Fetched following custom functions list from cache en el archivo error.log.

En caso de que se modifiquen las funciones personalizadas, el almacenamiento en caché se invalidará y se analizará.

Resolución de problemas troubleshooting

Consideraciones

Consulte también see-also