La estructura básica de un formulario es:
Todos estos componentes se realizan con una serie de componentes de formulario predeterminados, disponibles en una instalación de AEM estándar.
Además de desarrollar nuevos componentes para su uso en los formularios, también puede:
Uso de secuencias de comandos para ampliar la funcionalidad cuando sea necesario.
Este documento se centra en el desarrollo de formularios mediante Foundation Components en la IU clásica. Adobe recomienda aprovechar los nuevos Componentes principales y Ocultar condiciones para el desarrollo de formularios en la IU táctil.
El componente inicio de formulario proporciona un campo para la Ruta de carga, una ruta opcional que apunta a un nodo del repositorio.
Ruta de carga es la ruta a las propiedades del nodo que se utiliza para cargar valores predefinidos en varios campos del formulario.
Se trata de un campo opcional que especifica la ruta a un nodo en el repositorio. Cuando este nodo cuenta con propiedades que coinciden con los nombres de campo, los campos apropiados del formulario se cargan previamente con el valor de estas propiedades. Si no existe coincidencia, el campo contiene el valor predeterminado.
Una acción de formulario también puede establecer el recurso desde el cual cargar los valores iniciales. Esto se realiza utilizando FormsHelper#setFormLoadResource
dentro de init.jsp
.
Sólo si no se ha establecido, el autor rellenará el formulario desde la ruta definida en el componente de formulario de inicio.
Varios campos de formulario también tienen la Ruta de carga de elementos, otra vez una ruta opcional que apunta a un nodo en el repositorio.
La Ruta de carga de elementos es la ruta a las propiedades del nodo que se utiliza para cargar valores predefinidos en ese campo específico del formulario; por ejemplo, una lista desplegable, grupo de casillas de verificación o grupo de radio.
Se puede configurar una lista desplegable con el rango de valores para la selección.
La Ruta de carga de elementos puede utilizarse para acceder a una lista desde una carpeta del repositorio y precargarla en el campo:
Crear una nueva carpeta sling ( sling:Folder
)
por ejemplo, /etc/designs/<myDesign>/formlistvalues
Añada una nueva propiedad (por ejemplo, myList
) de tipo cadena de varios valores ( String[]
) para contener la lista de elementos desplegables. El contenido también se puede importar mediante una secuencia de comandos, como con una secuencia de comandos JSP o cURL en una secuencia de comandos de shell.
Utilice la ruta completa en el campo Ruta de carga de elementos:
por ejemplo, /etc/designs/geometrixx/formlistvalues/myList
Tenga en cuenta que si los valores de String[]
tienen el formato siguiente:
AL=Alabama
AK=Alaska
aem generará la lista como:
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
Esta función puede, por ejemplo, utilizarse bien en una configuración de varios idiomas.
Un formulario necesita una acción. Una acción define la operación que se ejecuta cuando el formulario se envía con los datos del usuario.
Se proporciona una serie de acciones con una instalación AEM estándar, que se pueden ver en:
/libs/foundation/components/form/actions
y en la lista Tipo de acción del componente Formulario:
Esta sección trata cómo desarrollar su propia acción de formulario para incluirla en esta lista.
Puede agregar su propia acción en /apps
de la siguiente manera:
Cree un nodo de tipo sling:Folder
. Especifique un nombre que refleje la acción que se va a implementar.
Por ejemplo:
/apps/myProject/components/customFormAction
En este nodo, defina las siguientes propiedades y haga clic en Guardar todo para mantener los cambios:
sling:resourceType
- configurado como foundation/components/form/action
componentGroup
- definir como .hidden
De forma opcional:
jcr:title
- especifique un título de su elección, esto se mostrará en la lista de selección desplegable. Si no se establece, se muestra el nombre del nodojcr:description
- escriba una descripción de su elecciónEn la carpeta, cree un nodo de cuadro de diálogo:
En la carpeta, cree una de las opciones siguientes:
Un script de anuncio.
El nombre de la secuencia de comandos es post.POST.<extension>
, por ejemplo: post.POST.jsp
La secuencia de comandos posterior se invoca cuando se envía un formulario para procesarlo, contiene el código que controla los datos que llegan desde el formulario POST
.
Añada una secuencia de comandos hacia delante que se invoque al enviar el formulario.
El nombre de la secuencia de comandos es forward.<extension
, por ejemplo: forward.jsp
Esta secuencia de comandos puede definir una ruta. La solicitud actual se reenvía a la ruta especificada.
La llamada necesaria es FormsHelper#setForwardPath
(2 variantes). Un caso típico es realizar alguna validación, o lógica, para encontrar la ruta de destinatario y luego avanzar a esa ruta, permitiendo que el servlet predeterminado del POST Sling haga el almacenamiento real en JCR.
También puede haber otro servlet que realice el procesamiento real, en tal caso la acción del formulario y forward.jsp
sólo actuaría como el código "pegado". Un ejemplo de esto es la acción de correo en /libs/foundation/components/form/actions/mail
, que envía los detalles a <currentpath>.mail.html
donde se encuentra un servlet de correo.
Entonces:
post.POST.jsp
es útil para pequeñas operaciones que se realizan completamente por la propia acciónforward.jsp
es útil cuando solo se requiere la delegación.El orden de ejecución de las secuencias de comandos es:
Al procesar el formulario ( GET
):
init.jsp
clientvalidation.jsp
clientvalidation.jsp
addfields.jsp
mientras se procesa dentro de la representación <form></form>
al administrar un formulario POST
:
init.jsp
servervalidation.jsp
servervalidation.jsp
forward.jsp
FormsHelper.setForwardPath
), reenvíe la solicitud y, a continuación, llame a cleanup.jsp
post.POST.jsp
(termina aquí, no se llama a cleanup.jsp
)De nuevo en la carpeta, agregue de forma opcional:
Secuencia de comandos para agregar campos.
El nombre de la secuencia de comandos es addfields.<extension>
, por ejemplo: addfields.jsp
Se invoca una secuencia de comandos addfields inmediatamente después de escribir el HTML para el inicio de formulario. Esto permite que la acción agregue campos de entrada personalizados u otro código HTML dentro del formulario.
Una secuencia de comandos de inicialización.
El nombre de la secuencia de comandos es init.<extension>
, por ejemplo: init.jsp
Esta secuencia de comandos se invoca cuando se procesa el formulario. Se puede utilizar para inicializar detalles específicos de acciones. "
Un script de limpieza.
El nombre de la secuencia de comandos es cleanup.<extension>
, por ejemplo: cleanup.jsp
Esta secuencia de comandos se puede utilizar para realizar la limpieza.
Utilice el componente Forms en un parámetro. La lista desplegable Tipo de acción ahora incluirá la nueva acción.
Para ver las acciones predeterminadas que forman parte del producto:
/libs/foundation/components/form/actions
Las restricciones pueden imponerse en dos niveles:
Puede agregar sus propias restricciones para un campo individual (en /apps
) de la siguiente manera:
Cree un nodo de tipo sling:Folder
. Especifique un nombre que refleje la restricción que se va a implementar.
Por ejemplo:
/apps/myProject/components/customFormConstraint
En este nodo, defina las siguientes propiedades y haga clic en Guardar todo para mantener los cambios:
sling:resourceType
- configurado para foundation/components/form/constraint
constraintMessage
- un mensaje personalizado que se mostrará si el campo no es válido, según la restricción, al enviar el formulario
De forma opcional:
jcr:title
- especifique un título de su elección, esto se mostrará en la lista de selección. Si no se establece, se muestra el nombre del nodohint
- información adicional, para el usuario, sobre cómo utilizar el campoDentro de esta carpeta, puede necesitar las siguientes secuencias de comandos:
Una secuencia de comandos de validación de cliente:
El nombre de la secuencia de comandos es clientvalidation.<extension>
, por ejemplo: clientvalidation.jsp
Esto se invoca cuando se procesa el campo de formulario. Se puede utilizar para crear javascript de cliente para validar el campo en el cliente.
Secuencia de comandos de validación del servidor:
El nombre de la secuencia de comandos es servervalidation.<extension>
, por ejemplo: servervalidation.jsp
Esto se invoca cuando se envía el formulario. Se puede utilizar para validar el campo en el servidor después de enviarlo.
En:
/libs/foundation/components/form/constraints
La validación global del formulario se especifica configurando un tipo de recurso en el componente de formulario de inicio ( validationRT
). Por ejemplo:
apps/myProject/components/form/validation
A continuación, puede definir:
clientvalidation.jsp
- insertado después de las secuencias de comandos de validación del cliente del camposervervalidation.jsp
- también llamado después de las validaciones del servidor de campo individual en un POST
.Puede configurar el formulario para que muestre u oculte los componentes del formulario según el valor de otros campos del formulario.
Cambiar la visibilidad de un campo de formulario resulta útil cuando el campo es necesario sólo en condiciones concretas. Por ejemplo, en un formulario de recopilación de información, se pregunta al usuario si desea que la información del producto se le envíe por correo electrónico. Al seleccionar Sí, aparece el campo de texto para que el cliente pueda escribir su dirección de correo electrónico.
Utilice el cuadro de diálogo Editar Mostrar/Ocultar reglas para especificar las condiciones en las que se muestra u oculta un componente de formulario.
Utilice los campos en la parte superior del cuadro de diálogo para especificar la siguiente información:
Aparecen una o varias condiciones bajo estos campos. Una condición compara el valor de otro componente del formulario (en el mismo formulario) con un valor. Si el valor real del campo se ajusta a la condición, la condición evalúa en verdadero. Las condiciones incluyen la siguiente información:
Por ejemplo, un componente Grupo de radio con el título Receive email notifications?
* * contiene los botones de radio Yes
y No
. Un componente Campo de texto con el título Email Address
utiliza la siguiente condición para que sea visible si se selecciona Yes
:
En Javascript, las condiciones utilizan el valor de la propiedad Nombre del elemento para hacer referencia a campos. En el ejemplo anterior, la propiedad Nombre de elemento del componente Grupo de radio es contact
. El siguiente código es el código Javascript equivalente para ese ejemplo:
((contact == "Yes"))
Para mostrar u ocultar un componente de formulario:
Edite el componente de formulario específico.
Seleccione Mostrar / Ocultar para abrir el cuadro de diálogo Editar Mostrar / Ocultar reglas:
En la primera lista desplegable, seleccione Mostrar o Ocultar para especificar si las condiciones determinan si se muestra u oculta el componente.
En la lista desplegable al final de la línea superior, seleccione:
En la línea de condición (una se presenta como predeterminada), seleccione un componente, operador y, a continuación, especifique un valor.
Añada más condiciones si es necesario haciendo clic en Añadir condición.
Por ejemplo:
Haga clic en Aceptar para guardar la definición.
Después de guardar la definición, aparece un vínculo Editar reglas junto a la opción Mostrar / Ocultar en las propiedades del componente del formulario. Haga clic en este vínculo para abrir el cuadro de diálogo Editar Mostrar / Ocultar reglas para realizar cambios.
Haga clic en Aceptar para guardar todos los cambios.
Se pueden ver y probar los efectos de las definiciones Mostrar/Ocultar:
Las condiciones de la función de mostrar y ocultar utilizan el valor de la propiedad Nombre de elemento para hacer referencia a otros componentes del formulario. La configuración Mostrar/Ocultar no es válida cuando cualquiera de las condiciones hace referencia a un componente que se elimina o cuya propiedad Nombre del elemento ha cambiado. Cuando se produce esta situación, se deben actualizar manualmente las condiciones o se producirá un error cuando se cargue el formulario.
Cuando la configuración Mostrar/Ocultar no es válida, la configuración se proporciona únicamente como código JavaScript. Edite el código para corregir los problemas. El código utilizará la propiedad Nombre de elemento utilizada originalmente para hacer referencia a los componentes.
Para obtener más información sobre los elementos de API que se pueden utilizar al escribir secuencias de comandos, consulte los javadocs relacionados con los formularios.
Esto se puede utilizar para acciones como llamar a un servicio antes de enviar el formulario y cancelar el servicio si se produce un error:
Definir el tipo de recurso de validación
Incluir una secuencia de comandos para validación:
com.day.cq.wcm.foundation.forms.ValidationInfo
que contenga sus mensajes de error. Si hay errores, los datos del formulario no se publicarán.