Crear aspectos personalizados para campos de formulario adaptables
Introducción
Los formularios adaptables aprovechan el marco de trabajo de apariencia para ayudarle a crear aspectos personalizados para 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.
Aspecto 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 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 del widget jQuery, para implementar un aspecto alternativo.
ClientLib Un sistema de bibliotecas del lado del cliente en AEM procesamiento del lado del cliente impulsado por código CSS y JavaScript complejo. Para obtener más información, consulte Uso de bibliotecas del lado del cliente.
Tipo de archivo Conjunto de herramientas de creación de plantillas de proyecto de Maven definido 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 una utilidad que contiene el valor del campo y se utiliza en la estructura de aspecto para enlazar la interfaz de usuario del widget personalizado 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:
Crear un proyecto: Cree un proyecto de Maven que genere un paquete de contenido para implementarlo en AEM.
Ampliar una clase de utilidad existente: Amplíe una clase de widget existente y anule las clases requeridas.
Crear una biblioteca de cliente: Cree un clientLib: af.customwidget y añada los archivos JavaScript y CSS necesarios.
Creación e instalación del 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 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:
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.
version: 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.
NombreWidget: 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:
Incluya la dependencia del complemento de terceros al proyecto.
Coloque los complementos de jQuery personalizados o de terceros en la variable jqueryplugin/javascript carpeta y archivos CSS relacionados en la jqueryplugin/css carpeta. Para obtener más información, consulte los archivos JS y CSS en la sección jqueryplugin/javascript and jqueryplugin/css carpeta.
Modifique el js.txt y css.txt para incluir cualquier archivo JavaScript y CSS adicional del complemento jQuery.
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 la variable $userControl especifica la restricción anterior, las funciones del AbstractWidget funciona 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 evento enter , la variable rawValue del campo . Esta función se llama para mostrar la variable rawValue al usuario.
showDisplayValue
De forma predeterminada, en XFA en el evento de salida, la variable formattedValue del campo . Esta función se llama para mostrar la variable formattedValue al usuario.
Actualice el archivo JavaScript en la sección integration/javascript , según sea necesario.
Reemplazar el texto __widgetName__ con 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 sustitúyalo por la clase principal real utilizada.
Amplíe el 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. La variable render debe devolver un elemento de control de usuario.
Amplíe el getOptionsMap para anular cualquier configuración de opción afectada por 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.
La variable 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.
La variable showDisplayValue y showValue aplique la cláusula de visualización y edición de imagen y se puede sobrescribir para que tenga un comportamiento alternativo.
La variable getCommitValue es invocado por el marco de formularios adaptables cuando commitse produce. 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 la variable 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 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 Maven, la información del repositorio se captura en la variable settings.xml archivo.
Actualizar el formulario adaptable
Para aplicar el aspecto personalizado a un campo de formulario adaptable:
Abra el formulario adaptable en modo de edición.
Abra el Propiedad para el campo en el que desea aplicar el aspecto personalizado.
En el Estilo , actualice el CSS class para agregar el nombre del aspecto en la variable widget_<widgetName> formato. 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:
Ejecute el siguiente comando para crear un proyecto local basado en el tipo de archivo Maven:
En el proyecto Eclipse, revise el código del complemento en la plugin.js para asegurarse de que coincide con los requisitos del aspecto. En este ejemplo, el aspecto visual cumple los siguientes requisitos:
El paso numérico debe extenderse desde - $.xfaWidget.numericInput.
La variable 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.
La variable render debe anularse para invocar el método 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 paso, por lo que no se requiere CSS adicional.
La variable $userControl debe estar disponible para el render método. Es un campo del text tipo que se clona con el código del complemento.
La variable + y - Los botones deben desactivarse cuando el campo esté desactivado.
Reemplace el contenido del bootstrap-number-input.js (Complemento jQuery) con el contenido del numericStepper-plugin.js archivo.
En el numericStepper-widget.js , añada el siguiente código para anular el método render 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;
}
En el numericStepper-widget.js , omita el getOptionsMap para anular la opción de acceso y ocultar los botones + y - en modo desactivado.
Guarde los cambios, vaya a la carpeta que contiene el pom.xml y ejecute el siguiente comando Maven para crear el proyecto:
mvn clean install
Instale el paquete mediante AEM Administrador de paquetes.
Abra el formulario adaptable en modo de edición en el que desee aplicar el aspecto personalizado 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 variable Clase CSS propiedad para agregar widget_numericStepper.
La nueva apariencia que acaba de crear ya está disponible para su uso.
