UDA-Componentes RUP. Pestañas

UDA - Utilidades de Desarrollo de Aplicaciones

Componentes RUP – Pestañas

Fecha: 03/12/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

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

Componentes RUP – Pestañas ii/16

Control de documentación

Título de documento: Componentes RUP – Pestañas

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.1.1 19/10/2011

Uso de capas html pre-cargadas (parámetro layer ).

Incorporación de la función changeLayerTab para modificar el contenido de una pestaña por un html pre-cargado.

1.2.1 24/01/2012 Se permitir definir la anchura (parámetro width ) y la altura (parámetro height ). Además, se le incluye scrollbar en caso necesario.

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

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.

2.4.2 27/06/2014 Nueva propiedad tabsAtBottom.

2.4.4 03/12/2014 Nuevas propiedades maxNumberTabs, lengthLiteral, fixedHeight, close, scrollable

Cambios producidos desde la última versión

Nuevas propiedades maxNumberTabs, lengthLiteral, fixedHeight, close, scrollable

Control de difusión

Responsable: Ander Martínez

Componentes RUP – Pestañas iii/16

Aprobado por:

Firma: Fecha:

Distribución:

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Pestañas iv/16

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 6

4.2. Dependencias 6

4.3. Versión minimizada 6

5. Invocación 7

6. Parámetros 9

7. Funciones 12

8. Eventos 15

9. Sobreescritura del theme 15

10. Integración con UDA 16

Componentes RUP – Pestañas 5/16

1. Introducción

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

Permiten dar acceso de forma compacta a grupos de contenidos mutuamente excluyentes pudiendo ser integradas en zonas muy reducidas de la interfaz.

2. Ejemplo

Se presentan a continuación un ejemplo de este patrón:

3. Casos de uso

Se recomienda el uso del patrón:

• Cuando se pretende separar grupos de contenidos mutuamente excluyentes.

4. Infraestructura

A continuación se comenta la infraestructura necesaria para el correcto funcionamiento del patrón.

• Se han de definir, en los controladores apropiados, las distintas funciones que sirvan las páginas presentadas en cada una de las pestañas.


El componente trabaja con distintas llamadas ajax que cargan el contenido de la pestaña al acceder a ellas. Dichas llamadas ajax requieren de las funciones del controller apropiadas para servir los contenidos.

• Adicionalmente, para el funcionamiento en cliente del componente, se requiere la inclusión de los ficheros que implementan el patrón (js y css) comentados en los apartados Ficheros y Dependencias.

4.1. Ficheros

Ruta Javascript: rup/scripts/

Fichero de plugin: rup.tabs-x.y.z.js

Ruta theme: rup/basic-theme/

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

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

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

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

• theme.rup.tabs-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

La primera noción que se ha de tener en cuenta, para el correcto manejo e inclusión del componente Pestañas dentro de una página jsp, es la asociación del componente a un elemento estructural “<div>” de html. La definición de dicho elemento determinara la ubicación que tendrá el componente dentro de las propias páginas donde será utilizado.

Para poder relacionar el componente a su “<div>” asociado y para que no se mezclen posibles definiciones de más de un componente Pestañas en la misma pagina, el “<div>” debe ir identificado por un “id” (identificador) único. Por ejemplo, un posible “<div>” utilizado podría tener el siguiente aspecto:

<div id =tabsDemo></ div >

Una vez definido el elemento que incluirá el componente será labor del desarrollador componer el selector de jQuery que determine el “<div>” sobre el que se aplicará el componente especificado. Una posible definición del selector, sobre el “<div>” definido anteriormente, sería:

$( "#tabs" ). rup_tabs ({

tabs : [

{ i18nCaption : "pestana1" , tabs : [ { i18nCaption : "sub10" , url : "tab1Fragment" }, { i18nCaption : "sub11" , url : "tab2Fragment" } ]}, { i18nCaption : "pestana2" , url : "tab2Fragment"}

]

});

Como se puede ver en el ejemplo, también será labor del desarrollador la definición y distribución de las distintas pestañas que formaran parte del componente.

