UDA - Utilidades de Desarrollo de Aplicaciones

Componentes RUP – Diálogo

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 – Diálogo ii/12

Control de documentación

Título de documento: Componentes RUP – Diálogo

Histórico de versiones

Código: Versión: Fecha: Resumen de cambios:

1.0.0 06/06/2011 Primera versión.

1.0.1 18/07/2011 Correcciones en los números de versión de ficheros, inclusión de ajaxOptions.

1.1.0 14/09/2011

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

Añadido el apartado Integración con UDA.

2.0.0 11/07/2012 Cambios de formato y correcciones ortográficas.

Añadido de algunas funciones de gestión nuevas.

2.1.0 18/09/2012 Actualización de las versiones de las librerías JavaScript subyacentes.

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:

Componentes RUP – Diálogo iii/12

Nombre archivo:

Localización:

Componentes RUP – Diálogo iv/12

Contenido

Capítulo/sección Página

1. Introducción 5

2. Ejemplo 5

3. Casos de uso 5

4. Infraestructura 5

4.1. Ficheros 5

4.2. Dependencias 6

4.3. Versión minimizada 6

5. Invocación 6

6. Propiedades 7

6.1. Botones 9

7. Métodos 10

8. Eventos 11

9. Sobreescritura del theme 11

10. Internacionalización (i18n) 12

11. Integración con UDA 12

Componentes RUP – Diálogo 5/12

1. Introducción

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

Permite lanzar un subproceso o un mensaje de confirmación dentro de un proceso principal sin salirse de este. Es una evolución del patrón mensaje.

2. Ejemplo

Se muestra a continuación una maquetación típica del componente:

3. Casos de uso

El uso de las ventanas modales debe ser únicamente en ocasiones muy concretas; tales como:

• Subprocesos dentro de un proceso principal

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

Ruta theme: rup/basic-theme/

Fichero CSS del theme: theme.rup.message-x.y.z.css

Componentes RUP – Diálogo 6/12

NOTA: Como se observa, los estilos se basan en el f ichero de estilos del componente message.

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.6.2.

• jQuery 1.6.2: 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.16.

• jQuery UI 1.8.16: http://jqueryui.com/

Los ficheros necesarios para el correcto funcionamiento del componente son:

• jquery-1.6.2.js

• jquery-ui-1.8.16.custom.js

• jquery-ui-1.8.16.custom.css

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

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

• theme.rup.message-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á el elemento capa (div) que envuelve el contenido a mostrar o bien directamente sobre jQuery invocando la función del componente. Por ejemplo:

• Usando una capa

$("#selector").rup_dialog(properties);

Componentes RUP – Diálogo 7/12

• Obteniendo el contenido directamente (texto) o vía AJAX:

$(document).rup_dialog(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.

La estructura de una ventana modal debe consistir en una capa semitransparente que deje ver ligeramente el proceso principal que se está llevando a cabo para dejar claro al usuario que sigue trabajando en ese proceso. Sobre la capa semitransparente se debe añadir la capa con el contenido del subproceso. Debe constar, además del contenido en si mismo, un aspa de cierre, un enlace para cancelar la acción y un botón destacado para la ejecución de la acción.

La funcionalidad implementada en los diálogos permite que el desarrollador decida si el diálogo a mostrar debe ser realmente modal o no. Del mismo modo se permite configurar el tamaño de las ventanas, si se pueden redimensionar, arrastrar…

6. Propiedades

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

• url : String. url de donde se obtendrá el contenido del diálogo.

• type : String. Propiedad que establece el tipo de diálogo a mostrar. Sus valores pueden ser:

o $.rup.dialog.DIV: Hara uso del div que se le pasa en el selector, mostrando su contenido en el cuerpo del diálogo.

o $.rup.dialog.TEXT. Creara un div interno y se le añadirá el texto que recibe en la configuración del componente como message.

o $.rup.dialog.AJAX: Creara un div interno y le añadirá como contenido la respuesta obtenida de la peticón ajax realizada a la url establecida en la configuración, puede ser tanto a contenido estático como contenido dinámico.

� Contenido estático: En el caso que se quiera cargar un dialogo con un htm de la parte de estáticos se debería establecer la url de la siguiente forma:

url: $.rup.APP_STATICS + "/resources/ajaxDiv.htm"

� Contenido dinámico: En el caso que se quiera cargar un contenido dinámico ya sea una jsp o el contenido de una petición al controller se deberá configurar de la siguiente forma:

url: "../patrones/dialogJSP", ajaxOptions: {

success: function (data, textStatus, XMLHttpRequest){…} }

Donde ajaxOptions es un objeto que posee las propiedades del objeto $.ajax como se explica a continuación.

Componentes RUP – Diálogo 8/12

• ajaxOptions : Object. Establece las todas las propiedades para configurar la petición ajax, como pueden ser:

o El evento success: el cual se ejecutará una vez se haya completado con existo la petición ajax.

o El evento beforeSend: el cual se ejecutará antes de que se lance las petición, pudiendo modificar el objeto XMLHTTPRequest de la petición.

o El evento error. El cual se ejecutara en caso de que curra algún error.

• rupCheckStyle : Boolean (true o false). Propiedad definida por el componentes base, si está a true se mostraran los mensajes específicos del componente base marcados por la guía de estilos, es decir, que si el desarrollador no cumple con la guisa de estilos o desarrollo el objeto base mostrará los mensajes advirtiendo su incumplimiento, si se pone a false no se mostraran. Esta acción queda bajo la responsabilidad de la aplicación, ya que esta propiedad no debería modificarse.Su valor por defecto es true

• showLoading : Boolean (true o false). Esta propiedad mostrará una capa de cargando datos en los diálogos de tipo Ajax durante la carga del mismo.

• disabled : Boolean (true o false). Propiedad que deshabilita o no el diálogo. Su valor por defecto es false.

• autoOpen : Boolean (true o false). Si esta propiedad esta a true el diálogo se abrirá automáticamente cuando se cree, en el caso de que su valor sea false, el diálogo se mantendrá oculto hasta que se invoque a la función “open” (.rup_dialog(“open”)). Su valor por defecto es true .

• buttons : Object ({} ).Define los botones (literales y funciones a las que invocan) que contendrá el diálogo. La propiedad sería de tipo Array. Donde cada elemento del array debe ser un objeto que define las propiedades de cada botón y el tipo del mismo.

buttons: [{ text: $.rup.i18n.rup_dialog.ok,

click: function() { $(this).rup_dialog("close"); }, btnType: $.rup.dialog.LINK

}, ...

]

• closeOnEscape : Boolean (true o false). Especifica si se debe cerrar el diálogo cuando el tenga el foco y el usuario pulse la tecla ESC. Su valor por defecto es true.

• dialogClass : Porpiedad que establece el/los estilos que se añadirán al dialogo para dotar al dialogo de estilos diferentes.

• draggable : Boolean (true o false). Si su valor es true el diáologo sera dragable pinchando sobre el título. Su valor por defecto es true.

• height : Number. Establece el alto del diálogoen pixeles. Su valor por defecto es auto.

• hide : String . Esfecto utilizado cuando se cierra el diálogo. Su valor por defecto es null.

• maxHeight : Number. Alto máximo en pixeles al que se puede llegar a redimensionar el diálogo. Su valor por defecto es false (no establecido).

Componentes RUP – Diálogo 9/12

• maxWidth : Number. Ancho máximo en pixeles al que se puede llegar a redimensionar el diálogo. Su valor por defecto es false (no establecido).

• minHeight : Number. Alto mínimo en pixeles al que se puede llegar a redimensionar el diálogo. Su valor por defecto es 150

• minWidth : Number. Ancho mínimo en pixeles al que se puede llegar a redimensionar el diálogo. Su valor por defecto es 150

• modal : Boolean (true o false). Si se establece esta propiedad a true el diálogo se abrirá de forma modal, por encima del resto de elementos. Su valor por defecto es false (no establecido).

• position : String, Array. Esta propiedad especifica donde debe mostrarse el diálogo. Sus posibles valores son:

o Un simple String representando la posición. 'center', 'left', 'right', 'top', 'bottom'.

o Un array con las coordenadas x, y en pixles (e. [350,100])

o Un array con string que representan la posición (e. ['right','top'])

• resizable : Boolean (true o false). Si se establece esta propiedad a true el diálogo se redimensionable.

• show : String. Efecto a realizar cuando se abre el diálogo.

• stack . Boolean (true o false). Establece si el diálogo actual se situa por encima del resto de diálogos que existan en la ventana.

• title : String. Establece el título de la ventana. Puede ser cualquier html válido.

• width : Number. Establece el ancho del diálogo en pixeles. Su valor por defecto es 300.

• zIndex : Number. Establece el zIndex del diálogo. Su valor por defecto es 1000 .

La definición de los literales de las ventanas (título, texto, botones, etc.) se ha simplificado mediante la implementación de un sistema que obtenga de un fichero json los literales necesarios según el idioma de navegación. El acceso a los ficheros se realizará mediante el identificador definido (key) como se verá más adelante (apartado Internacionalización).

6.1. Botones

Los diálogos pueden ser cerrados pulsando tanto la tecla Escape, en el aspa que aparece en la barra del título en la parte superior derecha o en el enlace que aparece junto al aspa. Por defecto al cerrar el diálogo de este modo se invocará función asociada a la acción secundaria, en caso de que no exista invocará la primaria. Es decir, en caso de un solo botón, diálogo de mensaje, se invocará la misma función que llame el botón al ser pulsado, pero en caso de que haya un botón y un enlace se invocará la acción que invoque el enlace.

buttons:[{ text: $.rup.i18n.rup_global.aceptar, click: function() { $("#idDialog").rup_dialog("close"); }

Componentes RUP – Diálogo 10/12

}, {

text: $.rup.i18n.rup_global.enviar, click: function() { $("#idDialog").rup_dialog("close"); },

btnType:$.rup.dialog.LINK } }]};

