Prácticas recomendadas para usar formularios adaptables best-practices-for-working-with-adaptive-forms

Usar Apache Maven aem-project-archetype para crear y administrar la estructura de proyectos de AEM. Crea plantillas y estructura recomendadas para el proyecto de AEM. Además, automatiza el procesamiento y cambia los sistemas de control para ayudar a administrar el proyecto.

• Utilice el comando de maven archetype:generate para generar la estructura inicial.
• Use el comando de maven eclipse:eclipse para generar los archivos del proyecto de Eclipse e importar el proyecto en Eclipse.

La herramienta FileVault o VLT le ayuda a asignar el contenido de una instancia CRX o AEM a su sistema de archivos. Proporciona operaciones de administración del control de cambios, como el registro y la salida del contenido del proyecto de AEM. Consulte Cómo utilizar la herramienta VLT.

Si utiliza el entorno de desarrollo integrado en Eclipse, puede utilizar herramientas de desarrollo de AEM para la integración perfecta de Eclipse IDE con instancias de AEM para crear aplicaciones de AEM. Para obtener más información, consulte Herramientas para desarrolladores de AEM para Eclipse.

No almacene ningún contenido ni realice ninguna modificación en la carpeta /libs. Cree superposiciones en carpetas /app para ampliar o sobrescribir las funcionalidades predeterminadas.

Cuando cree paquetes para mover contenido, asegúrese de que las rutas de filtro de paquetes sean correctas y solo se mencionen las rutas requeridas.

No almacene ningún contenido ni realice ninguna modificación en la carpeta /libs. Cree superposiciones en carpetas /app para ampliar o sobrescribir las funcionalidades predeterminadas.

Defina las dependencias correctas para que los paquetes obliguen mantener un orden o una secuencia de instalación predeterminados.

No cree ningún nodo referenciable en /libs o /apps.

Una plantilla de formulario adaptable es una página de AEM especializada que define la estructura y la información del encabezado y pie de página de un formulario adaptable. Una plantilla tiene diseños, estilos y estructuras básicos preconfigurados para un formulario adaptable. AEM Forms proporciona plantillas y componentes integrados que puede utilizar para crear formularios adaptables. Sin embargo, puede crear plantillas y componentes personalizados según sus necesidades. Se recomienda recopilar los requisitos para plantillas y componentes adicionales que necesite en los formularios adaptables. Para obtener más información, consulte Personalizar formularios y componentes adaptables.

Se recomienda cargar los paquetes de formularios mediante la interfaz de usuario de Form Manager en lugar de la interfaz de usuario de CRX Package Manager, ya que la carga de paquetes mediante CRX Package Manager a veces puede provocar anomalías.

AEM Forms permite crear formularios adaptables basados en los siguientes modelos de formulario. Los modelos de formulario actúan como interfaz para el intercambio de datos entre un formulario y el sistema de AEM y proporcionan una estructura basada en XML para el flujo de datos dentro y fuera de un formulario adaptable. Además, los modelos de formulario imponen reglas y restricciones en los formularios adaptables en forma de restricciones de esquema y XFA.

• Ninguno: los formularios adaptables creados con esta opción no utilizan ningún modelo de formulario. El XML de datos generado a partir de estos formularios tiene una estructura plana con campos y valores correspondientes.
• Esquema XML o JSON: los esquemas XML y JSON representan la estructura en la que el sistema back-end de su organización produce o consume los datos. Puede asociar el esquema a un formulario adaptable y utilizar sus elementos para agregarle contenido dinámico. Los elementos del esquema están disponibles en la pestaña Objeto del modelo de datos del explorador de contenidos para crear formularios adaptables. Puede arrastrar y soltar los elementos de esquema para crear el formulario.
• Plantilla de formulario XFA: es un modelo de formulario ideal si tiene inversiones en formularios HTML5 basados en XFA. Proporciona una forma directa de convertir los formularios basados en XFA en formularios adaptables. Cualquier regla XFA existente se conservará en el formulario adaptable asociado. El formulario adaptable resultante admitirá construcciones XFA, como validaciones, eventos, propiedades y patrones.
• Modelo de datos de formulario: es un modelo de formulario preferido si desea integrar sistemas backend como bases de datos, servicios web y perfiles de usuario de AEM para rellenar previamente formularios adaptables y escribir datos de formulario enviados de nuevo en los sistemas backend. Un editor del Modelo de datos de formulario permite definir y configurar entidades y servicios en un modelo de datos de formulario que se puede utilizar para crear formularios adaptables. Para obtener más información, consulte Integración de datos de AEM Forms.

