UDA - Utilidades de Desarrollo de Aplicaciones

Componentes RUP – Tooltip

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 – Tooltip iii/10

Control de documentación

Título de documento: Componentes RUP – Tooltip

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.

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.

1.2.1 13/02/2012

Cambios para que se aplique o no el tooltip a la infraestructura de Portales (parámetro applyToPortal ).

Ajuste de estilos para cambiar el aspecto del componente tooltip.

2.0.0 02/04/2012 Cambiar el plugin subyacente para un mejor funcionamiento del patrón.

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:

Componentes RUP – Tooltip iv/10

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Tooltip v/10

Contenido

Capítulo/sección Página

1. Introducción 6

2. Ejemplo 6

3. Casos de uso 6

4. Infraestructura 6

4.1. Ficheros 6

4.2. Dependencias 7

4.3. Versión minimizada 7

5. Invocación 8

6. Parámetros 8

7. Funciones 9

8. Eventos 11

9. Sobreescritura del theme 11

10. Integración con UDA 11

Componentes RUP – Tooltip 6/10

1. Introducción

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

Todas las aplicaciones deben tener un sistema de ayuda aunque algunas necesiten uno más completo y preciso que otras. El objetivo del sistema de ayuda debe ser, por un lado ayudar al impaciente y/o al usuario ocasional tan extensamente como sea posible y, por otro, ayudar a los usuarios expertos.

2. Ejemplo

Se presenta a continuación un ejemplo de este componente:

3. Casos de uso

Se recomienda el uso del componente:

• Cuando se desea añadir una ayuda/descripción extra sobre algún componente de tal manera que se muestre al interaccionar con dicho componente.

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

Ruta theme: rup/basic-theme/

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

Componentes RUP – Tooltip 7/10

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/

Las distintas funcionalidades que aporta el componente y las prestaciones generales del mismo, se apoyan en el plugin Qtip2 . Para el correcto funcionamiento del componente Tooltip, se precisa de la inclusión de dicho plugin.

• Qtip2: http://craigsworks.com/projects/qtip2/

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

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

� rup.tooltip-x.y.z.js

� theme.rup.tooltip-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.

Componentes RUP – Tooltip 8/10

5. Invocación

Este componente se invocará mediante un selector que indicará todos los elementos sobre los que se va a aplicar el componente tooltip. Lo más fácil sería utilizar el selector siguiente:

$(selector).rup_tootlip(properties);

Donde el parámetro “properties” es un objeto (var properties = {};) o bien directamente la declaración de los valores, detallados en el siguiente apartado.

6. Parámetros

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

• disabled: booleano que indica si el tooltip está habilitado o no. Valor por defecto false . Se podrá cambiar el valor de esta propiedad con la siguiente invocación:

$(selector).rup_tooltip("option", "disabled", tru e);

• applyToPortal: Parámetro encargado de determinar si el componente tooltip se aplica, también, al código html adscrito a los portales de la infraestructura de EJIE. El parámetro acepta el valor true, para indicar que se aplique al portal, y el valor false, para indicar que no se aplique al portal. Por defecto, si no se indica ningún valor, el valor del parámetro es false.

NOTA: Existen muchas opciones diferentes a la hora de configurar el tooltip por lo que recomendamos consultar los ejemplos y la documentación en la página web del plugin subyacente (Qtip2). A continuación se detallan las que se consideran más útiles:

• content: configura el texto del tooltip (si no se ha definido en el title):

o text: texto del tooltip o title:

text: tooltip en formato diálogo y este parámetro define el título del mismo

• position: configura la posición del tooltip y tiene (entre otros) los siguientes parámetros:

o my: posición en la que es colocado el tooltip a mostrar. o at: posición respecto al objeto al que se aplica el tooltip. o target: si se quiere definir sobre qué elemento debe aplicarse el tooltip.

Valor por defecto: {my: "top left", at: "bottom left"}. .

• show: configura el modo/evento en el que se despliega el tooltip. Por defecto al colocar el ratón encima del objeto