7. Métodos

El desarrollador podrá invocar a las siguientes funciones para poder realizar acciones sobre el componente:

• open : abre el dialogo y estable el foco en el primer botón.

$( selector ) .rup_dialog ( "open" );

• close : Cierra el dialogo.

$( selector ) .rup_dialog ( "close" );

• destroy : Borra el dialogo si este estubiera oculto o visible.

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

• disable : Función que deshabilita el dialogo sobre el que se aplica.

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

• enable : Funcion que, en caso de estar desahibilitado, habilita el dialogo sobre el que se aplica.

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

• moveToTop : Funcion encargada de poner por encima de todos los dialogos al dialogo sobre el que se aplica. Puede ser muy util se se tiene mas de un dialog abierto a la vez.

$( selector ) .rup_dialog ( "moveToTop" );

• isOpen : Función que devuelve si el dialogo esta abierto.

$( selector ) .rup_dialog ( "isOpen" );

• getOption (option): Obtiene la propiedad que recibe como parametro.

$( selector ) .rup_dialog ( "getOption", "width" );

• setOption (option): Establece la propiedad que recibe como parametro.

$( selector ) .rup_dialog ( "setOption", "width" , 200 );

Componentes RUP – Diálogo 11/12

8. Eventos

El desarrollador podrá hacer uso de los siguientes eventos para poder realizar acciones en cada evento.

• open : Evento que se lanza cuando se abre el diálogo.

$(selector).rup_dialog({ open: function(event, ui) { ... } });

• close: Evento que se lanza a la hora de cerrar el diálogo.

$(selector).dialog({ close: function(event, ui) { ... } });

• beforeCose : Evento que se lanza justo antes de que se cierre el dialogo, si este evento devuelve false se anulará las acción de cierre y el dialogo seguirá abierto.

$(selector).dialog({ beforeClose: function(event, ui) { ... } });

9. Sobreescritura del theme

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

Los estilos principales a tener en cuenta son los siguientes:

.ui-dialog-title: Estilo aplicado a la cabecera de la ventana de diálogo.

.ui-dialog-content: Estilo aplicado al cuerpo de la ventana de diálogo.

.ui-dialog-button-pane: Estilo aplicado a la botonera de la ventana de diálogo.

Adicionalmente se aplican una serie de estilos para mejorar la experiencia del usuario como puede ser el redondeo de las esquinas (sólo aplicable en FireFox) o la inclusión de estilos que modifiquen el cursor en caso de que la ventana sea redimensionable.

Componentes RUP – Diálogo 12/12

10. Internacionalización (i18n)

La gestion de los literales de lo diálogos se realiza a través de ficheros json lo que flexibiliza el desarrollo. Para acceder a los literales se hara uso del objeto base rup, por el cual se accedera al objeto json correspondiente según el idioma para obtener tanto los literales como los propios mensajes.

Los literales definidos para el contenido del diálogo pueden ser simple texto o código en html. Para este componente lo literales utilizados son escasos y están en la parte global de la internacionalización dentro de los resources de rup. A continuación se muestran los literales necesarios para el componente:

{ "rup_message":{ "aceptar":"Aceptar", "tituloError":"Se ha producido un error",

... }, "rup_global":{ "cerrar":"cerrar", "rupCheckStyleError":"NO SE CUMPLEN LAS NOMRAS DE LA GUIA DE ESTILOS DE RUP. DEBE EXISTIR UNA ACCIÓN SECUNDAR IA." }, "rup_blockUI":{

"cargando":"Procesando, espere por favor" }, "rup_dialog":{

"errorLoadingData":"<b>Error recuperando los datos peticionados para crear el diálogo.</b>"

} }

El acceso a cualquier tipo de literal se debe realizar de la siguiente forma (teniendo en cuenta que es un objeto JSON):

$.rup.i18n.rup_global.cerrar

11. Integración con UDA

No aplica.