AEM Forms proporciona plantillas de formulario adaptables integradas que puede utilizar para crear formularios adaptables. También puede crear sus propias plantillas. AEM proporciona plantillas estáticas y editables.

• Los desarrolladores definen y configuran las plantillas estáticas.
• Los autores crean plantillas editables mediante el editor de plantillas. El editor de plantillas permite definir una estructura básica y contenido inicial en una plantilla. Cualquier modificación en la capa de estructura se reflejará en todos los formularios que utilicen esa plantilla. El contenido inicial puede incluir una temática preconfigurada, un servicio de relleno previo, una acción de envío, etc. Sin embargo, esta configuración se puede modificar para un formulario con el editor de formularios. Para obtener más información, consulte Plantillas de formulario adaptables.

Para diseñar un campo o una instancia de panel específicos, utilice estilo dentro de la línea. Como alternativa, puede definir una clase en un archivo CSS y especificar su nombre en la propiedad Clase CSS del componente.

Incluya una biblioteca de cliente en un componente para aplicar estilos de forma coherente en todos los formularios adaptables o fragmentos que utilicen ese componente. Para obtener más información, consulte Crear un componente de página de formulario adaptable.

Aplique estilos definidos en una biblioteca de cliente para seleccionar formularios adaptables, para hacerlo, especifique la ruta a la biblioteca de cliente en el campo de ruta del archivo CSS en las propiedades del contenedor de formularios adaptables.

Para crear una biblioteca de cliente con sus estilos, puede configurar el archivo CSS personalizado en la base del Editor de temáticas clientlib o en las propiedades del contenedor de formularios.

Los formularios adaptables proporcionan diseños de panel, como capacidad de respuesta, pestañas, acordeones y asistente, para controlar cómo se distribuyen los componentes de formulario en un panel. Puede crear diseños de panel personalizados y ponerlos a disposición de los autores de formularios para utilizarlos. Para obtener más información, consulte Crear componentes de diseño personalizados para formularios adaptables.

También puede personalizar componentes de formulario adaptables específicos, como campos y diseño de panel.

• Utilice la funcionalidad de AEM Superposición para modificar una copia de un componente. No se recomienda modificar los componentes predeterminados.
• Para personalizar el diseño de los componentes de formulario adaptables listos para usar en /libs, cree componentes de diseño personalizados además de diseños predeterminados.
• Introduzca interactividades personalizadas mediante la creación de widgets o apariciones personalizados. No se recomienda modificar los componentes predeterminados. Para obtener más información, consulte Marco de trabajo de aspecto.

Consulte Administrar información personal para recomendaciones sobre la administración de datos PII.

Utilice el explorador de objetos de la barra lateral para acceder rápidamente a los campos situados en la parte inferior de la jerarquía del formulario. Puede utilizar el cuadro de búsqueda para buscar objetos en el árbol de objetos o formularios y navegar de un objeto a otro.

Para ver y editar las propiedades de un componente en el explorador de componentes de la barra lateral, seleccione el componente y haga clic en . También puede hacer doble clic en un componente para ver sus propiedades en el explorador de propiedades.

Utilice los métodos abreviados del teclado para realizar acciones rápidas en los formularios. Consulte Atajos de teclado de AEM Forms.

Se recomiendan los componentes de formulario adaptables para utilizarlos únicamente en páginas de formulario adaptables. Los componentes dependen de su jerarquía principal. Por lo tanto, no los utilice en una página de AEM.

Utilice nombres significativos y únicos para los campos y componentes de formulario para evitar posibles conflictos al escribir reglas.

Use el operador this para que un componente se haga referencia a sí mismo en una expresión de regla. Garantiza que la regla será válida incluso si cambia el nombre del componente. Por ejemplo, field1.valueCommit script: this.value > 10.

Utilice nombres de componentes cuando haga referencia a otros componentes del formulario. Utilice la propiedad value para recuperar el valor de un campo o componente. Por ejemplo, field1.value.

Consulte los componentes por jerarquía única relativa para evitar conflictos. Por ejemplo, parentName.fieldName.

Cuando administre reglas complejas o comúnmente utilizadas, considere la posibilidad de escribir lógica empresarial como funciones en una biblioteca de cliente independiente que puede especificar y reutilizar en formularios adaptables. La biblioteca de cliente debe ser una biblioteca independiente y no debe tener dependencias externas, excepto jQuery y Underscore.js. También puede utilizar la biblioteca de cliente para aplicar revalidación del lado del servidor de los datos de formulario enviados.

Los formularios adaptables proporcionan un conjunto de API que puede utilizar para comunicarse con los formularios adaptables y realizar acciones en ellos. Algunas de las API clave son las siguientes: Para obtener más información, consulte Referencia de la API de la biblioteca JavaScript para formularios adaptables.

