Crear aspectos personalizados para campos de formulario adaptables

Introducción

Los formularios adaptables aprovechan la estructura de aspecto para ayudarle a crear aspectos personalizados para los campos de formulario adaptables y proporcionar una experiencia de usuario diferente. Por ejemplo, reemplace los botones de opción y las casillas de verificación con botones de alternancia o utilice complementos jQuery personalizados para restringir las entradas de los usuarios en campos como números de teléfono o ID de correo electrónico.

En este documento se explica cómo utilizar un complemento jQuery para crear estas experiencias alternativas para campos de formulario adaptables. Además, muestra un ejemplo para crear un aspecto personalizado para que el componente de campo numérico aparezca como un paso numérico o un control deslizante.

Veamos primero los términos y conceptos clave utilizados en este artículo.

​AspectoSe refiere al estilo, el aspecto y la organización de varios elementos de un campo de formulario adaptable. Normalmente incluye una etiqueta, un área interactiva para proporcionar entradas, un icono de ayuda y descripciones cortas y largas del campo. La personalización del aspecto que se describe en este artículo es aplicable al aspecto del área de entrada del campo.

Complemento jQueryProporciona un mecanismo estándar, basado en el marco del widget jQuery, para implementar un aspecto alternativo.

​Sistema de bibliotecas clienteLibA del lado del cliente en AEM procesamiento del lado del cliente impulsado por complejos códigos JavaScript y CSS. Para obtener más información, consulte Uso de bibliotecas del lado del cliente.

​Tipo de archivoKit de herramientas de creación de plantillas de proyecto de Maven definido como un patrón o modelo original para los proyectos de Maven. Para obtener más información, consulte Introducción a los tipos de archivo.

Control de usuarioSe refiere al elemento principal de una utilidad que contiene el valor del campo y el marco de trabajo de aspecto lo utiliza para enlazar la interfaz de usuario de la utilidad personalizada con el modelo de formulario adaptable.

Pasos para crear un aspecto personalizado

Los pasos, en un nivel superior, para crear un aspecto personalizado son los siguientes:

  1. Crear un proyecto: Cree un proyecto de Maven que genere un paquete de contenido para implementarlo en AEM.

  2. Ampliar una clase de utilidad existente: Amplíe una clase de widget existente y anule las clases requeridas.

  3. Crear una biblioteca de cliente: Cree una clientLib: af.customwidget biblioteca y añada los archivos JavaScript y CSS necesarios.

  4. Cree e instale el proyecto: Cree el proyecto Maven e instale el paquete de contenido generado en AEM.

  5. Actualice el formulario adaptable: Actualice las propiedades del campo del formulario adaptable para utilizar el aspecto personalizado.

Crear un proyecto

Un tipo de archivo maven es un punto de partida para crear un aspecto personalizado. Los detalles del tipo de archivo a utilizar son los siguientes:

  • Repositorio: https://repo1.maven.org/maven2/com/adobe/
  • Id de artefacto: custom-appearance-archetype
  • Id De Grupo: com.adobe.aemforms
  • Versión: 1.0.4

Ejecute el siguiente comando para crear un proyecto local basado en el tipo de archivo:

mvn archetype:generate -DarchetypeRepository=https://repo1.maven.org/maven2/com/adobe/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

El comando descarga los complementos de Maven y la información del tipo de archivo desde el repositorio y genera un proyecto basado en la siguiente información:

  • groupId: ID de grupo utilizado por el proyecto Maven generado
  • artifactId: ID de artefacto utilizado por el proyecto Maven generado.
  • versión: Versión del proyecto Maven generado.
  • paquete: Paquete utilizado para la estructura de archivos.
  • artifactName: Nombre del artefacto del paquete de AEM generado.
  • packageGroup: Grupo de paquetes del paquete de AEM generado.
  • Nombre de la utilidad: Nombre de aspecto que se utiliza como referencia.

El proyecto generado tiene la siguiente estructura:

─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

Ampliar una clase de utilidad existente

Una vez creada la plantilla del proyecto, realice los cambios siguientes según sea necesario:

  1. Incluya la dependencia del complemento de terceros al proyecto.

    1. Coloque los complementos de jQuery personalizados o de terceros en la carpeta jqueryplugin/javascript y los archivos CSS relacionados en la carpeta jqueryplugin/css . Para obtener más información, consulte los archivos JS y CSS en la carpeta jqueryplugin/javascript and jqueryplugin/css .

    2. Modifique los archivos js.txt y css.txt para incluir cualquier archivo JavaScript y CSS adicional del complemento jQuery.

  2. Integre el complemento de terceros con el marco para permitir la interacción entre el marco de aspecto personalizado y el complemento jQuery. El nuevo widget solo funcionará después de ampliar o anular las siguientes funciones.

