UDA-Componentes RUP. Formulario

UDA – Utilidades de desarrollo de aplicaciones by EJIE is licensed under a Creative Commons Reconocimiento-
NoComercial-CompartirIgual 3.0 Unported License.
UDA - Utilidades de Desarrollo de Aplicaciones
Componentes RUP – Formulario
Fecha: 22/11/2013 Referencia:
EJIE S.A.
Mediterráneo, 14
Tel. 945 01 73 00*
Fax. 945 01 73 01
01010 Vitoria-Gasteiz
Posta-kutxatila / Apartado: 809
01080 Vitoria-Gasteiz
www.ejie.es

Componentes RUP – Formulario ii/14
Control de documentación
Título de documento: Componentes RUP – Formulario
Histórico de versiones
Código: Versión: Fecha: Resumen de cambios:
2.0.0 11/07/2012 Primera versión.
2.1.0 18/09/2012
Actualización de las versiones de las librerías
JavaScript subyacentes.
Añadido del apartado referente a la emulación de
peticiones XHR mediante el uso de iframes
2.1.1 09/01/2013
Añadidos nuevos métodos públicos: ajaxSubmit,
formToJson.
Añadida una nueva propiedad de configuración del
componente: useJsonIfPossible
2.4.0 22/11/2013
Se distribuye la versión minimizada de los ficheros
javascript y de estilos de RUP.
Cambios producidos desde la última versión
Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.
Control de difusión
Responsable: Ander Martínez
Aprobado por:
Firma: Fecha:
Distribución:
Referencias de archivo
Autor:
Nombre archivo:

Componentes RUP – Formulario iii/14
Localización:
Contenido
Capítulo/sección Página
1. Introducción 4
2. Ejemplo 4
3. Casos de uso 4
4. Infraestructura 5
4.1. Ficheros 5
4.2. Dependencias 5
5. Invocación 6
6. Parámetros 7
7. Funciones 8
8. Sobreescritura del theme 9
9. Integración con UDA 9
9.1. Envío y recepción de datos 9
9.2. Envío de múltiples entidades 9
9.3. Subida de ficheros 12
10. Interacción con otros componentes RUP 14

Componentes RUP – Formulario 4/14
1. Introducción
La descripción del Componente Formulario, visto desde el punto de vista de RUP, es la siguiente:
Permite al usuario introducir datos en una serie de campos para ser enviados al servidor y ser
procesados.
2. Ejemplo
Se presenta a continuación un ejemplo de este componente:
3. Casos de uso
Se aconseja la utilización de este componente:
• Cuando sea necesario enviar formularios vía AJAX.

4. Infraestructura
A continuación se comenta la infraestructura necesaria para el correcto funcionamiento del componente.
• Únicamente se requiere la inclusión de los ficheros que implementan el componente (js y css)
comentados en los apartados Ficheros y Dependencias.
4.1. Ficheros
Ruta Javascript: rup/scripts/
Fichero de plugin: rup.form-x.y.z.js
Ruta theme: rup/basic-theme/
Fichero CSS del theme: theme.rup.form-x.y.z.css
4.2. Dependencias
Por la naturaleza de desarrollo de los componentes (patrones) como plugins basados en la librería
JavaScript jQuery, es necesaria la inclusión del esta. La versión elegida para el desarrollo ha sido la
versión 1.8.0.
• jQuery 1.8.0: http://jquery.com/
La gestión de la ciertas partes visuales de los componentes, se han realizado mediante el plugin jQuery
UI que se basa en jQuery y se utiliza para construir aplicaciones web altamente interactivas. Este plugin,
proporciona abstracciones de bajo nivel de interacción y animación, efectos avanzados de alto nivel,
componentes personalizables (estilos) ente otros. La versión utilizada en el desarrollo ha sido la 1.8.23.
• jQuery UI 1.8.23: http://jqueryui.com/
Las distintas funcionalidades que aporta el componente y las prestaciones generales del mismo, se
apoyan en el plugin jQuery File Upload. Para el correcto funcionamiento del componente Upload, se
precisa de la inclusión de dicho plugin.
• jQuery-File-Upload: http://blueimp.github.com/jQuery-File-Upload/
Los ficheros necesarios para el correcto funcionamiento del componente son:
• jquery-1.8.0.js
• jquery-ui-1.8.23.custom.js
• jquery-ui-1.8.23.custom.css
• jquery.form.js
• rup.form-x.y.z.js