• guideBridge.reset(): restablece un formulario.

• guideBridge.submit(): envía un formulario.

• guideBridge.setFocus(somExp, focusOption, runCompletionExp): define el enfoque en un campo.

• guideBridge.validate(errorList, somExpression, focus): valida un formulario.

• guideBridge.getDataXML(options): obtiene los datos del formulario como XML.

• guideBridge.resolveNode(somExpression): obtiene un objeto de formulario.

• guideBridge.setProperty(somList, propertyName, valueList): define la propiedad de un objeto de formulario.

• Además, puede utilizar las siguientes propiedades de campo:

  • field.value para cambiar el valor de un campo.
  • field.enabled para habilitar o deshabilitar un campo.
  • field.visible para cambiar la visibilidad de un campo.

Es posible que los autores de formularios adaptables tengan que escribir código JavaScript para crear lógica empresarial en un formulario. Aunque JavaScript es potente y eficaz, es probable que pueda comprometer las expectativas de seguridad. Por lo tanto, debe asegurarse de que el autor del formulario sea una persona de confianza y de que haya procesos para revisar y aprobar el código JavaScript antes de que se ponga en producción un formulario. El administrador puede restringir el acceso al editor de reglas a los grupos de usuarios en base a su rol o función. Consulte Conceder acceso al Editor de reglas a determinados grupos de usuarios..

Puede utilizar expresiones en reglas para hacer dinámicos los formularios adaptables. Todas las expresiones son expresiones JavaScript válidas y utilizan API de modelos de scripts de formularios adaptables. Estas expresiones devuelven valores de ciertos tipos. Para obtener más información sobre las expresiones y las prácticas recomendadas que las rodean, consulte Expresiones de formulario adaptables.

Adobe recomienda utilizar las operaciones sincrónicas de JavaScript sobre las asincrónicas al crear reglas con el editor de reglas. Se desaconseja el uso de operaciones asincrónicas. Sin embargo, si se encuentra en una situación en la que las operaciones asincrónicas son inevitables, es esencial implementar las funciones de Cierre de JavaScript. Al hacerlo, puede proteger de forma eficaz contra cualquier posible condición de carrera, lo que garantiza que las implementaciones de reglas ofrezcan un rendimiento óptimo y mantengan la estabilidad en todo.

Por ejemplo, supongamos que necesitamos recuperar datos de una API externa y luego aplicar algunas reglas basadas en esos datos. Utilizamos un cierre para gestionar la llamada asincrónica a la API y garantizar que las reglas se apliquen después de recuperar los datos. Este es un ejemplo de código:

     function fetchDataFromAPI(apiEndpoint, callback) {
      // Simulate asynchronous API call with setTimeout
      setTimeout(() => {
        // Assuming the API call is successful, we receive some data
        const data = {
          someValue: 42,
        };
        // Invoke the callback with the fetched data
        callback(data);
      }, 2000); // Simulate a 2-second delay for the API call
    }
    // Rule implementation using Closure
    function ruleImplementation(apiEndpoint) {
      // Using a closure to handle the asynchronous API call and rule application
      // say you have set this value in street field inside address panel
      var streetField = address.street;
      fetchDataFromAPI(apiEndpoint, (data) => {
        streetField.value = data.someValue;
      });
    }
    // Example usage of the rule implementation
    const apiEndpoint = "https://example-api.com/data";
    ruleImplementation(apiEndpoint);

En este ejemplo, fetchDataFromAPI simula una llamada de API asincrónica con setTimeout. Una vez recuperados los datos, invoca la función de llamada de retorno proporcionada, que es el cierre para administrar la aplicación de reglas posterior. La función ruleImplementation contiene la lógica de regla.

Se recomienda crear formularios adaptables mediante el modelo de datos de formulario XSD incluso cuando sea posible convertir un XFA a un formulario adaptable.

Incluir solo los campos y paneles en formularios adaptables que capturan información del usuario. Considere la posibilidad de mantener el contenido estático como mínimo o utilice direcciones URL para abrirlo en una ventana independiente.

Aunque cada formulario está diseñado para un propósito específico, hay algunos segmentos comunes en la mayoría de los formularios. Por ejemplo: detalles personales, dirección, detalles de empleo, etc. Cree fragmentos de formulario adaptables para elementos y secciones de formulario comunes y utilícelos en todos los formularios. También puede guardar un panel en un formulario existente como un fragmento. Cualquier cambio en un fragmento se reflejará en todos los formularios adaptables asociados. Promueve la creación colaborativa, ya que varios autores pueden trabajar simultáneamente en diferentes fragmentos que conforman un formulario.