Las distintas pestañas definidas se declaran dentro de un array json de nombre “tabs”. En dicho array, se determinan las distintas pestañas incluidas en el nivel jerárquico del componente (por ejemplo: la primera definición del array determina el primer subnivel de pestañas). Para que el componente pueda mostrar algo es necesario que incluya, al menos, un array “tabs”.

A su vez, cada uno de los elementos del array se compondrá de objetos json que contendrán dos objetos json:

• i18nCaption • url / tabs

El atributo “i18nCaption” es obligatorio a la hora de parametrizar una pestaña, ya que determina el literal que aparece definiendo la pestaña. Los literales de definición de las pestañas interaccionan con el sistema


de gestión idiomática de la capa de presentación; por lo que el valor asociado al “i18nCaption” debe estar inscrito en el objeto “tab” dentro del los ficheros de literales (uno por cada idioma versionado) de la aplicación. Siguiendo con el ejemplo de definición del componente anterior, los ficheros de literales tendrían el siguiente aspecto:

Considerando que la aplicación tiene por código x21a y el War en el que se ubica la página, que alberga el componente, tiene por nombre Demo.

En el fichero “x21aDemo.i18n_es.json” ubicado en “/x21aStatics/WebContent/x21a/resources/”, se incluirá lo siguiente:

"tabs" : { "pestana1" : "Tab 1" , "pestana2" : "Tab 2" , "sub01" : "sub01" , "sub02" : "sub02"

}

Si la aplicación trabajara con más de una versión idiomática, se debería incluir la correspondiente traducción idiomática del literal en su correspondiente fichero (x21aDemo.i18n_eu.json, x21aDemo.i18n_en.json, x21aDemo.i18n_fr.json,…).

Es posible añadir otro array json para crear un nuevo subnivel de pestañas mediante el atributo tabs que recibirá una estructura json con el contenido de la sub-pestaña. También es posible mediante el parámetro url indicar la ruta de acceso a los contenidos de la pestaña parametrizada. Dicha ruta tendrá que coincidir con la utilizada para invocar los contenidos definidos en el controller (consideración estructural definida en el apartado “4. Infraestructura”). Además del envió de parámetros mediante “query string”, el componente acepta las urls en tres formatos:

Absoluto : Se le pasa la url completa.

url: "http://www.euskadi.ejiedes.net/x21aPilotoPatronesW ar/patrones/tab2Fragment"

Relativa al dominio : Se le especifica la url con una barra “/” como primer carácter. De esta manera, el componente concatenara la ruta especificada al dominio en el que se encuentre la aplicación.

url : "/x21aPilotoPatronesWar/patrones/tab2Fragment"

Relativa a la dirección actual : Se determina la ruta sin una barra “/” como primer carácter. Con este modelo, el componente monta la url quitando la ultima parte de la llamada, hasta la primera barra “/”, y añade la ruta especificada.

url : "tab2Fragment"

A nivel de interacción con el servidor, cabe destacar que el componente, por defecto, cachea el contenido servido mediante llamadas ajax para cada una de las pestañas. Este modelo de presentación agiliza la carga inicial del componente sin penalizar la interacción con el usuario (ya que no se invoca continuamente mediante ajax el contenido de cada pestaña). Este modo, por defecto, puede ser problemático frente a páginas dinámicas que pueden variar en el tiempo, por lo que se han incluido en el componente métodos y parametrizaciones que permiten modificar este comportamiento (es posible desconectar el cacheo en general o forzar la carga de una pestaña mediante un método).

El componente pestañas no limita el número de subniveles de pestañas que se pueden utilizar, pero por cuestiones de legibilidad y jerarquía estructural se recomienda el uso de no más de 2 subniveles de pestañas.


6. Parámetros

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

• disabled: Mediante el parámetro disabled, el desarrollador puede especificar el conjunto de pestañas que, inicialmente, estarán deshabilitadas. Para ello, dentro de la definición de uso del componente, se debe asociar al parámetro disabled un objeto json compuesto de parejas (pair). En dichas parejas se especifica el literal asociado a un sub-nivel de pestañas y el número de la pestaña que se quiere deshabilitar.