o event: evento con el que se muestra el tooltip (ej: click). o modal: el tooltip se muestra como si fuera modal (se deshabilita el resto de la

pantalla).

• hide: configura el modo/evento en el que se oculta el tooltip. Por defecto al quitar el ratón del objeto

o event: evento con el que se muestra el tooltip (ej: click).

Componentes RUP – Tooltip 9/10

7. Funciones

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

• destroy: elimina el tooltip. La invocación se realizará de la siguiente manera:

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

• disable: deshabilita el tooltip. La invocación se realizará de la siguiente manera:

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

• enable: habilita el tooltip. La invocación se realizará de la siguiente manera:

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

• option: obtiene o establece la configuración del tooltip. La invocación se realizará de la siguiente manera:

o Obtener el valor de la posición:

$( selector ) .rup_tooltip ( "option", "position" );

o Establecer el valor de la posición:

$( selector ) .rup_tooltip ( "option", "position", {offset: "15 15"} );

• open: muestra el tooltip. La invocación se realizará de la siguiente manera:

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

• close: oculta el tooltip. La invocación se realizará de la siguiente manera:

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

A continuación se muestran un par de ejemplos para mostrar las posibles combinaciones:

1. Ejemplo de tooltip en una imagen que se muestra al pinchar sobre ella y se oculta al mover el ratón fuera de ella:

$( "#idImagen" ).rup_tooltip({ content: { text: "Esto es un ejemplo de tooltip sobre imagen" }, position: {

Componentes RUP – Tooltip 10/10

my: 'top center' , at: 'bottom center' , target: $( "#id" ) }, show: { event: 'click' }, open: function(){ //Función que se ejecuta al mostrar el tooltip

... }, close: function(){

//Función que se ejecuta al ocultar el tooltip ...

}

});

idImagen: identificador de la imagen en pantalla

id: identificador del input sobre el que se desea m ostrar el tooltip

2. Ejemplo de tooltip modal en una imagen que se muestra al pinchar sobre ella y se oculta al volver a pinchar:

$( "#idImagen" ).rup_tooltip({

content: { text: 'Esto es un ejemplo de tooltip modal sobre imagen' , title: { text: 'Tooltip modal' } }, position: { my: 'bottom center' , at: 'top center' , target: $( "#id" ) }, show: { event: 'click' , modal: true }, hide: { event: 'click' }

});

idImagen: identificador de la imagen en pantalla

id: identificador del input sobre el que se desea m ostrar el tooltip

Componentes RUP – Tooltip 11/10

8. Eventos

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

• open: permite asociar una función que se ejecutará cuando se muestre el tooltip. Se configura de la siguiente manera:

$( selector ) .rup_tooltip ({ open: function(){...} });

• close: permite asociar una función que se ejecutará cuando se oculte el tooltip. Se configura de la siguiente manera:

$(selector).rup_tooltip ({ close: function(){...} });

9. Sobreescritura del theme

El componente tooltip se presenta con una apariencia visual definida en el fichero de estilos theme.rup.tooltip-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 que contengan la palabra “ui-“ son los propios de jQuery UI que en caso de ser necesario serán sobrescritos y no se comentarán en este documento por no ser su ámbito. Es importante tener en cuenta que, si se cambia el aspecto del componente tooltip mediante el Theme Roller, es posible que, también se cambie el aspecto de algunos otros componentes indirectamente (por ejemplo: el componente menú). Este efecto colateral, se debe a que algunos objetos de JQuery-UI comparten estilos, para mantener el modelo general de las páginas

Al aplicar de manera directa (online) los estilos del Theme Roller (ej. invocando $.rup.themeRoller()), puede ser que los estilos del tooltip no se vean afectados por los cambios. Para ello se deberá invocar la siguiente sentencia que modifica la gestión de estilos de los tooltips creados:

$( ".qtip" ).rup_tooltip( 'option' , 'style.widget' , true);

NOTA: Para el correcto funcionamiento, los tooltips deben haberse mostrado al menos una vez para que el componente tooltip cree los elementos en el árbol DOM.

10. Integración con UDA

No aplica.