• De forma similar a los formularios adaptables, se recomienda que todos los estilos específicos de fragmento y los scripts personalizados se definan en la biblioteca de cliente mediante el cuadro de diálogo contenedor de fragmentos. Además, intente crear fragmentos autosuficientes que no dependan de objetos externos.
• Evite utilizar scripts entre fragmentos. Si hay algún objeto fuera del fragmento al que deba hacer referencia, intente que dicho objeto forme parte del formulario principal. Si el objeto debe residir en otro fragmento, refiérase a él por su nombre en el script.

Utilice Guardar y reanudar con el guardado automático para guardar el formulario adaptable periódicamente y permitir que los usuarios vuelvan más tarde para completarlo.

Configure los fragmentos para que se carguen de forma diferida. Durante el tiempo de ejecución, los fragmentos marcados para cargarse de forma diferida solo se representarán cuando sean necesarios. Reduce significativamente el tiempo de carga de los formularios grandes. También se admite en fragmentos con paneles repetibles. Para obtener más información, consulte Configurar la carga diferida.

• No configure la carga diferida en fragmentos en un diseño de cuadrícula adaptable o en el primer panel.
• Los componentes Archivo adjunto y Términos y condiciones no son compatibles con los fragmentos cargados de forma diferida.
• Marque un valor en un panel cargado de forma diferida como Usar valor globalmente si ese valor se utiliza en alguna otra parte del formulario, de modo que el valor esté disponible para su uso cuando se descargue el panel que lo contiene.
• Considere la posibilidad de escribir reglas de visibilidad para aquellos fragmentos que deban mostrarse u ocultarse según una condición.

Establezca el valor del Número de llamadas por solicitud en el Servlet principal de Apache Sling a un número bastante grande. Permite al servidor de Forms permitir llamadas adicionales. La configuración muestra un valor predeterminado de 1500. El valor 1500 llamadas es para otros componentes de Experience Manager, como Sites y Recursos. El conjunto de valores predeterminado de los formularios adaptables es 20000. Si encuentra el error too many calls en los registros o si el formulario no se puede procesar, intente aumentar el valor a un número mayor para resolver el problema. Si el número de llamadas supera los 20 000, el formulario es complejo y puede tardar algún tiempo en procesarse en el explorador. Esto solo ocurrirá la primera vez que se cargue el formulario, después de que se almacene en la memoria caché. Una vez que el formulario se almacene en la memoria caché, el rendimiento no se verá afectado de forma significativa.

AEM Forms proporciona un servicio de rellenado previo para leer datos de un archivo XML de datos predefinido y rellenar previamente los campos de un formulario adaptable con el contenido del archivo XML.

El XML con datos de rellenado previo debe ser compatible con el esquema del modelo de formulario asociado al formulario adaptable.

IncluyaafBoundedData y secciones afUnBoundedData en el XML de rellenado previo para rellenar previamente los campos enlazados y no enlazados en un formulario adaptable.

Para los formularios adaptables basados en el modelo de datos de formulario, AEM Forms proporciona el servicio de rellenado previo del modelo de datos de formulario integrado. El servicio de relleno previo consulta las fuentes de datos de los objetos del modelo de datos en el formulario adaptable y rellena los valores de campo al procesar el formulario.

También puede utilizar los protocolos de archivo, crx, servicio o http para rellenar previamente los formularios adaptables.

AEM Forms admite servicios de relleno previo personalizados que se pueden insertar como servicio OSGi para rellenar previamente formularios adaptables.

Según el modelo de datos de formulario en el que se base un formulario adaptable, puede configurar una plantilla para el DoR de la siguiente manera:

• Plantilla de formulario XFA: utilice el archivo XDP asociado como plantilla del DoR.
• Esquema XSD: utilice la plantilla XFA asociada que utilice el mismo esquema XML utilizado por el formulario adaptable.
• Ninguno: utilice el DoR generado automáticamente.

Configure el encabezado, pie de página, imágenes, color, fuente, etc. a la derecha de la pestaña Documento de registro del editor de formularios adaptables.

Use DoRService para generar el DoR mediante programación.

Excluir los campos ocultos del documento de registro.

Use el parámetro de solicitud afAcceptLang para ver el DoR en otra configuración regional.

Utilice fragmentos de formulario adaptables para elementos comunes en todos los formularios y localice fragmentos. Garantiza que localice un fragmento una vez y se refleje en todos los formularios en los que se utilice el fragmento localizado.

