Versión | Vínculo del artículo |
---|---|
AEM as a Cloud Service | Haga clic aquí |
AEM 6.5 | Este artículo |
AEM Forms proporciona controladores de éxito y de error predeterminados para los envíos de formularios. También proporciona una función para personalizar las funciones del controlador de errores. Por ejemplo, puede invocar un flujo de trabajo personalizado en el back-end para códigos de error específicos o informar al cliente de que el servicio está inactivo. Los controladores son funciones del lado del cliente que se ejecutan en función de la respuesta del servidor. Cuando se invoca un servicio externo mediante las API, los datos se transmiten al servidor para su validación, lo que devuelve una respuesta al cliente con información sobre el evento de éxito o error del envío. La información se pasa en forma de parámetros al controlador correspondiente para ejecutar la función. Un controlador de errores ayuda a administrar y mostrar los errores o problemas de validación encontrados.
El formulario adaptable valida las entradas proporcionadas en los campos en función de criterios de validación predefinidos y comprueba los distintos errores devueltos por el punto final REST configurado para invocar un servicio externo. Puede definir los criterios de validación en función de la fuente de datos que utilice con el formulario adaptable. Por ejemplo, si utiliza los servicios web RESTful como fuente de datos, puede definir los criterios de validación en un archivo de definición Swagger.
Si los valores de entrada cumplen los criterios de validación, los valores se envían al origen de datos; de lo contrario, el formulario adaptable muestra un mensaje de error utilizando un controlador de errores. De forma similar a este enfoque, los formularios adaptables se integran con los controladores de errores personalizados para realizar validaciones de datos. Si los valores de entrada no cumplen los criterios de validación, los mensajes de error se muestran a nivel de campo en el formulario adaptable. Esto ocurre cuando el mensaje de error de validación devuelto por el servidor tiene el formato de mensaje estándar.
Los controladores de errores se utilizan para varios fines. A continuación se enumeran algunos de los usos de las funciones del controlador de errores:
Realizar validación: la gestión de errores comienza con la validación de las entradas del usuario con reglas o criterios predefinidos. A medida que los usuarios rellenan un formulario adaptable, el controlador de errores valida la entrada para asegurarse de que cumple el formato, la longitud o cualquier otra restricción necesaria.
Proporcionar comentarios en tiempo real: cuando se detecta cualquier error, el controlador de errores muestra comentarios inmediatos al usuario, como mensajes de error en línea debajo de los campos de formulario correspondientes. Estos comentarios ayudan a los usuarios a identificar y corregir errores sin tener que enviar el formulario y esperar una respuesta.
Mostrar mensajes de error: cuando el envío de un formulario adaptable encuentra algún error de validación, el controlador de errores muestra un mensaje de error adecuado. Los mensajes de error deben ser claros, concisos y resaltar los campos específicos que requieren atención.
Resalta el campo erróneo: para llamar la atención del usuario sobre los campos incorrectos específicos, el controlador de errores resalta o diferencia visualmente los campos correspondientes. Se lleva a cabo cambiando el color de fondo, agregando un icono o borde, o cualquier otra señal visual que ayude a los usuarios a localizar rápidamente los errores y solucionarlos.
Un formulario adaptable muestra los errores en un nivel de campo si los mensajes de error de validación del servidor tienen el siguiente formato estándar.
El siguiente código ilustra la estructura de respuesta a errores existente:
{
errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
errors : [
{
errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
}
]
originCode : <target error Code>
originMessage : <unstructured error message returned by service>
}
Donde:
errorCausedBy
describe el motivo del error.errors
mencione el nombre de campo completo de los campos en los que se han producido errores en los criterios de validación junto con el mensaje de error de validación.originCode
añadido por AEM que contiene el código de estado HTTP devuelto por el servicio externo.originMessage
añadido por AEM que contiene los datos de error sin procesar devueltos por el servicio externo.Con las mejoras en las funciones y las actualizaciones posteriores en las versiones de AEM Forms, la estructura de respuesta a errores existente ha cambiado a un nuevo formato basado en RFC7807, que es compatible con versiones anteriores de la estructura de respuesta a errores existente:
{
"type": "SERVER_SIDE_VALIDATION/FORM_SUBMISSION/SERVICE_INVOCATION/FAILURE/VALIDATION_ERROR", (required)
"title": "Server side validation failed/Third party service invocation failed", (optional)
"detail": "", (optional)
"instance": "", (optional)
"validationErrors" : [ (required)
{
"fieldName":"<qualified fieldname of the field whose data sent is invalid>",
"dataRef":<JSONPath (or XPath) of the data element which is invalid>
"details": ["Error Message(s) for the field"] (required)
}
],
"originCode": <Origin http status code>, (optional - if there is SERVER_SIDE_VALIDATION)
"originMessage" : "<unstructured error message returned by service>" (optional - if there is SERVER_SIDE_VALIDATION)
}
Donde:
type (required)
especifica el tipo de error. Puede tener uno de los siguientes valores:
SERVER_SIDE_VALIDATION
indica un error debido a la validación del lado del servidor.FORM_SUBMISSION
indica un error durante el envío del formularioSERVICE_INVOCATION
indica un error durante una invocación de servicio de terceros.FAILURE
indica un error general.VALIDATION_ERROR
indica un error debido a un error de validación.title (optional)
proporciona un título o una breve descripción del error.
detail (optional)
proporciona detalles adicionales sobre el error si es necesario.
instance (optional)
representa una instancia o identificador asociado con el error y ayuda a rastrear o identificar la incidencia específica del error.
validationErrors (required)
contiene información sobre errores de validación. Incluye los siguientes campos:
fieldname
menciona el nombre de campo cualificado de los campos en los que se han producido errores en los criterios de validación.dataRef
representa la ruta JSON o XPath de los campos en los que se ha producido un error en la validación.details
contiene el mensaje de error de validación con el campo erróneo.El campo originCode (optional)
añadido por AEM contiene el código de estado HTTP devuelto por el servicio externo
El campo originMessage (optional)
añadido por AEM contiene los datos de error sin procesar devueltos por el servicio externo.
Algunas de las opciones para mostrar las respuestas de error son las siguientes:
Header:
content-type:application/problem+json
Response:
{
"type": "VALIDATION_ERROR",
"validationErrors": [
{
"fieldName": "$form.PetId",
"dataRef": "",
"details": [
"Invalid ID supplied. Provided value is not correct!"
]
}
]}
Header:
content-type:application/problem+json
Response:
{
"type": "VALIDATION_ERROR",
"validationErrors": [
{
"fieldName": "",
"dataRef": "$.Pet.id",
"details": [
"Invalid ID supplied. Provided value is not correct!"
]
}
]}
Antes de utilizar el controlador de error en un Forms adaptable:
Utilizando la acción del Servicio de invocación del editor de reglas, se definen los criterios de validación en función de la fuente de datos que se utilice con el formulario adaptable. Por ejemplo, si utiliza los servicios web RESTful como fuente de datos, puede definir los criterios de validación en un archivo de definición Swagger. Gracias a las funciones del controlador de errores y el editor de reglas en los formularios adaptables, se puede administrar y personalizar de forma eficaz la gestión de errores. Las condiciones se definen mediante el Editor de reglas y se configuran las acciones que deben realizarse cuando se activa la regla. Los formularios adaptables validan las entradas que se proporcionan en los campos en función de criterios de validación predefinidos. En caso de que los valores de entrada no cumplan los criterios de validación, los mensajes de error se muestran a nivel de campo en un formulario adaptable.
Con el editor de reglas, se puede hacer lo siguiente:
Se admite un controlador de errores predeterminado para mostrar los mensajes de error en los campos si la respuesta de error está en el esquema estándar o en un error de validación del lado del servidor.
Para comprender cómo utilizar un controlador de errores predeterminado con la acción Invocar servicio del editor de reglas, vamos a ver un ejemplo de formulario adaptable con dos campos, ID de mascota y Nombre de mascota. Además, usaremos un controlador de errores predeterminado en el campo ID de mascota para comprobar si hay varios errores devueltos por el punto final REST configurado para invocar un servicio externo, por ejemplo, 200 - OK
, 404 - Not Found
y 400 - Bad Request
. Para añadir un controlador de error predeterminado mediante la acción Invocar servicio del Editor de reglas, ejecute los siguientes pasos:
Como resultado de esta regla, los valores introducidos para ID de mascota comprueban la validación de Nombre de mascota utilizando el servicio externo invocado por el punto final REST. Si los criterios de validación basados en la fuente de datos fallan, los mensajes de error se muestran en el nivel de campo.
Puede añadir una función del controlador de errores personalizado para realizar algunas de las acciones como:
Además de las acciones mencionadas, los controladores de errores personalizados se pueden utilizar para ejecutar funciones personalizadas que cumplan con los requisitos específicos del usuario.
El controlador de errores personalizado es una función (Biblioteca de cliente) diseñada para responder a los errores devueltos por un servicio externo y proporcionar una respuesta personalizada a los usuarios finales. Cualquier biblioteca de cliente con anotación @errorHandler
se considera que es una función del controlador de errores personalizado. Esta anotación ayuda a identificar la función de controlador de error especificada en la variable .js
archivo.
Para comprender cómo crear y utilizar un controlador de errores personalizado con la acción Invocar servicio del editor de reglas, vamos a ver un ejemplo de formulario adaptable con dos campos, ID de mascota y Nombre de mascota. Además, usar un controlador de errores personalizado en el campo ID de mascota para comprobar si hay varios errores devueltos por el punto final REST configurado para invocar un servicio externo, por ejemplo, 200 - OK
, 404 - Not Found
y 400 - Bad Request
.
Para añadir y utilizar un controlador de errores personalizado en un formulario adaptable, realice los siguientes pasos:
Para crear una función de error personalizada, realice los siguientes pasos:
Iniciar sesión en http://server:port/crx/de/index.jsp#
.
Cree una carpeta dentro de la carpeta /apps
. Por ejemplo, cree una carpeta denominada como experience-league
.
Guarde los cambios.
Vaya a la carpeta creada y cree un nodo de tipo cq:ClientLibraryFolder
as clientlibs
.
Vaya al recién creado clientlibs
y añada la allowProxy
y categories
propiedades:
Puede proporcionar cualquier nombre en lugar de customfunctionsdemo
.
Guarde los cambios.
Cree una carpeta llamada js
en el clientlibs
carpeta.
Cree un archivo JavaScript llamado functions.js
en el js
carpeta
Cree un archivo llamado js.txt
en el clientlibs
carpeta.
Guarde los cambios.
La estructura de carpetas creada tiene este aspecto:
Haga doble clic en functions.js
para abrir el editor. El archivo contiene el código del controlador de errores personalizado.
Vamos a añadir el siguiente código al archivo JavaScript para mostrar la respuesta y los encabezados, recibidos del extremo del servicio REST, en la consola del explorador.
/**
Custom Error handler
* @name customErrorHandler Custom Error Handler Function
* @errorHandler
*/
function customErrorHandler(response, headers, globals)
{
console.log("Custom Error Handler processing start...");
console.log("response:"+JSON.stringify(response));
console.log("headers:"+JSON.stringify(headers));
alert("CustomErrorHandler - Please enter valid PetId.")
globals.invoke('defaultErrorHandler',response, headers)
console.log("Custom Error Handler processing end...");
}
Para llamar al controlador de error predeterminado desde el controlador de error personalizado, se utiliza la siguiente línea del código de ejemplo:
globals.invoke('defaultErrorHandler',response, headers)
Guardar function.js
.
Vaya a js.txt
y agregue el siguiente código:
#base=js
functions.js
Guarde el archivo js.txt
.
Ahora, vamos a comprender cómo configurar y utilizar un controlador de errores personalizado mediante el servicio Invocar del Editor de reglas de AEM Forms.
Antes de implementar el controlador de error personalizado en un formulario adaptable, asegúrese de que el nombre de la biblioteca de cliente en la Categoría de biblioteca del cliente corresponda con el nombre especificado en la opción de categorías del archivo .content.xml
.
En este caso, el nombre de la biblioteca del cliente se proporciona como customfunctionsdemo
en el archivo .content.xml
.
Para utilizar un controlador de errores personalizado utilizando la acción Invocar servicio del Editor de reglas:
Como resultado de esta regla, los valores introducidos para ID de mascota comprueban la validación de Nombre de mascota utilizando el servicio externo invocado por el punto final REST. Si los criterios de validación basados en la fuente de datos fallan, los mensajes de error se muestran en el nivel de campo.
Abra la consola del explorador y compruebe la respuesta y el encabezado, recibidos del punto final de servicio REST, para el mensaje de error de validación.
La función del controlador de errores personalizado es responsable de ejecutar acciones adicionales, como mostrar un cuadro de diálogo modal o enviar un evento de análisis, en función de la respuesta de error. Una función del controlador de errores personalizado proporciona la flexibilidad para adaptar la gestión de errores a los requisitos específicos del usuario.