Función Descripción
render La función render devuelve el objeto jQuery para el elemento HTML predeterminado del widget. El elemento HTML predeterminado debe ser de tipo enfocable. Por ejemplo, <a>, <input> y <li>. El elemento devuelto se usa como $userControl. Si $userControl especifica la restricción anterior, las funciones de la clase AbstractWidget funcionan como se espera, de lo contrario, algunas de las API comunes (enfoque, clic) requieren cambios.
getEventMap Devuelve un mapa para convertir eventos de HTML en eventos XFA.
{ blur: XFA_EXIT_EVENT, }
Este ejemplo muestra que blur es un evento de HTML y XFA_EXIT_EVENT es el evento XFA correspondiente.
getOptionsMap Devuelve un mapa que proporciona detalles sobre la acción que se va a realizar al cambiar una opción. Las claves son las opciones que se proporcionan al widget y los valores son funciones a las que se llama cada vez que se detecta un cambio en la opción. La utilidad proporciona controladores para todas las opciones comunes (excepto value y displayValue).
getCommitValue El marco del widget jQuery carga la función siempre que el valor del widget jQuery se guarda en el modelo XFA (por ejemplo, en el suceso exit de un campo de texto). La implementación debe devolver el valor guardado en el widget. El controlador se proporciona con el nuevo valor para la opción .
showValue De forma predeterminada, en XFA en el suceso enter , se muestra el rawValue del campo. Se llama a esta función para mostrar el rawValue al usuario.
showDisplayValue De forma predeterminada, en XFA en el evento exit , se muestra el formattedValue del campo . Se llama a esta función para mostrar el formattedValue al usuario.
  1. Actualice el archivo JavaScript en la carpeta integration/javascript según sea necesario.

    • Reemplace el texto __widgetName__ por el nombre real del widget.

    • Amplíe el widget desde una clase de utilidad predeterminada adecuada. En la mayoría de los casos, es la clase de utilidad correspondiente al widget existente que se está reemplazando. El nombre de clase principal se utiliza en varias ubicaciones, por lo que se recomienda buscar todas las instancias de la cadena xfaWidget.textField en el archivo y sustituirlas por la clase principal real utilizada.

    • Amplíe el método render para proporcionar una interfaz de usuario alternativa. Es la ubicación desde la que se invocará el complemento jQuery para actualizar la interfaz de usuario o el comportamiento de la interacción. El método render debe devolver un elemento de control de usuario.

    • Amplíe el método getOptionsMap para anular cualquier configuración de opción afectada debido a un cambio en el widget. La función devuelve una asignación que proporciona detalles para que la acción se realice al cambiar una opción. Las claves son las opciones proporcionadas al widget y los valores son las funciones a las que se llama cada vez que se detecta un cambio en la opción.

    • El método getEventMap asigna los eventos activados por el widget, con los eventos requeridos por el modelo de formulario adaptable. El valor predeterminado asigna eventos de HTML estándar para el widget predeterminado y debe actualizarse si se activa un evento alternativo.

    • Los showDisplayValue y showValue aplican la cláusula de visualización y edición de imagen y se pueden sobrescribir para tener un comportamiento alternativo.

    • El marco de formularios adaptables llama al método getCommitValue cuando se produce el evento commit. Generalmente, es el evento de salida, excepto para los elementos de lista desplegable, botón de radio y casilla de verificación donde se produce al cambiar). Para obtener más información, consulte expresiones adaptables de Forms.

    • El archivo de plantilla proporciona implementación de muestra para varios métodos. Elimine los métodos que no se van a ampliar.

Crear una biblioteca de cliente

El proyecto de ejemplo generado por el tipo de archivo Maven crea automáticamente las bibliotecas de cliente necesarias y las envuelve en una biblioteca de cliente con una categoría af.customwidgets. Los archivos JavaScript y CSS disponibles en af.customwidgets se incluyen automáticamente en el tiempo de ejecución.

Generar e instalar

Para crear el proyecto, ejecute el siguiente comando en el shell para generar un paquete CRX que necesite ser instalado en el servidor de AEM.

mvn clean install

NOTA

El proyecto maven hace referencia a un repositorio remoto dentro del archivo POM. Esto es solo para fines de referencia y según los estándares de Maven, la información del repositorio se captura en el archivo settings.xml.

Actualizar el formulario adaptable

Para aplicar el aspecto personalizado a un campo de formulario adaptable:

  1. Abra el formulario adaptable en modo de edición.
  2. Abra el cuadro de diálogo Propiedad para el campo en el que desea aplicar el aspecto personalizado.
  3. En la pestaña Styling, actualice la propiedad CSS class para añadir el nombre del aspecto en el formato widget_<widgetName>. Por ejemplo: widget_numericstep