Las modificaciones como agregar un componente nuevo o aplicar un script en un formulario localizado no se localizan automáticamente. Por lo tanto, debe finalizar un formulario antes de localizarlo para evitar varios ciclos de localización.

Use el parámetro de solicitudafAcceptLang para anular la configuración regional del explorador y procesar el formulario en la configuración regional especificada. Por ejemplo, la siguiente URL es forzada a procesar el formulario en la configuración regional japonesa, independientemente de la configuración regional especificada en la configuración del explorador:

https://'[server]:[port]'/<contextPath>/<formFolder>/<formName>.html?wcmmode=disabled&afAcceptLang=ja

AEM Forms admite actualmente la localización del contenido de los formularios adaptables en las configuraciones regionales de Inglés (en), Español (es), Francés (fr), Italiano (it), Alemán (de), Japonés (ja), Portugués brasileño (pt-BR), Chino (zh-CN), Chino taiwanés (zh-TW) y Coreano (ko-KR). Sin embargo, se puede agregar compatibilidad con nuevas configuraciones regionales para formularios adaptables en el tiempo de ejecución. Para obtener más información, consulte Compatibilidad con nuevas configuraciones regionales para la localización de formularios adaptables.

Habilitar la compresión de la biblioteca de cliente HTML para JavaScript y CSS desde la consola Felix.

Almacenar en la memoria caché todas las bibliotecas de cliente en /etc.clientlibs/fd y cualquier biblioteca de cliente personalizada adicional en AEM Dispatcher para aumentar la capacidad de respuesta y seguridad de los formularios publicados. Para obtener más información, consulte Dispatcher.

No almacenar en la memoria caché /content/forms/af/ y rutas/content/dam/formsanddocuments/*. para obtener información detallada sobre la configuración del almacenamiento en la memoria caché de formularios adaptables, consulte Almacenamiento en la memoria caché de formularios adaptables.

Habilitar el HTML mediante el módulo de compresión del servidor web. Para obtener más información, consulte Ajustar el rendimiento del servidor de AEM Forms.

Aumentar las llamadas por configuración de solicitud para formularios grandes. Consulte Optimizar el rendimiento de formularios grandes y complejos.

Crear páginas de error personalizadas mostradas por el administrador de errores.

Asegurar el servidor de AEM Forms.

• Usar el modo de ejecución nosamplecontent para asegurarse de que no haya contenido ni usuarios de muestra implementados en el servidor de producción. Consultar Ejecutar AEM en el modo Producción lista.

Mantener el tamaño de la pila a un mínimo de 8 GB. Para otras configuraciones, consulte Ajustar el rendimiento del servidor de AEM Forms.

Utilice sesiones de usuario de servicio en lugar de sesiones de administración para ejecutar tareas de nivel de servicio. Para obtener más información, consulte Autenticar el servicio.

Almacenar datos de borrador: si utiliza la función Borrador de los formularios adaptables, debe implementar una interfaz de proveedor de servicios (SPI) personalizada para almacenar los datos en modo de borrador en un almacenamiento más seguro, como la base de datos. Para obtener más información, consulte Ejemplo para integrar el componente Borradores y envíos con la base de datos.

Almacenar datos de envío: si utiliza el repositorio de envío del portal de formularios, debe implementar un SPI personalizado para almacenar los datos de envío en una base de datos. Consulte Ejemplo para integrar el componente Borradores y envíos con la base de datos para una integración de ejemplo.

También puede escribir una acción de envío personalizada que almacene datos de formulario y los datos adjuntos en un almacenamiento seguro. Consulte Escribir una acción de envío personalizada para formularios adaptables para obtener más información.

Longitud del ID del borrador: al guardar un formulario adaptable como borrador, se genera un ID de borrador para identificar el borrador de forma exclusiva. El valor mínimo de la longitud del campo de ID de borrador es de 26 caracteres. Adobe recomienda establecer la longitud de ID de borrador en 26 caracteres o más.

Use sin problemas el control de versiones como Git:

• El aislamiento del código del contenido reduce significativamente los conflictos de Git durante la administración de contenido y promueve un repositorio bien organizado.
• Funciones personalizadas es útil para proyectos con varios colaboradores que trabajan simultáneamente.

Beneficios técnicos:

• Las funciones personalizadas ofrecen modularidad y encapsulación.
• Los módulos se pueden desarrollar, probar y mantener de forma independiente.
• Mejora la reutilización y el mantenimiento del código.

Proceso de desarrollo eficiente:

• La modularidad permite a los desarrolladores centrarse en funcionalidades específicas.
• Reduce la carga de los desarrolladores al reducir las complejidades de todo el código base para un proceso de desarrollo más eficiente.