4.3. Versión minimizada
A partir de la versión v2.4.0 se distribuye la versión minimizada de los componentes RUP. Estos ficheros
contienen la versión compactada y minimizada de los ficheros javascript y de estilos necesarios para el
uso de todos los compontente RUP.
Los ficheros minimizados de RUP son los siguientes:
• rup/scripts/min/rup.min-x.y.z.js
• rup/basic-theme/rup.min-x.y.z.css
Estos ficheros son los que deben utilizarse por las aplicaciones. Las versiones individuales de cada uno
de los componentes solo deberán de emplearse en tareas de desarrollo o depuración.
5. Invocación
El componente formulario se invoca sobre un formulario html existente en la jsp. El formulario contendrá los
campos que se desean enviar.
Un ejemplo de un formulario que se desee enviar es el siguiente:
<form id="formulario" action="/form">
<label for="nombre">Nombre</label>
<input type="text" name="nombre" id="nombre" />
<label for="apellido1" >Primer apellido</label>
<input type="text" name="apellido1" id="apellido1" />
<label for="apellido2" >Segundo apellido</label>
<input type="text" name="apellido2" id="apellido2" />
</form>
En este caso el formulario dispone de tres campos que serán enviados al servidor. Para realizar la
invocación del componente formulario realizaremos lo siguiente:
var properties={
// Propiedades de configuración
};
$("#formulario").rup_form(properties);
Como ya se profundizará mas adelante, mediante las propiedades indicadas en la invocación del
componente, se realiza la configuración del mismo.

6. Parámetros
A continuación se muestran los posibles parámetros de configuración que recibe el componente.
• beforeSerialize: Función de callback que será invocada antes de realizarse la serialización del
formulario. Permite la modificación de los datos del formulario antes de que estos sean recuperados
para su procesado por el componente. Valor por defecto, null.
• beforeSubmit: Función de callback que será invocada antes de realizarse el envío del formulario.
Permite acceder a la información que será enviada al formulario. En caso de retornar false no se
realizará en envío. Valor por defecto, null.
• clearForm: Propiedad booleana que determina si el formulario debe de limpiarse después de
realizar el envío.
• data: Mediante esta propiedad es posible especificar parámetros extra que sean enviados al
servidor.
• dataType: Tipo de datos esperados en la respuesta. Los valores posibles son null, xml, json y script.
Valor por defecto null.
• error: Función de callback que será invocada cuando se produzca un error.
• forceSync: Propiedad booleana. En caso de ser true elimina la corta espera que se produce antes
de enviar el formulario cuando se envían ficheros o se utiliza la opción de iframe. La espera se utiliza
para permitir al navegador actualizar modificaciones realizadas en el DOM antes de que se realice el
envío de los datos. Por defecto a false.
• iframe: Determina si el formulario debe de ser enviado siempre mediante un iframe. Por defecto a
false.
• iframeSrc: Propiedad de texto que deberá ser utlizada siempre en conjunción con la propiedad
iframe. Por defecto, about:blank. Por defecto para páginas que utlicen el protocolo https, javascript:false.
• iframeTarget: Identifica el iframe que será utilizado como target en la respuesta en los envíos de
ficheros. Por defecto, el componente creará un iframe temporal para capturar la respuesta del envío de
ficheros. Valor por defecto, null.
• multimodel: Permite especificar la configuración que se deberá de aplicar a la hora de realizar el
envío de varias entidades en la misma petición. La configuración de este parámetro se detalla en el
apartado 9.2. Valor por defecto, false.
• replaceTarget: Opcionalmente se utililiza junto con la opción target. En caso de ser true el elemento
identificado en la opción target será reemplazado. En caso de ser false solo su contenido será
reemplazado. Valor por defecto, false.
• resetForm: Propiedad booleana que determina si el formulario debe ser inicializado al realizarse el
envío del mismo. Por defecto, false.
• semantic: Propiedad booleana que determina si los campos del formulario deben ser enviado en
estricto orden semántico. Por defecto la serialización normal del formulario se realiza en orden
semántico exceptuando los campos img. Valor por defencto, false.
• success: Método callback que será invocado cuando se reciba la respuesta del formulario.
• target: Identifica los elementos de la página que deberán ser actualizados con la respuesta del
servidor. El target puede ser indicado mediante un selector de jQuery, un objeto de jQuery o un objeto
DOM.

