Crear apariencias personalizadas para campos de formularios adaptables
Creado para:
- User
Introducción
Los formularios adaptables aprovechan el marco de trabajo de apariencia para ayudarle a crear apariencias personalizadas para campos de formularios adaptables y proporcionar una experiencia de usuario diferente. Por ejemplo, reemplace los botones de radio y las casillas de verificación por 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 formularios adaptables. Además, muestra un ejemplo para crear una apariencia personalizada para que el componente de campo numérico aparezca como un salto numérico o un control deslizante.
Veamos primero los términos y conceptos clave utilizados en este artículo.
Apariencia Se refiere al estilo, la apariencia 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 de la apariencia que se describe en este artículo es aplicable a la apariencia del área de entrada del campo.
Complemento jQuery Proporciona un mecanismo estándar, basado en el marco de trabajo del widget jQuery, para implementar una apariencia alternativa.
ClientLib Es un sistema de bibliotecas del lado del cliente en procesamiento del lado del cliente de AEM impulsado por código CSS y JavaScript complejo. Para obtener más información, consulte Uso de bibliotecas del lado del cliente.
Arquetipo Es un conjunto de herramientas de creación de plantillas de proyecto de Maven definidas como 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 usuario Se refiere al elemento principal de un widget que contiene el valor del campo y se utiliza en la estructura de la apariencia para enlazar la interfaz de usuario del widget personalizado con el modelo del formulario adaptable.
Pasos para crear una apariencia personalizada
Los pasos, en un nivel superior, para crear una apariencia personalizada son los siguientes:
-
Crear un proyecto: cree un proyecto de Maven que genere un paquete de contenido para implementarlo en AEM.
-
Ampliar una clase de widget existente: amplíe una clase de widget existente y anule las clases requeridas.
-
Crear una biblioteca de cliente: cree una biblioteca
clientLib: af.customwidget
y agregue los archivos JavaScript y CSS necesarios. -
Crear e instalar el proyecto: cree el proyecto Maven e instale el paquete de contenido generado en AEM.
-
Actualizar el formulario adaptable: actualice las propiedades del campo del formulario adaptable para utilizar la apariencia personalizada.
Crear un proyecto
Un arquetipo Maven es un punto de partida para crear una apariencia personalizada. Los detalles del arquetipo a utilizar son los siguientes:
- Repositorio: https://repo.adobe.com/nexus/content/groups/public/
- ID del 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 del arquetipo 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 del 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.
- widgetName: 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 widget existente
Una vez creada la plantilla del proyecto, realice los siguientes cambios según sea necesario:
-
Incluya la dependencia del complemento de terceros al proyecto.
- Coloque los complementos de jQuery personalizados o de terceros en la carpeta
jqueryplugin/javascript
y los archivos CSS relacionados en la carpetajqueryplugin/css
. Para obtener más información, consulte los archivos JS y CSS en la carpetajqueryplugin/javascript and jqueryplugin/css
. - Modifique el
js.txt
ycss.txt
para incluir cualquier archivo JavaScript y CSS adicional del complemento jQuery.
- Coloque los complementos de jQuery personalizados o de terceros en la carpeta
-
Integre el complemento de terceros con el marco para permitir la interacción entre el marco de trabajo de apariencia personalizada y el complemento jQuery. El widget nuevo solo funcionará después de ampliar o de anular las siguientes funciones.
render
<a>
, <input>
y <li>
. El elemento devuelto se usa como $userControl
. Si el $userControl
especifica la restricción anterior, las funciones de la clase AbstractWidget
funcionarán como se espera, de lo contrario, algunas de las API comunes (enfoque, clic) requierirán cambios.getEventMap
{ blur: XFA_EXIT_EVENT, }
Este ejemplo muestra que
blur
es un evento HTML y XFA_EXIT_EVENT
es el evento XFA correspondiente.getOptionsMap
value
y displayValue
).getCommitValue
showValue
rawValue
del campo. Esta función se llama para mostrar el rawValue
al usuario.showDisplayValue
formattedValue
del campo. Esta función se llama para mostrar el formattedValue
al usuario.-
Actualice el archivo JavaScript en la carpeta
integration/javascript
, según sea necesario.- Reemplace el texto
__widgetName__
con el nombre del widget. - Amplíe el widget desde una clase de widget adecuada. En la mayoría de los casos, es la clase de widget correspondiente al widget existente que reemplaza. 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 reemplzarlas 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étodorender
debe devolver un elemento de control de usuario. - Amplíe el método
getOptionsMap
para anular cualquier configuración de opción afectada por un cambio en el widget. La función devuelve un mapa que proporciona detalles para que la acción se realice al cambiar una opción. Las claves son las opciones proporcionadas para el 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
mapea los eventos activados por el widget, con los eventos requeridos por el modelo de formulario adaptable. El valor predeterminado asigna eventos HTML estándar para el widget predeterminado y debe actualizarse si se activa un evento alternativo. - El
showDisplayValue
yshowValue
aplican la cláusula de visualización y de edición de imagen y se pueden sobrescribir para que tengan un comportamiento alternativo. - El método
getCommitValue
es invocado por el marco de trabajo de formularios adaptables cuando se produce el eventocommit
. Generalmente, ocurre en el evento de salida, excepto para los elementos de lista desplegable, el botón de radio y la casilla de verificación al cambiar). Para obtener más información, consulte Expresiones de formularios adaptables. - El archivo de plantilla proporciona una implementación de muestra para varios métodos. Quite los métodos que no se vayan a ampliar.
- Reemplace el texto
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 el af.customwidgets
se incluyen automáticamente durante la ejecución.
Generar e instalar
Para crear el proyecto, ejecute el siguiente comando en shell para generar un paquete CRX que necesite instalarse en el servidor de AEM.
mvn clean install
settings.xml
.Actualizar el formulario adaptable
Para aplicar la apariencia personalizada a un campo de formulario adaptable, haga lo siguiente:
- Abra el formulario adaptable en modo de edición.
- Abra el cuadro de diálogo Propiedad para el campo en el que desea aplicar la apariencia personalizada.
- En la pestaña Estilo, actualice la propiedad
CSS class
para agregar el nombre de la apariencia en el formatowidget_<widgetName>
. Por ejemplo: widget_numericstepper
Ejemplo: Crear una apariencia personalizada
Veamos un ejemplo para crear una apariencia personalizada para que un campo numérico aparezca como un salto numérico o un control deslizante. Siga estos pasos:
-
Ejecute el siguiente comando para crear un proyecto local basado en el tipo de archivo 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 solicitará 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
-
Navegue hasta el directorio
customWidgets
(valor especificado para la propiedadartifactID
) y ejecute el siguiente comando para generar un proyecto Eclipse:mvn eclipse:eclipse
-
Abra la herramienta Eclipse y haga lo siguiente para importar el proyecto Eclipse:
-
Seleccione Archivo > Importar > Proyectos existentes en el espacio de trabajo.
-
Busque y seleccione la carpeta en la que ejecutó el comando
archetype:generate
. -
Haga clic en Finalizar.
-
-
Seleccione el widget que se utilizará para la apariencia personalizada. Este ejemplo utiliza el siguiente widget de saltos 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 de la apariencia. En este ejemplo, la apariencia visual cumple los siguientes requisitos:- El salto 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. - El método
render
debe anularse para invocar el métodobootstrapNumber
. - 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 salto, por lo que no se requiere CSS adicional.
- El objeto
$userControl
debe estar disponible para el métodorender
. Es un campo del tipotext
que se clona con el código del complemento. - Los botones + y - deben deshabilitarse cuando el campo esté deshabilitado.
- El salto numérico debe extenderse desde
-
Reemplace el contenido del
bootstrap-number-input.js
(Complemento jQuery) por el contenido del archivonumericStepper-plugin.js
. -
En el archivo
numericStepper-widget.js
, agregue el siguiente código para anular el método de procesamiento para 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; }
-
En el archivo
numericStepper-widget.js
, omita la propiedadgetOptionsMap
para anular la opción de acceso y ocultar los botones + y - en modo deshabilitado.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; }
-
Guarde los cambios, navegue hasta la carpeta que contenga el archivo
pom.xml
y ejecute el siguiente comando Maven para crear el proyecto:mvn clean install
-
Instale el paquete mediante el administrador de paquetes de AEM.
-
Abra el formulario adaptable en modo de edición en el que desee aplicar la apariencia personalizada y haga lo siguiente:
-
Haga clic con el botón derecho en el campo en el que desee aplicar la apariencia y haga clic en Editar para abrir el cuadro de diálogo Editar componente.
-
En la pestaña Estilo, actualice la propiedad clase CSS para agregar
widget_numericStepper
.
-
La nueva apariencia que acaba de crear ya está disponible para usarla.