UDA-Utilidades de desarrollo de aplicaciones • UDA-Componentes RUP. Diálogo http://uda-ejie.github.io/

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

2. 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:

3. Componentes RUP – Diálogo iii/12
Nombre archivo:
Localización:

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

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

6. Componentes RUP – Diálogo 6/12
NOTA: Como se observa, los estilos se basan en el fichero 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);

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

8. 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).

9. 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");
}

10. 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);

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

12. 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 SECUNDARIA."
},
"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.