Un ejemplo de parametrización con pestañas deshabilitadas sería el siguiente:


tabs : [


] , disabled : { tabs : 1, pestana1 : 1 }

});

Como excepción a la norma de especificación del subnivel y pestaña a deshabilitar, es necesario aclarar que las pestañas en el primer subnivel siempre se especifican con el identificador de todo el objeto (para este ejemplo, el identificador es “tabs”).

También cabe destacar que las pestañas cero de cada uno de los sub-niveles no pueden salir deshabilitadas por la presentación inicial que hace el componente. En un orden de lectura de izquierda a derecha, tampoco tendría sentido tener la primera pestaña (la de la izquierda del todo) deshabilitada, cuando se puede ordenar más a la derecha.

Las pestañas se pueden habilitar o deshabilitar programáticamente utilizando los métodos del propio componente “disableTabs” y “enableTabs”.

• cache: Activada (true) por defecto, para cachear los contenidos de las pestañas mejorando el rendimiento en tiempos y llamadas. Mediante el valor false se desactiva este comportamiento y se realiza una invocación ajax cada vez que se presentan los datos de una pestaña.


tabs : [


]


, disabled : { tabs : 1, pestana1 : 1 } , cache : false

});

• close : Determina si se debe mostrar un icono de cerrar pestaña junto al label de las mismas. De este modo se permite eliminar pestañas de manera dinámica. Por defecto su valor es false.

$( "#tabs" ). rup_tabs ({ ... close: true ...

});

• fx: Parámetro para habilitar animaciones a la hora de ocultar y mostrar las pestañas. Además de poder especificar un tipo de animación, también es posible determinar el tiempo de duración de la misma utilizando una de las tres velocidades predefinidas ("slow", "normal", "fast") o indicando un valor en milisegundos (por defecto, el valor es "normal").

Básicamente el parámetro fx se utiliza para pasar los campos de invocación de la función animate de JQuery (http://api.jquery.com/animate/). Las opciones y los valores aceptados por el parámetro fx son los mismos que acepta la función animate (ver documentación de JQuery).

El parámetro fx se puede parametrizar para que tenga el mismo o distinto efecto a la hora de mostrar una pestaña y a la hora de ocultarla. Para diferenciar los efectos de presentación el parámetro fx acepta el paso de un único conjunto de opciones (el mismo efecto o efecto con inversión) o el paso de un array de dos conjuntos de opciones con el efecto de ocultación y el de reaparición (el primer elemento marca el efecto de ocultación y el segundo el de reaparición).


tabs : [


] , disabled : { tabs : 1, pestana1 : 1 } , cache : false , fx : [{ opacity : 'toggle' , height : [ 'toggle' , 'swing' ], duration : 'normal' }, // hide option { opacity : 'toggle' , width : [ 'toggle' , 'swing' ], duration : 'fast' }] // show option

});

• fixedHeight : Permite especificar una altura fija para el contenedor de las pestañas. En caso de que el contenido supere este tamaño se mostrará scroll. Por defecto su valor es undefined.

$( "#tabs" ). rup_tabs ({ ... fixedHeight: 450 ...

});

• lengthLiteral : Permite especificar un número máximo de caracteres a mostrar en el label de la pestaña antes de aplicar ellipsis. Por defecto su valor es undefined.


$( "#tabs" ). rup_tabs ({ ... lengthLiteral: 10 ...

});

• maxNumberTabs : Parámetro que determina el número máximo de pestañas que va a permitir el componente que se añadan de manera dinámica. Por defecto su valor es undefined.

$( "#tabs" ). rup_tabs ({ ... maxNumberTabs: 5 ...

});

• panelTemplate: Especifica la plantilla html que envolverá el contenido perteneciente a una pestaña. La plantilla por defecto del componente es '<div></div>' y en caso de querer añadir una nueva se deberá poner la plantilla con las etiquetas de apertura y cierre correspondientes.