• type: Detemina el método con el que se enviará el formulario, GET o POST. Por defecto el valor de
la propiedad method indicada en el formulario o GET en caso de no encontrarse.
• uploadProgress: Método que será invocado con información de progreso del envío del formulario
(en caso de estar soportado por el navegador).
• url: URL a la cual se realizará en envío del formulario. Por defecto el valor indicado en la propiedad
action del formulario.
• useJsonIfPossible: Mediante este parámetro se especifica al componente que debe de utilizar el
formato application/json como prioridad (siempre que sea posible) al realizar el envío del formulario.
Valor por defecto, true.
Junto con las propiedades de configuración del componente es posible especificar propiedades
de configuración para el método $.ajax de jQuery que será utilizado para el envío de los datos del
formulario.
7. Funciones
A continuación se detallan las diferentes funciones que integran el componente validación:
• ajaxForm: Configura un formulario para ser enviado vía AJAX. Para ello añade los event listener
jQuery que sean necesarios. Este método no realiza el envío del formulario. Esta función puede ser
invocada sin parámetros o con un simple parámetro que puede ser o una función de callback o un
objeto con las propiedades de configuración.
• ajaxSubmit: Realiza el envío del formulario. La configuración de este método es la misma que la de
ajaxForm.
• ajaxFormSubmit: Realiza la misma función que ajaxSubmit. Se mantiene para asegurar la
retrocompatibilidad con versiones anteriores.
• formSerialize: Serializa el contenido del formulario en un query string. Este método retorna una
cadena de texto con el formato nombre1=valor1&nombre2=valor2.
• fieldSerialize: Realiza la serialización de campos del formulario en un query string. Retorna una
cadena de texto con el formato nombre1=valor1&nombre2=valor2.
• formToJson: Realiza la serialización de campos del formulario en un objeto json. Retorna un objeto
con el formato {nombre1:valor1, nombre2:valor2…nombreN:valorN}.
• fieldValue: Devuelve un array con el valor de los campos indicados. La función siempre devuelve un
array.
• resetForm: Inicializa el formulario con su estado inicial invocando al método reset nativo.
• clearForm: Limpia los elementos del formulario.

• clearFields: Limpia los campos especificados mediante el selector de jQuery.
8. Sobreescritura del theme
No aplica.
9. Integración con UDA
En este apartado se va a explicar las diferentes interacciones que realiza el componente con el resto de
subsistemas definidos en UDA.
9.1. Envío y recepción de datos
El componente formulario realiza, por defecto, el envío de los datos en formato application/json, excepto en
los casos en los que se ha especificado otro formato de envío o cuando se debe realizar envío de un fichero.
El envío de ficheros se detallará en un apartado posterior.
Una vez explicado este punto, se presentan dos escenarios al realizar el envío del formulario:
• El contenido del formulario se envía en formato application/json. En este caso el data binding de
estos datos se realiza sobre el parámetro del controller anotado mediante @RequestBody. El
proceso de data binding del formulario enviado en formato application/json se realiza mediante el
componente Jackson JSON Processor. El uso y configuración del mismo se detalla en el documento
correspondiente.
El método del controller encargado de recoger los datos se declarará del siguiente modo:
@RequestMapping(method = RequestMethod.POST)
public @ResponseBody Alumno add(@RequestBody Alumno alumno){
}
• El contenido del formulario se envía en formato un formato diferente al application/json, por ejemplo
en multipart/form-data o application/x-www-form-urlencoded. En este caso el data binding de estos
datos se realiza sobre el parámetro del controller anotado mediante @ModelAttribute.
El método del controller encargado de recoger los datos se declarará del siguiente modo:
@RequestMapping(method = RequestMethod.POST)
public @ResponseBody Alumno edit(@ModelAttribute Alumno alumno){
}
9.2. Envío de múltiples entidades
El componente formulario permite, junto con el uso del componente Jackson, el envío y recepción de datos
de múltiples entidades dentro de la misma petición.

