Funciones personalizadas en los componentes principales de Forms adaptable

Este artículo describe la creación de funciones personalizadas con el componente principal del formulario adaptable más reciente, que tienen las funciones más recientes, como las siguientes:

Asegúrese de establecer la última versión del formulario en el entorno del componente principal de AEM Forms para utilizar las características más recientes en las funciones personalizadas.

Introducción

AEM Forms 6.5 incluye funciones de JavaScript que le permiten definir reglas comerciales complejas mediante el editor de reglas. Aunque AEM Forms ofrece una variedad de funciones personalizadas integradas, muchos casos de uso requieren la definición de sus propias funciones personalizadas para utilizarlas en varios formularios. Estas funciones personalizadas mejoran las capacidades de los formularios al permitir la manipulación y el procesamiento de los datos introducidos para satisfacer requisitos específicos. Además, permiten modificar dinámicamente el 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 los componentes principales de Forms adaptables 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 proporcionan metadatos para el código JavaScript. Incluye comentarios que comienzan con símbolos específicos como /** 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

Name se usa para identificar la función personalizada en el editor de reglas de un formulario adaptable. Las siguientes sintaxis se utilizan para asignar un nombre a una función personalizada:

Parámetro

El Parámetro es una lista de argumentos utilizados por 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 es 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.

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:

El tipo de valor devuelto no distingue entre mayúsculas y minúsculas.

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 considerations

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.

Requisitos previos para crear una función personalizada

Antes de empezar a añadir una función personalizada a su Forms adaptable, asegúrese de que tiene instalado el siguiente software en su equipo:

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

Los pasos para crear funciones personalizadas son los siguientes:

AEM Crear una biblioteca de cliente con el tipo de archivo del proyecto de create-client-library-archetype

AEM Puede agregar funciones personalizadas agregando una biblioteca de cliente al proyecto creado mediante el tipo de archivo del proyecto de.
Si tiene un proyecto existente , puede agregar directamente funciones personalizadas a su proyecto local.

Después de crear un proyecto de tipo de archivo o de utilizar uno existente, cree una biblioteca de cliente. Para crear una biblioteca de cliente, realice los siguientes pasos:

Agregar una carpeta de biblioteca de cliente

AEM Para agregar una nueva carpeta de biblioteca de cliente al [directorio de proyecto de la], siga los 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:

Crear e implementar funciones personalizadas mediante CRXDE create-add-custom-function

Si está utilizando el complemento más reciente de AEM Forms y Forms, puede crear una función personalizada a través de CRXDE para utilizar las últimas actualizaciones de las funciones personalizadas. Para ello, realice los siguientes pasos:

Puede hacer referencia a la carpeta función personalizada siguiente. AEM Descargue e instale esta carpeta en su instancia de.

Ahora puede utilizar la función personalizada en el formulario adaptable agregando la biblioteca de cliente.

Agregar una biblioteca de cliente en un formulario adaptable add-client-library

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

Ahora puede crear una regla para utilizar funciones personalizadas en el editor de reglas:

Ahora, vamos a entender cómo configurar y utilizar una función personalizada usando el servicio Invocar del Editor de reglas en AEM Forms 6.5

Usar una función personalizada en un formulario adaptable use-custom-functions

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:

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 utiliza la ventana de la consola para ver la respuesta tras hacer clic en el botón:

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

Objetos de campo hace 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.

Caso de uso: mostrar un panel con la regla SetProperty

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para establecer el campo del formulario 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});
       }
    }

En este ejemplo, la validación del panel personaldetails se produce al hacer clic en el botón. Si no se detectan errores en el panel, otro panel, el panel feedback, se vuelve visible al hacer clic en el botón.

Vamos a crear una regla para el botón Next, que valida el panel personaldetails y hace visible el panel feedback cuando el usuario hace clic en el botón Next.

Consulte la siguiente ilustración para demostrar dónde se valida el panel personaldetails al hacer clic en el botón Next. Si se validan todos los campos del personaldetails, el panel feedback se volverá visible.

Si hay errores en los campos del panel personaldetails, se mostrarán en el nivel de campo al hacer clic en el botón Next, y el panel feedback permanecerá invisible.

Caso de uso: valide el campo.

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para validar el campo.

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

        globals.functions.validate(field);

    }

En este ejemplo, se aplica un motivo de validación personalizado al campo contact. Los usuarios deben ingresar un número de teléfono que comience por 10 seguido de 8 dígitos. Si el usuario escribe un número de teléfono que no comienza con 10 o contiene más o menos de 8 dígitos, aparecerá un mensaje de error de validación al hacer clic en el botón:

Ahora, el siguiente paso es crear una regla para el botón Next que valide el campo contact al hacer clic en el botón.

Consulte la siguiente ilustración para demostrar que si el usuario escribe un número de teléfono que no comience por 10, aparece un mensaje de error en el nivel de campo:

Si el usuario escribe un número de teléfono válido y se validan todos los campos del panel personaldetails, aparecerá el panel feedback en la pantalla:

Caso de uso: Restablecer un panel

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para restablecer el panel.

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

        globals.functions.reset(field);

    }

En este ejemplo, el panel personaldetails se restablece al hacer clic en el botón Clear. El siguiente paso es crear una regla para el botón Clear que restablezca el panel al hacer clic en el botón.

Consulte la siguiente ilustración para mostrar que si el usuario hace clic en el botón clear, se restablece el panel personaldetails:

Caso de uso: para mostrar un mensaje personalizado en el nivel de campo y marcar el campo como no válido

Puede usar la función markFieldAsInvalid() para definir un campo como no válido y establecer un mensaje de error personalizado en el nivel de campo. El valor fieldIdentifier puede ser fieldId, field qualifiedName o field dataRef. El valor del objeto denominado option puede ser {useId: true}, {useQualifiedName: true} o {useDataRef: true}.
Las sintaxis utilizadas para marcar el campo como no válido y establecer mensajes personalizados son:

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para habilitar el mensaje personalizado en el nivel de 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 });
    }
}

En este ejemplo, si el usuario introduce menos de 15 caracteres en el cuadro de texto de comentarios, aparece un mensaje personalizado en el nivel de campo.

El siguiente paso es crear una regla para el campo comments:

Vea la demostración siguiente para mostrar que escribir comentarios negativos en el campo comments déclencheur la visualización de un mensaje personalizado en el nivel de campo:

Si el usuario introduce más de 15 caracteres en el cuadro de texto de comentarios, el campo se valida y se envía el formulario:

Caso de uso: enviar datos alterados al servidor

La siguiente línea de código:
globals.functions.submitForm(globals.functions.exportData(), false); se usa para enviar los datos del formulario después de la manipulación.

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para enviar los datos manipulados en el 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);
    }

En este ejemplo, si el usuario deja vacío el cuadro de texto comments, el NA se envía al servidor al enviar el formulario.

Ahora cree una regla para el botón Submit que envía datos:

Consulte la siguiente ilustración de console window para demostrar que si el usuario deja vacío el cuadro de texto de comments, el valor como NA se envía en el servidor:

También puede inspeccionar la ventana de la consola para ver los datos enviados al servidor:

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