UDA-Componentes RUP. Validación

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 – Validación

Fecha: 13/03/2014 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 – Validación ii/18

Control de documentación

Título de documento: Componentes RUP – Validación

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ñadida información importante en el apartado integración con UDA.

2.1.1 09/01/2013 Añadido el evento rupValidate_formValidationError

2.4.0 22/11/2013 Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.

2.4.1 13/03/2014 Correcciones en el apartado de invocación.

Cambios producidos desde la última versión

Correcciones en el apartado de invocación.

Control de difusión

Responsable: Ander Martínez

Aprobado por:

Firma: Fecha:

Distribución:

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Validación iii/18

Componentes RUP – Validación iv/18

Contenido

Capítulo/sección Página

1. Introducción 5

2. Ejemplo 5

3. Casos de uso 5

4. Infraestructura 6

4.1. Ficheros 6

4.2. Dependencias 6

4.3. Versión minimizada 7

5. Invocación 7

6. Parámetros 8

7. Funciones 9

8. Eventos 10

9. Validaciones 10

10. Sobreescritura del theme 12

11. Personalización 13

11.1. Visualización errores 13

11.2. Validaciones propias 13

11.3. Sobreescritura validaciones 14

11.4. Personalización de los mensajes 14

12. Integración con UDA 16

13. Interacción con otros componentes RUP 16

Componentes RUP – Validación 5/18

1. Introducción

La descripción del Componente Validación , visto desde el punto de vista de RUP, es la siguiente:

Permite al usuario validar los datos introducidos en los campos que se presentan en la aplicación.

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 realizar validaciones en cliente de los campos de formulario.


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.validate-x.y.z.js

Ruta theme: rup/basic-theme/

Fichero CSS del theme: theme.rup.validate-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.validate.js

• rup.validate-2.0.0.js

• theme.rup.validate-2.0.0.css


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 validación se invoca sobre un formulario existente en la jsp. El formulario contendrá los campos que se desean validar.

Un ejemplo de un formulario que se desee validar es el siguiente:

<form id ="formValidaciones" action ="/form">

< label for ="campoObligatorio">Campo Obligatorio </ label >

<input type ="text" name="campoObligatorio" i d="campoObligatorio" />

<label for ="dni" >Dni </ label >

<input type ="text" name="dni" id ="dni" />

</form>

Este formulario dispone dos campos que deben ser validados. El primero de ellos deberá ser un campo obligatorio y el segundo además de ser también obligatorio, deberá cumplir el formato de un dni válido. La invocación correspondiente que deberemos realizar al componente validación será la siguiente:

var properties={ rules:{ "campoObligatorio" :{required: true}, "dni" :{required: true,dni: true }

};

$( "#formValidaciones" ).rup_validate(properties);


Como ya se profundizará mas adelante, mediante la propiedad rules se indicará para cada campo (identificado mediante su el valor de su propiedad name) que validaciones se deben de realizar.

6. Parámetros

A continuación se muestran los posibles parámetros de configuración que recibe el componente.

• debug : Activa el modo debug. En caso de estar activado el formulario no se envía el formulario y los errores de ejecución que se hayan producido se visualizan en la consola. Requiere Firebug o Firebug lite. Por defecto a false.

• submitHandler: Método callback utilizado para capturar el evento submit cuando el formulario es válido. Reemplaza el submit por defecto. Es el método utilizado para realizar un submit mediante AJAX después de ser validado:

• invalidHandler: Método callback que se ejecuta cuando un formulario presenta errores de validación.

• ignore: Selector jQuery que identifica los elementos del formulario que van a ser ignorados al realizarse las validaciones.

• messages: Utilizado para indicar mensajes propios para las validaciones. Estos se especifican mediante pares de clave/valor. La clave es el nombre del elemento mientras que el valor es el texto que se ha de mostrar en caso de producirse un error en la validación.

• groups: Se utiliza para realizar agrupamientos de mensajes de error.

• onsubmit: Determina si se valida el formulario al realizarse el submit. Marcar como false para realizar las validaciones mediante el resto de eventos. Por defecto a true.

• ofocusout: Determina si se realiza la validación de los campos (excepto los checkbox y radio) al lanzarse los eventos blur. Estas validaciones se realizan únicamente una vez que un campo ha sido marcado como inválido. Por defecto a true.

• okeyup: Determina si se realiza la validación de los campos (excepto los checkbox y radio) al lanzarse los eventos keyup. Las validaciones se realizan únicamente una vez que un campo ha sido marcado como inválido. Por defecto a true.

• onclick: Determina si se realizan las validaciones de los checkbox y radio al realizar un click sobre los mismos. Por defecto a true.

• focusInvalid: Posiciona el foco en el último campo activo o en el primer campo inválido la realizarse la validación de los campos. En caso de encontrarse el foco en un campo al realizarse la validación se mantiene en dicho campo. En caso de no encontrarse el foco en un campo, se posicionará en el primer campo inválido existente. Por defecto a true.

• focusCleanup: En caso de activarse, elimina el errorClass correspondiente y oculta los mensajes de error de los campos que reciben el foco. Evitar utilizar esta propiedad en conjunción con focusInvalid. Por defecto a false.


• meta: En caso de utilizar metainformación en los campos que sea utilizada por otros plugins, es posible indicar un identificador para envolver la metadata correspondiente al el componente validate dentro de un objeto propio.

• errorClass: Determina el nombre del class que va a aplicarse a los campos que presenten errores de validación. Por defecto error.

• validClass: Determina el nombre del class que va a aplicarse a los campos que han sido validados y no presenten errores. Por defecto valid.

• errorElement: Determina el tipo del elemento que va a utilizarse para generar los mensajes de error. Por defecto label.

• wrapper: Recubre los mensajes de error con el elemento especificado. Util en conjunción la propiedad errorLabelContainer para crear listado de errores.

• errorLabelContainer: Determina el objeto contenedor en el que se van a mostrar los mensajes de error.

• errorContainer: Determina un contenedor adicional para los mensajes de error.

• showErrors: Función callback para realizar un tratamiento personalizado de los errores de validación. La función recibe como primer parámetro un mapa con los errores de validación y una lista de errores como segundo.

• errorPlacement: Función de callback que permite personalizar el lugar en el que se posicionarán los mensajes de error. Como primer argumento recibe el label de error como un objeto jQuery. Como segundo atributo recibe el elemento inválido. Por defecto se posiciona el label de error después del elemento inválido.

• highlight: Función de callback para determinar como se debe resaltar los campos inválidos.

• unhighlight: Función de callback para restaurar los cambios realizados por la función indicada en la propiedad highlight.

• ignoreTitle: Determina si se evita el obtener los mensajes a partir del atributo title. Por defecto false.

7. Funciones

A continuación se detallan las diferentes funciones que integran el componente validación:

• destroy: elimina los objetos jQuery asociados al elemento identificado por el selector, durante el proceso de creación del componente validación:

$( selector ) .rup_validate ( "destroy" );


8. Eventos

A continuación se detallan las diferentes eventos lanzados por el componente:

• rupValidate_formValidationError: Este evento es lanzado cuando se produce alguna violación entre las reglas de validación especificadas para ser aplicadas sobre los campos del formulario. Un ejemplo para definir un capturador para el evento sería el siguiente:

$( selector ) .on ( "rupValidate _formValidationError", function (event){

});

9. Validaciones

• required: El campo es obligatorio. Es posible indicar expresiones de dependencia y funciones callback para determinar una dependencia entre la necesidad de validarse como requerido o no.

• minlength : Se requiere una longitud mínima.

• maxlength : El campo no debe superar una longitud máxima.

• rangelength : El campo debe tener una longitud comprendida entre el rango indicado.

• min : El valor existente en el campo debe ser igual o mayor que el valor mínimo indicado.

• max : El valor existente en el campo debe ser igual o menor que el valor máximo indicado.

• range : El valor existente en el campo debe estar comprendido entre el rango indicado.

• email : El campo debe contener un email válido.

• url : El campo debe contener una url válida.

• date : El campo debe contener una fecha válida.

• number : El campo debe contener un número decimal válido.

• digits : El campo debe contener únicamente caracteres numéricos.

• creditcard : El contenido del campo debe de cumplir un formato de tarjeta de crédito válida.

• accept : El campo debe de contener el nombre de un fichero con una extensión determinada.

• equalTo : El contenido de ambos campos debe de ser el mismo.

• dni : El campo debe de contener un dni válido.

• maxWords : El contenido del campo debe de estar formado por un número de palabras igual o menor al indicado.


• minWords : El contenido del campo debe de estar formado por un número de palabras igual o mayor al indicado.

• rangeWords : El contenido del campo debe de estar formado por un número de palabras comprendido entre el rango indicado.

• letterswithbasicpunc : El campo debe contener únicamente letras y símbolos de puntuación.

• alphanumeric : El campo debe contener únicamente caracteres alfanuméricos.

• lettersonly : El campo debe contener únicamente letras.

• nowhitespace : El campo no debe de contener espacios en blanco.

• integer : El campo debe contener un número entero.

• pattern : El contenido del campo debe de cumplir el formato correspondiente al patrón indicado.

Un ejemplo de la configuración de las diferentes reglas de validación sería el siguiente:

$( "#formValidaciones" ).rup_validate(

rules:{ "campoObligatorio1" :{required: true}, "campoObligatorio2" :{required: "#esObligatorio:checked" }, "campoObligatorio3" :{required: function(){ return $( "#diaObligatorio" ).val() > 5; }}, "longitudMinima" :{minlength:8}, "longitudMaxima" :{maxlength:20}, "longitudIntervalo" :{rangelength:[8,20]}, "valorMinimo" :{min:10}, "valorMaximo" :{max:30}, "valorIntervalo" :{range:[10,30]}, "validacionEmail" :{email: true}, "validacionUrl" :{url: true}, "validacionFecha" :{date: true}, "validacionFechaISO" :{dateISO: true}, "numeroDecimal" :{number: true}, "soloDigitos" :{digits: true}, "tarjetaCredito" :{creditcard: true}, "extension" :{accept: "xls|csv" }, "clave_confirmar" :{ equalTo: "#clave" }, "dni" :{dni: true}, "palabrasMaximo" :{maxWords:6}, "palabrasMinimo" :{minWords:2}, "palabrasIntervalo" :{rangeWords:[2,6]}, "letrasYPuntuacion" :{letterswithbasicpunc: true}, "alfanumerico" :{alphanumeric: true}, "soloLetras" :{lettersonly: true}, "sinEspacios" :{nowhitespace: true}, "entero" :{integer: true}, "patron" :{pattern: '\\d' } } }


10. Sobreescritura del theme

El componente validación se presenta con una apariencia visual definida en el fichero de estilos theme.rup.validate-x.y.z.css.

Si se quiere modificar la apariencia del componente, se recomienda redefinir el/los estilos necesarios en un fichero de estilos propio de la aplicación situado dentro del proyecto de estáticos (codAppStatics/WebContent/codApp/styles).

Los estilos del componente se basan en los estilos básicos de los widgets de jQuery UI, con lo que los cambios que se realicen sobre su fichero de estilos manualmente o mediante el uso de la herramienta Theme Roller podrán tener repercusión sobre todos los componentes que compartan esos mismos estilos (pudiendo ser el nivel de repercusión general o ajustado a un subconjunto de componentes).


11. Personalización

El componente validación permite realizar una serie de personalizaciones sobre las validaciones, estilos, y mensajes de error mostrados.

11.1. Visualización errores

Mediante las propiedades de configuración que ofrece el componente es posible personalizar el modo en el que se muestran los errores de validación.

$( "#formValidaciones" ).rup_validate({ feedback:$( "#feedbackErroresValidaciones" ), liveCheckingErrors: false, showFieldErrorAsDefault: true, showErrorsInFeedback: true, showFieldErrorsInFeedback: true, rules:{

"campoObligatorio" :{required: true}, "dni" :{required: true,dni: true } });

El significado de cada una de las propiedades se especifica en el apartado Propiedades.

En caso de que la aplicación necesite de un grado de personalización mayor de los errores de validación deberá de extender las funciones de gestión de errores que proporciona el componente.

11.2. Validaciones propias

El componente permite la creación de validaciones propias que puedan ser utilizadas junto con las definidas por defecto.

La creación de la nueva regla de validación se realiza mediante la función addMethod del plugin subyacente jquery.validator.

jQuery.validator.addMethod(name, method, message);

El método recibe los siguientes parámetros:

• name: Nombre identificativo de la validación.

• method: Función javascript que contiene la implementación necesaria para llevar a cabo la validación.

• message: Parámetro opcional. Permite especificar un mensaje de error de validación al margen de los definidos en los ficheros de recursos de i18n.


A continuación se muestra un ejemplo de creación de una regla de validación personalizada. En este caso se desea validar que el valor introducido en un campo sea un número par:

jQuery.validator.addMethod( "par" , function(value, element, params) { return this.optional(element) || (value%2===0);

});

Para hacer uso de la validación de deberá de invocar al componente indicando para el campo que queremos validar el uso de la nueva validación:

$( "#formValidaciones" ).rup_validate({

rules:{

"nameCampo" :{par: true}

}

});

11.3. Sobreescritura validaciones

Del mismo modo que se realiza la creación de una nueva regla de validación, es posible sobrescribir la implementación de las reglas de validación ya existentes.

El procedimiento es el mismo que el que se realiza para añadir una nueva regla. Este sería un ejemplo de sobreescritura de la reagla de validación dni:

jQuery.validator.addMethod( "dni" , function(value, element) { // Nueva implementación });

11.4. Personalización de los mensajes

Los mensajes de error de las validaciones se encuentran definidos en los ficheros de recursos de rup. Para cada menaje de error existe su versión idiomática correspondiente.

"rup_validate":{

"messages":{ "required": "Campo obligatorio.", "remote": "Por favor, rellena este campo.", "email": "Por favor, escribe una dirección de cor reo válida", "url": "Por favor, escribe una URL válida.", "date": "Por favor, escribe una fecha válida.", "dateISO": "Por favor, escribe una fecha (ISO) vá lida.",


"number": "Por favor, escribe un número entero vá lido.", "digits": "Por favor, escribe sólo dígitos.", "creditcard": "Por favor, escribe un número de ta rjeta válido.", "equalTo": "Por favor, escribe el mismo valor de nuevo.", "accept": "Por favor, escribe un valor con una ex tensión aceptada.", "maxlength": "Por favor, no escribas más de {0} c aracteres.", "minlength": "Por favor, no escribas menos de {0} caracteres.", "rangelength": "Por favor, escribe un valor entre {0} y {1} caracteres.", "range": "Por favor, escribe un valor entre {0} y {1}.", "max": "Por favor, escribe un valor menor o igual a {0}.", "min": "Por favor, escribe un valor mayor o igual a {0}.", "dni": "Por favor, introduzca un dni válido.", "maxWords": "Por favor, no escribas mas de {0} pa labras.", "minWords": "Por favor, no escribas menos de {0} palabras.", "rangeWords": "Por favor, escribe un valor entre {0} y {1} palabras.", "letterswithbasicpunc": "Por favor, introduzca ún icamente letras y signos de puntuación.", "alphanumeric": "Por favor, introduzca letras, nú meros, espacios o guiones bajos.", "lettersonly": "Por favor, introduzca únicamente letras.", "nowhitespace": "Por favor, no introduzca espacio s en blanco.", "integer": "Por favor, introduzca un número enter o positivo o negativo.", "pattern": "El formato no es válido" }

}

Estos mensajes pueden ser modificados definiendo en los ficheros de internacionalización de la aplicación un objeto json con la misma estructura para sustituir a continuación los mensajes:

"rup_validate":{

"messages":{ ...

... }

}

Para sustituir los mensajes iniciales se deberá de ejecutar el siguiente código

$.extend($.validator.messages, $.rup.i18n.app.rup_v alidate.messages);

Para una personalización de los errores de validación más específica, que no sea definida a nivel global para todas las existentes en la aplicación, se puede indicar un mensaje de error personalizado para un campo concreto:

$( "#formValidaciones" ).rup_validate({ messages:{ "password_confirm" :$.rup.i18n.app.validaciones.password_confirm, "email_confirm" :$.rup.i18n.app.validaciones.email_confirm }, rules:{ "password" :{required: true,minlength:4},


"password_confirm" : { equalTo: "#password" }, "email" :{email: true}, "email_confirm" : { equalTo: "#email" }, } });

Se deberá de indicar en los ficheros de i18n de la aplicación los mensajes que se deberán de mostrar. Para este ejemplo se deberá de incluir las siguientes entradas en los ficheros /xxxStatics/WebContent/xxx/resources/xxxYyy.i18n_zz.json:

"validaciones":{

"password_confirm":"Las contraseñas no coinciden", "email_confirm":"Los correos introducidos no coinc iden" },

12. Integración con UDA

El componente que nos ocupa, está ligado al subsistema de validaciones de UDA.

La interacción entre ambos se detalla en el documento Anexo-Gestión_de_validaciones.doc

IMPORTANTE: En el caso de utilizar el navegador Int ernet 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. En estos casos la gestión de errores de validaciones realizadas en el servidor d e aplicaciones, no puede hacer un uso correcto de los códigos de error http para la gestión de los mi smos.

La configuración que se ha de realizar para permiti r 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

13. Interacción con otros componentes RUP

En este apartado se va a detallar la interacción del componente validación con el resto de componentes RUP.

Componente RUP formulario


El componente de validación está estrechamente relacionado con el componente formulario. Esto es debido a que la mayor parte de las validaciones que se realizan en las aplicaciones, están relacionadas con la validación de datos introducidos mediante un formulario.

Para facilitar la configuración de ambos componentes se permite especificar los parámetros del componente de validaciones junto con los del formulario.

$( "#validacionFormulario" ).rup_form({ feedback:$( "#feedbackErroresValidaciones" ), url:$.rup.CTX_PATH+ "/patrones/validacion/servidor" , validate: {

messages:{ "password_confirm":$.rup.i18n.app.validaciones.password_confirm,

"email_confirm":$.rup.i18n.app.validaciones.email_confirm }, rules:{ "password":{required:true,minlength:4}, "password_confirm": { equalTo: "#password"

}, "email":{email: true}, "email_confirm": { equalTo: "#email" }

} } });

Como se puede observar, la configuración del componente validación se especifica mediante la propiedad validate del componente formulario. La configuración es exactamente la misma que la especificada en el caso de utilizar el componente de manera independiente.

El componente formulario invocará al componente validación durante el proceso de inicialización. Una vez configurado, se podrá hacer uso de las funciones y eventos que proporciona el componente validación.

Resto componentes RUP

El componente validación está preparado para realizar validaciones sobre cualquier componente RUP. Para validar campos que han sido inicializados como componentes RUP se deberá de proceder del mismo modo que con controles HTML comunes.

En el siguiente ejemplo se muestra el uso del patrón validación sobre unos componentes RUP:

[validaciones.jsp]

<form:form id ="formValidaciones">

...

... <input id ="autocomplete" name="autocomplete" />

...

... <select id ="comboAbueloRemoto" name="provincia" class ="rup-combo"></ select >

...

... <select id ="comboPadreRemoto" name="comarca" class ="rup-combo"></ select >

...

... <select id ="comboHijoRemoto" name="localidad" class ="rup-combo"></ select >


...

... <input id ="fecha" name="fecha" />

...

... <input id ="fechaHora" name="fechaHora" />

...

... <input type ="submit" value ="Validar formulario" /> </ form:form >

[validaciones.js]

$( "#autocomplete" ).rup_autocomplete({

// Inicialización del componente rup_autocomplete }); $( "#comboAbueloRemoto" ).rup_combo({

// Inicialización del componente rup_combo }); $( "#comboPadreRemoto" ).rup_combo({

// Inicialización del componente rup_combo }); $( "#comboHijoRemoto" ).rup_combo({

// Inicialización del componente rup_combo }); $( "#fecha" ).rup_date({

// Inicialización del componente rup_fecha }); $( "#fechaHora" ).rup_date({

// Inicialización del componente rup_fecha });

$( "# formValidaciones" ).rup_form({ feedback:$( "#feedbackErroresValidaciones" ), url:$.rup.CTX_PATH+ "/patrones/validacion/servidor" , validate: { rules:{ "autocomplete" :{required: true }, "provincia" :{required: true }, "comarca" :{required: true }, "localidad" :{required: true }, "fecha" :{required: true }, "fechaHora" :{required: true }

} } });

UDA-Componentes RUP. Validación

Technology

Transcript of UDA-Componentes RUP. Validación