UDA-Componentes RUP. Hora (v2.1.0 deprecado)

Correcciones en los números de versión de ficheros.

Actualización de las versiones de las librerías yacentes.

Añadido el apartado Integración con UDA.

Nuevos métodos getRupValue y setRupValue para la interacción con los demás componentes RUP.

Actualizado el apartado Integración con UDA.

Cambios de formato y correcciones ortográficas.

Actualización de las versiones de las librerías subyacentes.

Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.

Cambios producidos desde la última ve rsión

Se distribuye la versión minimizada de los ficheros javascript y de estilos de RUP.

UDA - Utilidades de Desarrollo de Aplicaciones

Componentes RUP – Hora

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

UDA – Utilidades de desarrollo de aplicaciones by EJIE is licensed under a Creative Commons Reconocimiento-NoComercial-CompartirIgual 3.0 Unported License..

Componentes RUP – Hora ii/16

Componentes RUP – Hora iii/16

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

4.3. Versión minimizada 6

5. Invocación 6

6. Parámetros 6

7. Funciones 9

8. Eventos 11

9. Interacción con teclado 12

10. Sobreescritura del theme 13

11. Integración con UDA 15

Componentes RUP – Hora 4/16

1. Introducción

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

El usuario puede introducir y seleccionar una hora tanto de forma manual como visual, moviéndose fácilmente por las horas y los minutos, recibiendo ayudas y sugerencias para minimizar las posibilidades de introducir una hora incorrecta.

2. Ejemplo

Se muestra a continuación una captura de un ejemplo típico del componente:

3. Casos de uso

Se recomienda el uso del componente:

• Cuando el usuario tenga que introducir una hora y se quiera ofrecer flexibilidad para escribirla manualmente o seleccionándola de un calendario.


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

Ruta theme: rup/basic-theme/

Fichero CSS del theme: theme.rup.time-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 medieante 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/

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-ui.timepicker.js

• rup.base-x.y.z.js

• rup.time-x.y.z.js

• theme.rup.time-x.y.z.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

Este componente se invocará mediante un selector que indicará todos los elementos sobre los que se va a aplicar el patrón Fecha. Por ejemplo:

$("#id_input").rup_time (properties);

Donde el parámetro “properties” es un objeto (var properties = {};) o bien directamente la declaración de lo valores directamente. Sus posibles valores se detallan en el siguiente apartado.

6. Parámetros

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

• disabled : indica si el componente debe aparecer deshabilitado o no. Su valor por defecto es false.

• labelMaskId: identificador del label que contendrá la máscara que indica el formato de la hora.

• timeFormat: formato en el que se muestra la hora. El valor por defecto es hh:mm. Los posibles modificadores son:

o h: modificador relativo a las horas. En caso de querer que las horas inferiores a 10 muestren el 0 deberá incluirse por duplicado (hh).

o m: modificador relativo a los minutos. En caso de querer que las horas inferiores a 10 muestren el 0 deberá incluirse por duplicado (mm).

o s: modificador relativo a los segundos. En caso de querer que las horas inferiores a 10 muestren el 0 deberá incluirse por duplicado (ss).


• hour: valor con el que se carga inicialmente las horas del componente. El valor por defecto es 0.

• minute: valor con el que se carga inicialmente los minutos del componente. El valor por defecto es 0.

• second: valor con el que se carga inicialmente los segundos del componente. El valor por defecto es 0.

• hourMin: valor mínimo seleccionable en las horas del componente. El valor por defecto es 0.

• hourMax: valor máximo seleccionable en las horas del componente. El valor por defecto es 59.

• minuteMin: valor mínimo seleccionable en los minutos del componente. El valor por defecto es 0.

• minuteMax: valor máximo seleccionable en los minutos del componente. El valor por defecto es 59.

• secondMin: valor mínimo seleccionable en los segundos del componente. El valor por defecto es 0.

• secondMax: valor mínimo seleccionable en los segundos del componente. El valor por defecto es 59.

• showHour: indica si se muestran o no las horas. El valor por defecto es true.

• showMinute: indica si se muestran o no los minutos. El valor por defecto es true.

• showSecond: indica si se muestran o no los segundos. El valor por defecto es false.

• stepHour: establece el incremento de la barra de scroll relativa a las horas. El valor por defecto es 1.

• stepMinute: establece el incremento de la barra de scroll relativa a los minutos. El valor por defecto es 1.

• stepSecond: establece el incremento de la barra de scroll relativa a los segundos. El valor por defecto es 1.

• hourGrid: indica el intervalo de los números que aparecen bajo la barra de scroll relativa a las horas. Al pinchar sobre dichos números se selecciona ese valor. El valor por defecto es 0 (desactivado).

• minuteGrid: indica el intervalo de los números que aparecen bajo la barra de scroll relativa a los minutos. Al pinchar sobre dichos números se selecciona ese valor. El valor por defecto es 0 (desactivado).


• secondGrid: indica el intervalo de los números que aparecen bajo la barra de scroll relativa a los segundos. Al pinchar sobre dichos números se selecciona ese valor. El valor por defecto es 0 (desactivado).