Ejemplo: Crear un aspecto personalizado  

Veamos un ejemplo para crear un aspecto personalizado para que un campo numérico aparezca como un paso numérico o un control deslizante. Siga estos pasos:

  1. Ejecute el siguiente comando para crear un proyecto local basado en el tipo de archivo Maven:

    mvn archetype:generate -DarchetypeRepository=https://repo1.maven.org/maven2/com/adobe/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

    Le solicita que especifique valores para los siguientes parámetros.
    Los valores utilizados en esta muestra se resaltan en negrita.

    Define value for property 'groupId': com.adobe.afwidgets

    Define value for property 'artifactId': customWidgets

    Define value for property 'version': 1.0.1-SNAPSHOT

    Define value for property 'package': com.adobe.afwidgets

    Define value for property 'artifactName': customWidgets

    Define value for property 'packageGroup': adobe/customWidgets

    Define value for property 'widgetName': numericStepper

  2. Vaya al directorio customWidgets (valor especificado para la propiedad artifactID ) y ejecute el siguiente comando para generar un proyecto de Eclipse:

    mvn eclipse:eclipse

  3. Abra la herramienta Eclipse y haga lo siguiente para importar el proyecto Eclipse:

    1. Seleccione Archivo > Importar > Proyectos existentes en Workspace.

    2. Busque y seleccione la carpeta en la que ejecutó el comando archetype:generate.

    3. Haga clic en Finish.

      captura de pantalla de eclipse

  4. Seleccione el widget que se utilizará para el aspecto personalizado. Este ejemplo utiliza el siguiente widget de pasos numéricos:

    https://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html

    En el proyecto Eclipse, revise el código del complemento en el archivo plugin.js para asegurarse de que coincida con los requisitos del aspecto. En este ejemplo, el aspecto visual cumple los siguientes requisitos:

    • El paso numérico debe extenderse desde - $.xfaWidget.numericInput.

    • El método set value del widget define el valor después de que el foco esté en el campo. Es un requisito obligatorio para un widget de formulario adaptable.

    • Se debe sobrescribir el método render para invocar el método bootstrapNumber.

    • No hay dependencia adicional para el complemento que no sea el código fuente principal del complemento.

    • El ejemplo no realiza ningún estilo en el paso, por lo que no se requiere CSS adicional.

    • El objeto $userControl debe estar disponible para el método render. Es un campo del tipo text que se clona con el código del complemento.

    • Los botones + y - deben desactivarse cuando el campo esté desactivado.

  5. Reemplace el contenido del bootstrap-number-input.js (complemento jQuery) con el contenido del archivo numericStepper-plugin.js.

  6. En el archivo numericStepper-widget.js, añada el siguiente código para anular el método de renderización y invocar el complemento y devolver el objeto $userControl:

    render : function() {
         var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
         var $control = $(control);
         var controlObject;
         try{
             if($control){
             $control.bootstrapNumber();
             var id = $control.attr("id");
             controlObject = $("#"+id);
             }
         }catch (exc){
              console.log(exc);
         }
         return controlObject;
    }
    
  7. En el archivo numericStepper-widget.js, anule la propiedad getOptionsMap para anular la opción de acceso y oculte los botones + y - en modo desactivado.

    getOptionsMap: function(){
        var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),
    
        newMap = $.extend({},parentOptionsMap,
    
         {
    
               "access": function(val) {
               switch(val) {
                  case "open" :
                    this.$userControl.removeAttr("readOnly");
                    this.$userControl.removeAttr("aria-readonly");
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
                  case "nonInteractive" :
                  case "protected" :
                    this.$userControl.attr("disabled", "disabled");
                    this.$userControl.attr("aria-disabled", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                 case "readOnly" :
                    this.$userControl.attr("readOnly", "readOnly");
                    this.$userControl.attr("aria-readonly", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                default :
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
              }
           },
       });
       return newMap;
     }
    
  8. Guarde los cambios, vaya a la carpeta que contiene el archivo pom.xml y ejecute el siguiente comando Maven para crear el proyecto:

    mvn clean install

  9. Instale el paquete mediante AEM Administrador de paquetes.

  10. Abra el formulario adaptable en modo de edición en el que desee aplicar el aspecto personalizado y haga lo siguiente:

    1. Haga clic con el botón derecho en el campo en el que desee aplicar el aspecto y haga clic en Editar para abrir el cuadro de diálogo Editar componente.

    2. En la pestaña Estilo , actualice la propiedad CSS class para añadir widget_numericStepper.

La nueva apariencia que acaba de crear ya está disponible para su uso.

En esta página