Show Menu
TEMAS×

Creación de apariencias personalizadas para campos de formulario adaptables

Introducción

Los formularios adaptables aprovechan el marco de apariencia para ayudarle a crear apariencias personalizadas para los campos de formulario adaptables y ofrecer una experiencia de usuario diferente. Por ejemplo, reemplace los botones de radio y las casillas de verificación con botones de alternar 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 escalón numérico o un deslizador.
Analicemos primero los términos y conceptos clave utilizados en este artículo.
Aspecto Se 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 jQuery Proporciona un mecanismo estándar, basado en el marco de utilidades jQuery, para implementar un aspecto alternativo.
ClientLib Un sistema de bibliotecas del lado del cliente en el procesamiento del lado del cliente de AEM impulsado por código JavaScript y CSS complejo. Para obtener más información, consulte Uso de bibliotecas del lado del cliente.
Archetype Juego de herramientas de plantilla de proyecto Maven definido como un patrón o modelo original para proyectos Maven. Para obtener más información, consulte Introducción a los arquetipos.
Control de usuario Se refiere al elemento principal de una utilidad que contiene el valor del campo y se utiliza en la estructura de aspecto para enlazar la interfaz de usuario de la utilidad personalizada con el modelo de formulario adaptable.

Pasos para crear un aspecto personalizado

Los pasos para crear un aspecto personalizado de alto nivel 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 agregue los archivos JavaScript y CSS necesarios.
  4. Cree e instale el proyecto : Cree el proyecto de Maven e instale el paquete de contenido generado en AEM.
  5. Actualizar el formulario adaptable: Actualice las propiedades del campo de formulario adaptable para utilizar el aspecto personalizado.

Creación de un proyecto

Un arquetipo determinado es un punto de partida para crear un aspecto personalizado. Los detalles del arquetipo a utilizar son los siguientes:
  • Repositorio : https://repo.adobe.com/nexus/content/groups/public/
  • 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 arquetipo:
mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
El comando descarga los complementos de Maven y la información de arquetipo del repositorio, y genera un proyecto basado en la siguiente información:
  • groupId : ID de grupo utilizado por el proyecto Maven generado
  • artiactId : 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.
  • artiactName : Nombre de artefacto del paquete AEM generado.
  • packageGroup : Grupo de paquetes del paquete AEM generado.
  • widgetName : Nombre de aspecto utilizado 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

Ampliación de una clase de utilidad existente

Una vez creada la plantilla de proyecto, realice los siguientes cambios, según sea necesario:
  1. Incluya la dependencia del complemento de terceros en el proyecto.
    1. Coloque los complementos de jQuery personalizados o de terceros en la jqueryplugin/javascript carpeta y los archivos CSS relacionados en la jqueryplugin/css carpeta. Para obtener más información, consulte los archivos JS y CSS de la jqueryplugin/javascript and jqueryplugin/css carpeta.
    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 la estructura para habilitar la interacción entre la estructura de aspecto personalizada y el complemento jQuery. La nueva utilidad solo funcionará después de ampliar o anular las siguientes funciones.