• showTime: determina si se desea mostrar o no la fecha en el desplegable. El valor por defecto es true.

• ampm: determina si en lugar de mostrar la hora en formato 0-24 se muestra con el literal am/pm. El valor por defecto es false.

• showButtonPanel: indica si se muestran los botones de la parte inferior (ahora y cerrar). Su valor por defecto es false.

• mask: texto empleado para la máscara de la fecha. Su valor por defecto se obtiene del fichero de idioma.

• buttonText: texto alternativo de la imagen que se muestra junto al campo de la fecha. Su valor por defecto se obtiene del fichero de idioma.

• closeText: texto a mostrar en el botón que se muestra en el panel inferior (requiere el activarlo mediante el atributo showButtonPanel) para cerrar el desplegable. Su valor por defecto se obtiene del fichero de idioma.

• currentText: texto a mostrar en el botón que se muestra en el panel inferior (requiere el activarlo mediante el atributo showButtonPanel) para seleccionar la hora actual en el desplegable. Su valor por defecto se obtiene del fichero de idioma.

• timeOnlyTitle: texto que aparece en la cabecera del desplegable. Su valor por defecto se obtiene del fichero de idioma.

• timeText: texto que aparece delante de la hora seleccionada (en caso de que esté activo el atributo showTime). Su valor por defecto se obtiene del fichero de idioma.

• hourText: texto que aparece delante de la barra de scroll de selección de horas. Su valor por defecto se obtiene del fichero de idioma.

• minuteText: texto que aparece delante de la barra de scroll de selección de minutos. Su valor por defecto se obtiene del fichero de idioma.

• secondText: texto que aparece delante de la barra de scroll de selección de segundos. Su valor por defecto se obtiene del fichero de idioma.

Para facilitar la manipulación de horas, el fichero “rup.utils” incluye la función createTime (hour, minute, second) que devuelve un objeto date. Por ejemplo:

$. rup_utils . createTime ( 14, 50, 20)


7. Funciones

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

• destroy: elimina el componente de la pantalla. En caso de tener máscara también se restaura el label con un texto vacío. A continuación se muestra un ejemplo de cómo invocar la función:

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

• disable: deshabilita el componente en pantalla no pudiendo introducirse ninguna hora ni se despliega el calendario. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "disable" );

• enable: habilita el componente permitiendo introducir la hora tanto mediante teclado como mediante el desplegable. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "enable" );

• isDisabled: indica si el componente se encuentra deshabilitado o no. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "isDisabled" );

• hide: oculta el desplegable para seleccionar una hora. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "hide" );

• show: muestra el desplegable para seleccionar una hora. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "show" );

• getTime: devuelve la hora seleccionada, si no se ha seleccionado nada devuelve vacío. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "getTime" );

• setTime: establece la hora del componente. El parámetro debe ser un objeto date. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "setTime", date );

• refresh: refresca el calendario desplegado por si ha habido algún cambio. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "refresh" );


• options: permite modificar alguno de los atributos del componente pasando el nombre de la propiedad y su valor. A continuación se muestra un ejemplo de cómo invocar la función:

$( selector ) .rup_time ( "options", optionName, value );

• getRupValue: método utilizado para obtener el valor del componente. Este método es el utilizado por el resto de componentes RUP para estandarizar la obtención del valor.

$( selector ) .rup_time ( "getRupValue" );

• setRupValue: método utilizado para asignar el valor al componente. Este método es el utilizado por el resto de componentes RUP para estandarizar la asignación del valor.

$( selector ) .rup_time ( "setRupValue",value );


8. Eventos

A continuación se detallan los eventos asociados al componente:

• onSelect: permite asociar una función que se ejecutará cuando se modifique alguno de los valores del desplegable (hora, minutos o segundos). Los parámetros recibidos son la hora seleccionada (texto) y la instancia del componente. La configuración se realiza de la siguiente manera:

$( selector ) .rup_time ({ onSelect: function(dateText, inst){...} });

• onClose: permite asociar una función que se ejecutará cuando se oculte el desplegable. Los parámetros recibidos son la hora seleccionada (texto) y la instancia del componente. La configuración se realiza de la siguiente manera:

$(selector).rup_time ({ onClose: function(dateText, inst){...} });


9. Interacción con teclado

La interacción natural con el componente es mediante el ratón, pero se han añadido la posibilidad de manipular los valores mediante el teclado para agilizar su uso lo que ahorra mucho tiempo a los usuarios avanzados.

Cuando el campo asociado al componente recibe el foco se muestra el desplegable. En este momento si se introduce una hora (siguiendo el formato especificado) utilizando los números del teclado, el componente actualiza sus barras de scroll con el valor introducido manualmente. Mediante flechas de dirección (←, ↑, →, ↓) se puede desplazar el cursor a través del campo de hora para modificarla, además de borrar ciertos valores mediante las teclas suprimir y tecla de retroceso (backspace). Con la tecla escape se cerrará el desplegable.