Supongamos que se debe de enviar desde la capa de presentación cierta información introducida por el
usuario. El databinding de estos datos debe de ser realizado sobre dos beans entre los cuales no existe
anidamiento:
public class Alumno implements java.io.Serializable {
private BidDecimal id;
private String nombre;
private String apellido1;
private String apellido2;
// Getters y setters de las propiedades
}
public class Departamento implements java.io.Serializable {
private BidDecimal id;
private String descEs;
private String descEu;
// Getters y setters de las propiedades
}
Para evitar la creación de un nuevo tipo de bean cada vez que se da esta necesidad se ha implementado
una nueva funcionalidad de Jackson. Esta funcionalidad es proporcionada por el UdaModule y permite
realizar el databinding de varias entidades sobre un parámetro del método de tipo HashMap.
Para poder determinar en cada petición si se va a utilizar o no el databinding múltiple, se incluye una
cabecera en la petición, RUP_MULTI_ENTITY. En caso de ser true se activará el comportamiento especial.
Este sería el proceso completo de databinding múltiple:
1. Partimos de un formulario definido en la jsp en el que se dispone de varios campos
correspondientes a varias entidades:
<form id="formMultientidades" action='/multientidades' method="post">
<input type="text" name="alumno.id" />
<input type="text" name="alumno.nombre" />
<input type="text" name="alumno.apellido1" />
<input type="text" name="alumno.apellido2" />
<input type="text" name="departamento.id" />
<input type="text" name="departamento.descEs" />
<input type="text" name="departamento.descEu" />
<input type="submit" value="Enviar" />
</form>
2. Se invoca al componente RUP formulario. En la configuración se especifica la información necesaria
para realizar el data binding múltiple:
$("#formMultientidades").rup_form({
feedback:$("#feedbackMensajes"),
multimodel:{
"alumno":"com.ejie.x21a.model.Alumno",
"departamento":"com.ejie.x21a.model.Departamento"
},
success:function(xhr){
// Tratamiento de la petición realizada correctamente
},
validate:{

rules:{
// Reglas de validación necesarias
}
}
});
En la propiedad multimodel se especifica la correlación entre las nombres de las propiedades y de
los objetos Java.
La petición resultante tiene el siguiente aspecto:
Content-Type application/json; charset=UTF-8
RUP_MULTI_ENTITY true
{
"alumno":
{"id":"1","nombre":"Nom","apellido1":"ap1","apellido2":"ap2"},
"departamento":
{"id":"3","descEs":"Dep_es","descEu":"Dep_eu"},
"rupEntityMapping":{
"alumno":"com.ejie.x21a.model.Alumno",
"departamento":"com.ejie.x21a.model.Departamento"
}
}
En el objeto json se envía la siguiente información:
• Los datos correspondientes a cada una de las entidades sobre las que se debe realizar el
databinding en formato json.
• Un objeto de nombre rupEntityMapping que contiene la correlación entre los nombres de los
objetos y el tipo Java.
3. La petición se mapea sobre el método del controller correspondiente. El tipo de parámetro del
parámetro sobre el que se van a crear las nuevas entidades debe ser de tipo java.util.Map:
@RequestMapping(value = "form/multientidades", method = RequestMethod.POST)
public @ResponseBody Object getFormmMultientidades(@RequestBody Map<String, Object>
multiModelMap) {
// Obtención del alumno
Alumno alumno = (Alumno)multiModelMap.get("alumno");
// Obtención del departamento
Departamento departamento =
(Departamento)multiModelMap.get("departamento");
}
El key de cada uno de los elementos del mapa y el tipo de objeto que se crea en dicho elemento se
corresponde con la configuración indicada en el objeto json rupEntityMapping.
El componente permite también en envío de múltiples entidades del mismo tipo. Las diferentes entidades se
diferenciarían mediante el nombre del parámetro:
<form id="formMultientidades" action='/multientidades' method="post">
<input type="text" name="comarca1.code" />
<input type="text" name="comarca1.descEs" />