Función Descripción
render La función de procesamiento devuelve el objeto jQuery para el elemento HTML predeterminado del widget. El elemento HTML predeterminado debe ser de tipo seleccionable. Por ejemplo, <a> , <input> y <li> . El elemento devuelto se usa como $userControl . Si la restricción $userControl especifica la anterior, las funciones de la AbstractWidget clase funcionan según lo esperado, de lo contrario, algunas de las API comunes (enfoque, clic) requieren cambios.
getEventMap Devuelve un mapa para convertir eventos HTML en eventos XFA. { blur: XFA_EXIT_EVENT, } Este ejemplo muestra que blur es un evento HTML y XFA_EXIT_EVENT es el evento XFA correspondiente.
getOptionsMap Devuelve un mapa que proporciona detalles sobre la acción que se debe 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 La estructura de la utilidad jQuery carga la función cada vez que se guarda el valor de la utilidad jQuery en el modelo XFA (por ejemplo, en el suceso exit de un campo de texto). La implementación debe devolver el valor guardado en la utilidad. El controlador se proporciona con el nuevo valor para la opción.
showValue De forma predeterminada, en XFA cuando se produce el suceso enter, se muestra el nombre rawValue del campo. Se llama a esta función para mostrar al usuario rawValue .
showDisplayValue De forma predeterminada, en XFA cuando se produce un evento exit, se muestra el nombre formattedValue del campo. Se llama a esta función para mostrar al usuario formattedValue .
  1. Actualice el archivo JavaScript de la integration/javascript carpeta según sea necesario.
    • Reemplace el texto __widgetName__ con el nombre real del widget.
    • Extienda la utilidad desde una clase de utilidad lista para usar adecuada. En la mayoría de los casos, es la clase de widget que corresponde 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 reemplazarlas por la clase principal real utilizada.
    • Amplíe el render método para proporcionar una IU 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 render método debe devolver un elemento de control de usuario.
    • Amplíe el getOptionsMap método para anular cualquier opción que se vea afectada por un cambio en la utilidad. La función devuelve una asignación que proporciona detalles para la acción que se realizará 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 getEventMap método asigna eventos activados por la utilidad, con los eventos requeridos por el modelo de formulario adaptable. El valor predeterminado asigna eventos HTML estándar para la utilidad predeterminada y debe actualizarse si se activa un evento alternativo.
    • La cláusula de visualización showDisplayValue showValue y aplicación de la cláusula de visualización y edición de imagen y se puede anular para tener un comportamiento alternativo.
    • El marco de formularios adaptables llama al getCommitValue método cuando se produce el commit suceso. Generalmente, es el evento exit, 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 de formularios adaptables.
    • El archivo de plantilla proporciona implementación de muestra para varios métodos. Elimine los métodos que no se van a ampliar.

Creación de una biblioteca de cliente

El proyecto de muestra generado por el arquetipo 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 el af.customwidgets se incluyen automáticamente durante la ejecución.

Generar e instalar

Para crear el proyecto, ejecute el siguiente comando en el shell para generar un paquete CRX que debe instalarse en el servidor AEM.
mvn clean install
El proyecto principal hace referencia a un repositorio remoto dentro del archivo POM. Esto es sólo con fines de referencia y, según los estándares Maven, la información del repositorio se captura en el settings.xml archivo.

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 del campo en el que desea aplicar el aspecto personalizado.
  3. En la ficha Estilo , actualice la propiedad CSS class para agregar el nombre de aspecto en el widget_<widgetName> formato. Por ejemplo: widget_numericstep

Ejemplo: Crear un aspecto personalizado

Veamos ahora un ejemplo para crear un aspecto personalizado para que un campo numérico aparezca como un paso numérico o un deslizador. Siga estos pasos:
  1. Ejecute el siguiente comando para crear un proyecto local basado en el arquetipo Maven:
    mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
    Le solicita que especifique valores para los parámetros siguientes. 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 artifactID propiedad) y ejecute el siguiente comando para generar un proyecto 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 archetype:generate comando.
    3. Click Finish .
  4. Seleccione la utilidad que se utilizará para la apariencia personalizada. En este ejemplo se utiliza el siguiente widget numérico de pasos:
    En el proyecto Eclipse, revise el código del complemento en el plugin.js archivo para asegurarse de que coincide con los requisitos del aspecto. En este ejemplo, la apariencia cumple los siguientes requisitos:
    • El paso numérico debería extenderse desde - $.xfaWidget.numericInput .
    • El set value método de la utilidad establece el valor después de que el enfoque esté en el campo. Es un requisito obligatorio para un widget de formulario adaptable.
    • El render método debe sobrescribirse para invocar el bootstrapNumber método.
    • 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 componente, por lo que no se requiere CSS adicional.
    • El $userControl objeto debe estar disponible para el render método. Es un campo del text tipo 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 numericStepper-plugin.js archivo.
  6. En el numericStepper-widget.js archivo, agregue el siguiente código para anular el método de procesamiento para invocar el complemento y devolver el $userControl objeto:
    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 numericStepper-widget.js archivo, anule la getOptionsMap propiedad 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 pom.xml archivo y ejecute el siguiente comando Maven para crear el proyecto:
    mvn clean install
  9. Instale el paquete mediante el Administrador de paquetes de AEM.
  10. Abra el formulario adaptable en modo de edición en el que desea aplicar el aspecto personalizado y haga lo siguiente:
    1. Haga clic con el botón secundario en el campo en el que desea aplicar el aspecto y haga clic en Editar para abrir el cuadro de diálogo Editar componente.
    2. En la ficha Estilo, actualice la propiedad de clase ​CSS para agregar widget_numericStepper .
La nueva apariencia que acaba de crear ahora está disponible para su uso.