Ejemplos de desarrollo y uso de funciones personalizadas

El artículo proporciona ejemplos detallados de funciones personalizadas para un formulario adaptable basadas en componentes principales, lo que ofrece información valiosa sobre su implementación eficaz en varios escenarios. Las funciones personalizadas se utilizan en el editor de reglas de una AEM Forms, lo que permite a los desarrolladores definir y controlar la lógica que rige el comportamiento del formulario.
Este artículo explora diferentes implementaciones de funciones personalizadas, mostrando cómo se pueden utilizar para adaptar los formularios para satisfacer requisitos específicos y mejorar la funcionalidad general.

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.

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para establecer las opciones de la lista desplegable mediante 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:

Mostrar un panel utilizando la regla SetProperty

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

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.

Validación del campo

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para validar el campo con la ayuda de un formulario Contact Us.

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:

Restablecer un panel

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para restablecer el campo con la ayuda de un formulario Contact Us.

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:

Para mostrar un mensaje personalizado en el nivel de campo y marcar el campo como no válido

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para mostrar un mensaje personalizado en el nivel de campo y marcar el campo como no válido con la ayuda de un formulario Contact Us.

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 un campo como no válido y establecer un mensaje personalizado son:

Agregue el siguiente código en la función personalizada como se explica en la sección create-custom-function para habilitar un 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:

Enviar datos modificados al servidor

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para enviar datos manipulados en el servidor con la ayuda de un formulario Contact Us.

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

Anular los controladores de éxito y de error del envío del formulario

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para anular los controladores de envío con la ayuda de un formulario Contact Us.

Agregue la siguiente línea de código, tal como se explica en la sección create-custom-function, para personalizar el envío o el mensaje de error para los envíos de formularios y mostrar los mensajes de envío de formularios en un cuadro modal:

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

En este ejemplo, cuando el usuario utiliza las funciones personalizadas customSubmitSuccessHandler y customSubmitErrorHandler, los mensajes de éxito y error se muestran en un modal. La función de JavaScript showModal(type, message) se usa para crear y mostrar dinámicamente un cuadro de diálogo modal en una pantalla.

Ahora, cree una regla para el envío correcto de formularios:

Consulte la siguiente ilustración para demostrar que, cuando el formulario se envía correctamente, el mensaje de éxito se muestra en un modal:

Del mismo modo, vamos a crear una regla para los envíos de formularios fallidos:

Consulte la siguiente ilustración para demostrar que, cuando falla el envío del formulario, el mensaje de error se muestra en un modal:

Para mostrar el éxito y el error del envío del formulario de forma predeterminada, las funciones Default submit Form Success Handler y Default submit Form Error Handler están disponibles de forma predeterminada.

AEM En caso de que el controlador de envío personalizado no funcione según lo esperado en los formularios o proyectos existentes de la aplicación, consulte la sección solución de problemas.

Realizar acciones en una instancia específica del panel repetible

Las reglas creadas con el editor de reglas visuales en un panel repetible se aplican a la última instancia del panel repetible. Para escribir una regla para una instancia específica del panel repetible, podemos utilizar una función personalizada.

Vamos a crear otro formulario como Booking Form para recopilar información sobre los viajeros que se dirigen a un destino. Un panel de viajeros se agrega como un panel repetible, donde el usuario puede agregar detalles para 5 viajeros con el botón Add Traveler.

Agregue la siguiente línea de código como se explica en la sección create-custom-function para realizar acciones en una instancia específica del panel repetible que no sea la última:

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

En este ejemplo, la función personalizada hidePanelInRepeatablePanel realiza una acción en una instancia específica del panel repetible. En el código anterior, travelerinfo representa el panel repetible. El código repeatablePanel[1].traveler, {visible: false} oculta el panel en la segunda instancia del panel repetible.

Vamos a agregar un botón denominado Hide y agregar una regla para ocultar la segunda instancia de un panel repetible.

Consulte el siguiente vídeo para demostrar que, cuando se hace clic en Hide, se oculta el panel de la segunda instancia repetible:

Rellene previamente el campo con un valor cuando se cargue el formulario

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para rellenar previamente el campo con la ayuda de Booking Form.

Agregue la siguiente línea de código, tal como se explica en la sección create-custom-function, para cargar el valor rellenado previamente en un campo cuando se inicialice el formulario:

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

En el código mencionado, la función testImportData rellena previamente el campo de cuadro de texto Booking Amount cuando se carga el formulario. Supongamos que el formulario de reserva requiere que la cantidad mínima de reserva sea de 10,000.

Vamos a crear una regla en la inicialización del formulario, donde el valor del campo Booking Amount textbox se rellena previamente con un valor especificado cuando se carga el formulario:

Consulte la captura de pantalla siguiente, que muestra que cuando se carga el formulario, el valor del cuadro de texto Booking Amount está rellenado previamente con un valor especificado:

Establecer el enfoque en un campo específico

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para establecer el enfoque en un campo específico con la ayuda de Booking Form.

Agregue la línea de código siguiente, tal como se explica en la sección create-custom-function, para establecer el enfoque en el campo especificado cuando se haga clic en el botón Submit.:

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

Vamos a agregar una regla al botón Submit para establecer el enfoque en el campo de cuadro de texto Email ID cuando se hace clic:

Consulte la captura de pantalla siguiente, que muestra que cuando se hace clic en el botón Submit, el enfoque se establece en el campo Email ID:

Agregar o eliminar el panel repetible con la propiedad dispatchEvent

Vamos a aprender cómo las funciones personalizadas utilizan los objetos globales y de campo para agregar o eliminar paneles repetibles mediante la propiedad dispatchEvent con la ayuda de Booking Form.

Agregue la línea de código siguiente, tal como se explica en la sección create-custom-function, para agregar un panel cuando se haga clic en el botón Add Traveler mediante la propiedad dispatchEvent:

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

Vamos a agregar una regla al botón Add Traveler para agregar el panel repetible cuando se hace clic:

Consulte el archivo gif siguiente, que muestra que cuando se hace clic en el botón Add Traveler, el panel se agrega mediante la propiedad dispatchEvent:

Del mismo modo, agregue la siguiente línea de código, tal como se explica en la sección create-custom-function, para eliminar un panel cuando se haga clic en el botón Delete Traveler mediante la propiedad dispatchEvent:

/**

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

Vamos a agregar una regla al botón Delete Traveler para eliminar el panel repetible cuando se hace clic:

Consulte el archivo gif siguiente, que muestra que cuando se hace clic en el botón Delete Traveler, el panel del viajero se elimina utilizando la propiedad dispatchEvent:

Resolución de problemas

Consulte también