<input type="text" name="comarca1.descEu" />
</form>
La invocación y la configuración del componente formulario sería la siguiente:
$("#formMultientidades").rup_form({
feedback:$("#feedbackMensajes"),
multimodel:{
"comarca1":"com.ejie.x21a.model.Comarca",
"comarca2":"com.ejie.x21a.model.Comarca",
"comarca3":"com.ejie.x21a.model.Comarca"
},
success:function(xhr){
// Tratamiento de la petición realizada correctamente
},
validate:{
rules:{
// Reglas de validación necesarias
}
}
});
Por su parte, el método del controller encargado de la recepción de las entidades sería el siguiente:
@RequestMapping(value = "/multientidades", method = RequestMethod.POST)
public @ResponseBody Object getFormmMultientidades(@RequestBody Map<String, Object>
multiModelMap) {
// Obtención de la entidad comarca1
Comarca comarca1 = (Comarca)multiModelMap.get("comarca1");
}
9.3. Subida de ficheros
Para realizar la subida de ficheros basta con incorporar un campo file al formulario que se va a enviar. El
componente formulario detecta que debe de gestionar la subida de un fichero y actúa en consecuencia.
La principal diferencia respecto al envío de una petición normal es que se realiza mediante una
multipart/form-data en lugar de una application/x-www-form-urlencoded.
Para llevar a cabo el envío de ficheros mediante el componente form se deben llevar a cabo los siguientes
pasos:
1. Habilitar el soporte de Spring para peticiones multipart. Por defecto Spring no tiene habilitada la
gestión de subidas de ficheros (multipart).

Para habilitarlo se debe de añadir un MultipartResolver al contexto de aplicación de Spring. Esto se
realiza editando la configuración del fichero mvc.config.xml e incluyendo la siguiente definición:
<bean id="multipartResolver" class="com.ejie.x38.util.UdaMultipartResolver" >
</bean>
Desde UDA se proporciona un MultipartResolver que permite el envío de peticiones multipart
mediante PUT.
2. Crear un formulario con un campo file mediante el cual se seleccionará el fichero a enviar:
<form id="formFichero" action='/subidaFichero' method="post">
...
...
<input type="file" id="campoFichero" name="fichero" />
...
...
</form>
3. Invocación del componente formulario.
$("#formFichero").rup_form({
});
4. Para obtener en el controller el fichero enviado se deberá de definir un parámetro del siguiente
modo. El parámetro se muestra resaltado en el ejemplo:
@RequestMapping(value="/subidaFichero", method = RequestMethod.POST)
public void subirFichero(
@ModelAttribute Alumno alumno,
@RequestParam(value="fichero", required=false) MultipartFile fichero) {
// Procesado del fichero
}
IMPORTANTE: En el caso de utilizar el navegador Internet Explorer 8, la subida de ficheros mediante
un formulario se realiza mediante el uso de iframe. Esto es debido a que la subida de ficheros
mediante peticiones AJAX no está soportada en este navegador.
La configuración que se ha de realizar para permitir la interacción correcta entre los iframes y el
resto de la infraestructura (request mappings, http error code, validaciones…) se detalla en el anexo
Anexo-Emulacion_xhr_iframes.doc

10. Interacción con otros componentes RUP
Para facilitar la gestión de los formularios de la aplicación, se ha tratado de facilitar la validación de los
campos del formulario. Para ello se ha integrado en el componente formulario el uso del componente
validación.
La configuración de las validaciones que se deben de aplicar a los campos del formulario se realiza del
mismo modo que se describe en el documento de uso del componente validación. Las opciones de
configuración del componente validación se indican en la propiedad validate del las opciones de
configuración del componente formulario.
A continuación se muestra un ejemplo de una invocación del componente formulario en el que se incluye la
configuración correspondiente a la validación de sus campos:
$("#formulario").rup_form({
url:"/formulario/guardar",
success: function(){
},
validate:{
rules:{
"nombre":{required:true},
"apellido1":{required:true}
}
}
});
La configuración referente al proceso de validación se detalla en la guía de uso del componente RUP
validación.

UDA-Componentes RUP. Formulario

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Similar a UDA-Componentes RUP. Formulario

Similar a UDA-Componentes RUP. Formulario (20)

Más de Ander Martinez

Más de Ander Martinez (16)

Último

Último (20)

UDA-Componentes RUP. Formulario