$("#tabs").rup_tabs({ tabs : [


], disabled : { tabs : 1, pestana1 : 1 }, cache : false , fx : [

{ opacity : 'toggle' , height : [ 'toggle' , 'swing' ], duration : 'normal' }, // hide option

{ opacity : 'toggle' , width : [ 'toggle' , 'swing' ], duration : 'fast' }

], //show option panelTemplate : '<H2></H2>'

});

• scrollable : Determina si la pestaña permite el mostrar scroll en la capa contenedora. Por defecto su valor es false.

$( "#tabs" ). rup_tabs ({ ... scrollable: true ...

});

• layer : Parámetro que permite especificar fragmentos html previamente cargados para el contenido de una pestaña. El parámetro acepta cualquier tipo de selector válido de JQuery para determinar que fragmento html se ubica en la pestaña. En caso de precisarse un selector de JQuery que devuelva más de un elemento, éstos se incluirán en la pestaña correspondiente dispuestos verticalmente (esta forma de trabajar no es muy ortodoxa pero es factible).

$( "#tabsStatic" ).rup_tabs({


tabs : [ {i18nCaption:"pestana0", layer:".estiloo" }, {i18nCaption:"pestana1", layer:"#ejemploVisual" }, {i18nCaption:"pestana2", layer:".estiloo2" }]

});

El uso de este tipo de estructuras en el componente pestañas, puede derivar en efectos raros de aparición y desaparición de objetos a la hora de cargar la página. Para evitar este tipo de anomalías visuales, se recomienda que los fragmentos html utilizados lleven incorporados el style="display: none;". La incorporación de este estilo permitirá que el html no aparezca hasta estar creadas las pestañas y será eliminado por el propio componente. En caso de incluir el estilo "display: none;" en un class, el componente no será capaz de quitarlo directamente y será necesaria una gestión adicional para que el contenido de la pestaña se visualice correctamente.

• width y height : Permiten definir las dimensiones del componente.

$( "#tabs" ). rup_tabs ({ ... width:800, height:600 ...

});

La asignación de unos valores superiores al contenedor que aloja el componente puede suponer que éste sobrepase los límites de su padre. Queda bajo responsabilidad del diseñador revisar los tamaños de los diferentes componentes de pantalla que pudieran verse afectados.

• tabsAtBottom : Parámetro que determina si las pestañas se van a mostrar en la parte inferior en vez de en la superior. Por defecto su valor es false.

$( "#tabs" ). rup_tabs ({ ... tabsAtBottom: true ...

});

7. Funciones

A continuación se detallan las diferentes funciones que integran el componente pestañas:

• disableTabs: Función encargada de deshabilitar una o un conjunto de pestañas de un mismo sub-nivel. La invocación del método se realiza de la siguiente manera:

o Una única pestaña:

$( "#tabs" ). rup_tabs ( "disableTabs" ,{ idTab : "tabs" , position : 1

});

o Un conjunto de pestañas:

$( "#tabs" ). rup_tabs ( "disableTabs" ,{ idTab : "tabs" , position : [ 0, 1, 2]


});

NOTA: Se ha de recordar que cada subnivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas. También es importante tener claro que la pestaña en la que se encuentre el usuario no puede ser deshabilitada.

• enableTabs: Función encargada de habilitar una o un conjunto de pestañas de un mismo subnivel. La invocación del método se realiza de la siguiente manera:

o Una única pestaña:

$( "#tabs" ). rup_tabs ( "enableTabs " ,{ idTab : "tabs" , position : 1

});

o Un conjunto de pestañas:

$( "#tabs" ). rup_tabs ( "enableTabs" ,{ idTab : "tabs" , position : [ 0, 1, 2]

});

NOTA: Se ha de recordar que cada subnivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas.

• loadTab: Función que fuerza la recarga de una pestaña. Si se especifica una nueva url, además de recargar la página con la nueva url, se inserta ésta como nueva url de la pestaña. La invocación del método se realiza de la siguiente manera:

o Recarga simple:

$( "#tabs" ). rup_tabs ( "loadTab" ,{ idTab : "tabs" , position : 2

});

o Recarga con cambio de url:

$( "#tabs" ). rup_tabs ( "loadTab" ,{ idTab : "tabs" , position : 2, url : "/nuevoFragmento"

});

NOTA: Como se ha comentado en apartados anteriores, las urls aceptadas por el componente pueden tener tres formatos diferentes: absoluta, relativa al dominio y relativa a la url actual. Cada sub-nivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas.

• changeUrlTab: Función encargada de actualizar la url de invocación de una pestaña determinada. La invocación del método se realiza de la siguiente manera:

$( "#tabs" ). rup_tabs ( "changeUrlTab" ,{ idTab : "tabs" , position : 1 , url : "nuevaUrl"

});


NOTA: Como se ha comentado en apartados anteriores, las urls aceptadas por el componente pueden tener tres formatos diferentes: absoluta, relativa al dominio y relativa a la url actual. Cada subnivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas.

• changeLayerTab: Función encargada de actualizar la capa html, previamente cargada, que se muestra en la pestaña determinada. La invocación del método se realiza de la siguiente manera:

$( "#tabs" ). rup_tabs ( "changeUrlTab" ,{ idTab : "tabs" , position : 2 , layer: "nuevaSelector"

});

NOTA: Como se ha comentado en otro punto de este documento, el parámetro layer acepta cualquier tipo de selector valido de JQuery para determinar que fragmento de html se ubica en la pestaña. En caso de precisarse un selector de JQuery que devuelva más de un elemento, éstos se incluirán en la pestaña correspondiente dispuestos verticalmente (esta forma de trabajar no es muy ortodoxa pero es factible). Cada sub-nivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas.

• selectTab: Función encargada de seleccionar una pestaña determinada. El comportamiento es idéntico al click con el ratón. La invocación del método se realiza de la siguiente manera:

$( "#tabs" ). rup_tabs ( "selectTab" ,{ idTab : "tabs" , position : 1 ,

});

NOTA: Cada sub-nivel se distingue por el literal del mismo y el primer nivel se identifica mediante el identificador general de toda la estructura de pestañas.

• addTab: Función encargada de añadir una nueva pestaña cuando el componente ya está creado. Es posible añadir una nueva pestaña al final o entre otras pestañas. La invocación del método se realiza de la siguiente manera:

$( "#tabs" ). rup_tabs ( "addTab" ,{ idTab : "tabs" , position : 2, label : "nuevaPestaña" , url : "fragmento3"

});


• removeTab: Función encargada de eliminar una nueva pestaña cuando el componente ya está creado. La invocación del método se realiza de la siguiente manera:

$( "#tabs" ). rup_tabs ( "removeTab" ,{ idTab : "tabs" , position : 2

});



8. Eventos

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

• create: Este evento se lanza cada vez que se crea una pestaña. Se configura de la siguiente manera:

$( selector ) .rup_tabs ({ create: function(){...} });

• select: Se lanza el evento cada vez que se hace click sobre una pestaña. Se configura de la siguiente manera:

$( selector ) .rup_tabs ({ select: function(){...} });

• load: Este evento se desencadena después de que el contenido de una pestaña se ha cargado.

$( selector ) .rup_tabs ({ load: function(){...} });

• show: Este evento ocurre cuando una pestaña está preparada para ser mostrada:

$( selector ) .rup_tabs ({ show: function(){...} });

• add: Este evento se desencadena cuando se añade una pestaña:

$( selector ) .rup_tabs ({ add: function(){...} });

• remove: Este evento se desencadena cuando se elimina una pestaña:

$( selector ) .rup_tabs ({ remove: function(){...} });

• enable: Este evento se desencadena cuando se habilita una pestaña:

$( selector ) .rup_tabs ({ enable: function(){...} });

• disable: Este evento se desencadena cuando se deshabilita una pestaña:

$(selector). rup_tabs ({ disable: function(){...} });

9. Sobreescritura del theme

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

A continuación se muestran unas capturas del componente con los estilos asociados dependiendo del uso de imágenes. 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.

10. Integración con UDA

No aplica.

UDA-Componentes RUP. Pestañas

Technology

Transcript of UDA-Componentes RUP. Pestañas