Existen unos atajos de teclado para poder manipular las barras de scroll sin tener que utilizar los números del teclado que son los siguientes:

o CTRL + � : Disminuye la hora

o CTRL + � : Aumente la hora

o CTRL + SHIFT + � : Disminuye los minutos

o CTRL + SHIFT + � : Aumenta los minutos

o CTRL + SHIFT + ALT + � : Disminuye los segundos

o CTRL + SHIFT + ALT + � : Aumenta los segundos


10. Sobreescritura del theme

El componente hora se presenta con una apariencia visual definida en el fichero de estilos theme.rup.time-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).

Ejemplo base de la estructura generada por el componente (estructura interna que forma el desplegable, no se incluye el input sobre el que se aplica el componente):

<div class ="ui-timepicker-div" id ="ui-timepicker-div-hora"> <div class ="ui-widget-header ui-helper-clearfix ui-corner-all"> <div class ="ui-datepicker-title">Seleccione Tiempo </ div >

</ div > <dl >

dt class ="ui_tpicker_time_label" id ="ui_tpicker_time_label_hora"> Tiempo

</ dt > <dd class ="ui_tpicker_time" id ="ui_tpicker_time_hora">

08:00:00 </ dd>

<dt class ="ui_tpicker_hour_label" id ="ui_tpicker_hour_label_hora"> Hora

</ dt > <dd class ="ui_tpicker_hour ui-slider ui-slider-horizontal ui-widget

ui-widget-content ui-corner-all" id ="ui_tpicker_hour_hora"> <a style =" left : 34.7826%;" class ="ui-slider-handle ui-state-

default ui-corner-all" href ="#"></ a> </ dd> <dt class ="ui_tpicker_minute_label"

id ="ui_tpicker_minute_label_hora"> Minuto

</ dt > <dd class ="ui_tpicker_minute ui-slider ui-slider-horizontal ui-

widget ui-widget-content ui-corner-all" id ="ui_tpicker_minute_hora"> <a style =" left : 0%;" class ="ui-slider-handle ui-state-default

ui-corner-all" href ="#"></ a> </ dd>

<dt class ="ui_tpicker_second_label" id ="ui_tpicker_second_label_hora">

Segundo </ dt >


<dd class ="ui_tpicker_second ui-slider ui-slider-horizontal ui- widget ui-widget-content ui-corner-all" id ="ui_tpicker_second_hora">

<a style =" left : 0%;" class ="ui-slider-handle ui-state-default ui-corner-all" href ="#"></ a>

</ dd> </ dl > </ div > <div class ="ui-datepicker-buttonpane ui-widget-content">

<button type ="button" class ="ui-datepicker-current ui-state-default ui-priority-secondary ui-corner-all" onclick ="DP_jQuery_1301919639240.datepicker._gotoToday('#ho ra');" >

Ahora </ button >

<button type ="button" class ="ui-datepicker-close ui-state-default ui- priority-primary ui-corner-all" onclick ="DP_jQuery_1301919639240.datepicker._hideDatepicker ();" >

Cerrar </ button >

</ div > NOTA: El componente genera adicionalmente una estructura para la manipulación de fechas combinada con la manipulación de horas que no se utiliza y por ello se ha omitido. Además la estructura presentada podría variar algo en función de los atributos indicados en la configuración.


11. Integración con UDA

Para facilitar la serialización/deserialización de los datos entre los objetos java y los componentes hora, desde UDA se proporcionan las siguientes clases. Estas clases definen tanto serializadores como deserializadores para el componente Jackson utilizado en UDA.

Estas clases son utilizadas por las anotaciones @JsonSerialize y @JsonDeserialize de Jackson. Al incluir estas anotaciones en los métodos setter y setter de los model se determina el modo en que Jackson va a realizar la serialización y deserialización de estos tipos de datos.

• com.ejie.x38.control.JsonTimeSerializer: Realiza la serialización de un tipo de dato Date en su representación json correspondiente. El valor json resultante contiene la información de la hora. (HH:mm:ss).

En el proceso de serialización se tiene en cuenta el idioma utilizado por el usuario en la aplicación para utilizar el formato correcto de la hora. Un ejemplo de uso sería el siguiente:

@JsonSerialize (using = JsonTimeSerializer. class) public Date getHora() { return this. hora ;

}

• com.ejie.x38.control.JsonDateDeserializer: Realiza la deserialización de un objeto json que contiene la representación de una fecha válida en un tipo de dato Date.

El objeto json debe contener una hora válida de acuerdo al formato definido por la locale correspondiente al idioma utilizado en la aplicación por el usuario. Este formado solo comprenderá la parte de la hora ignorando la fecha. (HH:mm:ss).

Un ejemplo de uso sería el siguiente:

@JsonDeserialize (using = JsonTimeDeserializer. class) public void setFechaBaja(Date hora) { this.hora = hora;

}

UDA-Componentes RUP. Hora (v2.1.0 deprecado)

Technology

Transcript of UDA-Componentes RUP. Hora (v2.1.0 deprecado)