UDA-Componentes RUP. Wizard

18

Click here to load reader

description

UDA-Utilidades de desarrollo de aplicaciones • UDA-Componentes RUP. Wizard http://code.google.com/p/uda/

Transcript of UDA-Componentes RUP. Wizard

Page 1: UDA-Componentes RUP. Wizard

UDA - Utilidades de Desarrollo de Aplicaciones

Componentes RUP – Wizard

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

Page 2: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard iii/18

Control de documentación

Título de documento: Componentes RUP – Wizard

Histórico de versiones

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

2.0.0 20/04/2012 Primera versión.

2.0.1 08/08/2012 Añadidos estilos

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:

Nombre archivo:

Localización:

Page 3: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard iv/18

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 7

6. Parámetros 8

7. Funciones 11

8. Estructura 12

9. Resumen (conversiones) 13

9.1. INPUT 13

9.2. TEXTAREA 14

9.3. SELECT (combo) 14

9.4. LABEL 14

9.5. Componentes RUP 15

9.5.1. Accordion 15

9.5.2. Combo 15

9.5.3. Date 15

9.5.4. Time 15

9.5.5. Tabs 15

Page 4: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard v/18

10. Sobreescritura del theme 16

10.1.1. Tabs 18

11. Integración con UDA 19

Page 5: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 6/18

1. Introducción

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

Permitir guiar al usuario paso a paso a través de un proceso realizando las tareas dentro de un orden señalado.

2. Ejemplo

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

3. Casos de uso

Se recomienda el uso del componente:

• Cuando la tarea sea larga o complicada.

• Cuando la tarea sea nueva para el usuario o no la realice a menudo.

• Cuando la tarea sea delicada y requiera un control alto.

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

Ruta theme: rup/basic-theme/

Page 6: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 7/18

Fichero css del theme: theme.rup.wizard-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/

Los ficheros necesarios para el correcto funcionamiento del componente son:

� jquery-1.8.0.js

� jquery.qtip.js

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

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

� theme.rup.wizard-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 objeto contenedor de la estructura a convertir en asistente paso a paso. Por ejemplo

$("#id_form").rup_wizard(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.

Page 7: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 8/18

6. Parámetros

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

• submitButton: Identificador del botón de envío del formulario. Sirve para que dicho botón solo se muestre en el último paso del asistente.

• submitFnc: Función que se ejecuta previamente al envío del formulario.

• summary: Indica si se debe generar o no el paso resumen. Este paso mostrará (como texto plano) los valores seleccionados en los diferentes pasos habilitados. Si un paso se encuentra deshabilitado no se utilizarán sus valores para la generación del resumen. El paso de resumen se genera cuando se navega hacia él. Su valor por defecto es true.

• summaryWithAccordion: Indica si el paso resumen debe formatear los diferentes pasos del asistente mediante elementos que usan el componente accordion. Su valor por defecto es false.

o true:

o false:

• summaryWithAccordionSpaceBefore: Indica si cuando se genera un resumen con los diferentes pasos presentados con accordion, se debe dejar un espacio (</br>) entre el contenido y la barra con los pasos. Su valor por defecto es true.

Page 8: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 9/18

• summaryWithAccordionSpaceAfter: Indica si cuando se genera un resumen con los diferentes pasos presentados con accordion, se debe dejar un espacio (</br>) entre el contenido y el contenedor de botones (siguiente y enviar). Su valor por defecto es true.

• summaryTabs2Accordion: Indica si los componentes rup_tab de los diferentes pasos del wizard se deben convertir en elementos del componente accordion a la hora de generar el paso resumen. Su valor por defecto es false.

o true:

o false:

• summaryFnc_PRE: Función que se invocará previamente a la generación del paso resumen. En caso de devolver false no se generaría el resumen.

• summaryFnc_INTER: Función que se ejecuta una vez ha comenzado la generación del paso resumen. Se habrá generado la capa contenedora y duplicado el contenido de los pasos anteriores pero sin llegar a procesarse (cambiarse por texto plano). En caso de devolver false no se continuaría con el procesado del contenido de los pasos.

• summaryFnc_POST: Función que se ejecuta una vez se ha generado el paso resumen.

Page 9: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 10/18

• stepFnc: Objeto json que contiene las diferentes funciones a ejecutar al navegar hacia cada uno de los pasos. En caso de devolver false no se continuaría la navegación hacia dicho paso. La clave de cada elemento será el número del paso y el valor será la función a ejecutar. Por ejemplo:

stepFnc : { 2 : function (){

//Función que se ejecuta al navegar hacia el paso 2 ... }

}

• disabled: Array que indica los pasos a deshabilitar al inicio. En caso de que el elemento del array sea un número (numeric) se deshabilitará dicho paso y en caso de que sea un literal (string) se procesará como un intervalo que deberá definirse como “X-Y”. Por ejemplo:

disabled: [1] //Deshabilitar el paso 1 disabled: ["2-4"] //Deshabilitar los pasos 2,3 y 4

• accordion: Define de forma general el funcionamiento del componente rup_accordion en el paso de resumen. Su valor por defecto es:

accordion: { animated: "bounceslide" , active: false, autoHeight: false, collapsible: true

},

• rupAccordion: Define el funcionamiento del patrón rup_accordion en el resumen (de los objetos rup_accordion existentes en los pasos anteriores). No tiene valor por defecto, por lo que en caso de no definirse se toma el valor del parámetro accordion.

• summaryAccordion: Define el funcionamiento del patrón rup_accordion en el resumen para cada uno de los pasos que lo componen (si configura la generación de resumen y conversión de pasos en accordion). No tiene valor por defecto, por lo que en caso de no definirse se toma el valor del parámetro accordion.

• tabAccordion: Define el funcionamiento del patrón rup_accordion en el resumen, para cada los objetos rup_tab existentes en los pasos anteriores (si configura la generación de resumen y conversión de pestañas en accordion). No tiene valor por defecto, por lo que en caso de no definirse se toma el valor del parámetro accordion.

• rupTabsElement: Indica el tipo de objeto HTML en el que se convierten los objetos del patrón rup_tab en el paso de resumen. Su valor por defecto es <h4 />.

• labelElement: Indica el tipo de objeto HTML en el que se convierten los objetos label en el paso de resumen. Su valor por defecto es <span />.

• labelSeparatorElement: Indica el tipo de objeto HTML que se utilizará para separar los valores de sus correspondientes labels en el paso de resumen. Su valor por defecto es <span />.

Page 10: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 11/18

• labelSeparatorText: Indica el contenido del objeto HTML que se utilizará para separar los valores de sus correspondientes labels en el paso de resumen. Su valor por defecto es &nbsp;&nbsp;&nbsp;.

Ejemplo:

<span class ="rup-wizard_summaryLabel">Nombre</ span > <span class="rup-wizard_separator"> </span>

<span class ="rup-wizard_summaryValue">Juan </ span >

• textareaElement: Indica el tipo de objeto HTML en el que se convierten los objetos textarea en el paso de resumen. Su valor por defecto es <p />.

NOTA: La numeración de los pasos comienza en cero.

7. Funciones

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

• step: Selecciona el paso recibido como parámetro. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "step", 1 );

• first: Selecciona el primer paso del asistente. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "first" );

• last: Selecciona el último paso del asistente. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "last" );

• getCurrentStep: Devuelve el número del paso actual. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "getCurrentStep" );

• isCurrentStep: Indica si el paso recibido como parámetro es el activo. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "isCurrentStep", 1 );

• isCurrentStepFirst: Indica si el paso activo es el primero. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "isCurrentStepFirst" );

• isCurrentStepLast: Indica si el paso activo es el último. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "isCurrentStepLast" );

• isCurrentStepSummary: Indica si el paso activo es el resumen. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "isCurrentStepSummary" );

• enableStep: Habilita el paso recibido como parámetro. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "enableStep", 1 );

• disableStep: Deshabilita el paso recibido como parámetro. La invocación se realizará de la siguiente manera:

Page 11: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 12/18

$( selector ) .rup_wizard ( "disableStep", 1 );

• isStepDisabled: Indica si el paso recibido como parámetro está deshabilitado. La invocación se realizará de la siguiente manera:

$( selector ) .rup_wizard ( "isStepDisabled", 1 );

NOTA: La numeración de los pasos comienza en cero.

8. Estructura

A continuación se detalla la estructura que debe seguir el formulario a convertir en wizard.

Cada paso del wizard estará formado por un fieldset y la descripción del paso se definirá dentro del fieldset mediante la etiqueta legend. Un ejemplo de la estructura:

<form id ="wizardForm"> <fieldset >

<legend >Paso primero </ legend > ...

</ fieldset > <fieldset >

<legend >Paso segundo </ legend > ...

</ fieldset > ...

<fieldset > <legend >Paso n </ legend > ...

</ fieldset > </form >

Una vez definida la estructura bastará con lanzar el componente para obtener el wizard con la siguiente estructura (se han obviado los estilos, detallados en otro apartado más adelante, para facilitar la comprensión):

<ul id ="steps"> <li id ="stepDesc0"> <span> 1. Paso primero </span>

</li> <li id ="stepDesc1"> <span> 2. Paso segundo </span>

</li>

...

<li id ="stepDescn"> <span> n. Paso enésimo </span>

</li> </ul> <form id ="wizardForm">

<div id ="step0"> <fieldset >

<legend >Paso primero </ legend > ...

</ fieldset >

Page 12: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 13/18

</ div > <div id ="step1"> <fieldset >

<legend >Paso segundo </ legend > ...

</ fieldset > </ div >

...

<div id ="stepn"> <fieldset >

<legend >Paso enésimo </ legend > ...

</ fieldset > </ div >

</ form >

Por lo expuesto anteriormente se deduce que la conversión de la estructura inicial en asistente paso a paso es la siguiente:

Se genera una lista no numerada UL que contiene los enlaces a los diferentes pasos. Estará al mismo nivel que el formulario y su identificador será steps.

La lista no numerada contendrá un elemento de lista LI por cada paso definido en el asistente. Los identificadores de los elementos de la lista serán correlativos y con la nomenclatura siguiente: stepDescX (siendo x un número comenzando en 0).

Cada elemento de la lista alojará en su interior un SPAN donde se define el texto del paso. Este texto se obtendrá del legend del paso correspondiente.

Los fieldsets que definen los diferentes pasos serán recubiertos con una capa DIV. El identificador de este elemento serán correlativos y con la nomenclatura siguiente: stepX (siendo x un número comenzando en 0).

9. Resumen (conversiones)

El patrón wizard genera por defecto un paso Resumen donde se muestran en texto plano los diferentes datos introducidos en los pasos anteriores. A continuación se detalla la conversión realizada con los diferentes elementos posibles. Se han omitido los estilos que se detallan en el siguiente apartado.

9.1. INPUT

En este apartado se detallan las conversiones de los diferentes tipos de los elementos de introducción de datos, que se transformarán en elementos span.

text

<input type="text" id ="nombre" name="nombre" />

<span >Juan <span />

password: Caracteres cambiados por *

<input type="password" id ="password" name="password" />

Page 13: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 14/18

<span >***** <span />

radio: Solo se mostrará el elemento seleccionado

<input type="radio" name="group1" value ="hombre" id ="radio_hombre" checked ="checked"/> <input type="radio" name="group1" value ="mujer" id ="radio_mujer"/> <span >Hombre <span />

checkbox: Cada elemento irá precedido de un par de corchetes [ ] y los elementos seleccionados contendrán una equis en su interior [X]

<input type="checkbox" name="mes_enero" value ="0"/> <input type="checkbox" name="mes_febrero" value ="1"/> <input type="checkbox" name="mes_marzo" value ="2"/> <span >[X] <span /> <span >[ ] <span /> <span >[ ] <span />

9.2. TEXTAREA

Los elementos de tipo textarea se convierten en elementos paragraph (<p>). Opcionalmente se puede configurar el elemento en el que se convierte mediante el parámetro textareaElement .

<textarea id ="aficiones" name="aficiones" cols ="150" rows ="10"></ textarea>

<p>Esto es un ejemplo de texto </p>

9.3. SELECT (combo)

Los combos se convierten en elementos span, que mostrará el label (literal) del elemento seleccionado.

<select id ="ejie"> <option value ="0" selected ="selected">No</ option > <option value ="1">Sí </ option >

</ select>

<span> No</span>

9.4. LABEL

Los elementos de tipo label se convierten en elementos span. Opcionalmente se puede configurar el elemento en el que se convierte mediante el parámetro labelElement .

<label for ="username">Usuario </ label>

<span> Usuario </span>

Page 14: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 15/18

9.5. Componentes RUP

Además de los elementos básicos de HTML se pueden incluir componentes RUP en el asistente paso a paso y a continuación se detalla su correspondiente conversión.

9.5.1. Accordion

Cuando se duplica un accordion en el paso de resumen simplemente se modifica el identificador que contiene el accordion pasando a llamarse como su original con el literal “_summary” concatenado al final. Para configurar el funcionamiento del accordion se utilizará el parámetro rupAccordion.

<div id ="meses">

<h1><a>Jornada reducida </ a></ h1>

...

</ div >

<div id="meses_summary">

<h1><a>Jornada reducida </ a></ h1>

...

</ div >

9.5.2. Combo

En el procesamiento de este elemento se debe eliminar los elementos sobrantes para mostrar el literal del elemento seleccionado bajo un span.

9.5.3. Date

En el procesamiento de este elemento se debe eliminar los elementos sobrantes, en este caso la imagen para seleccionar fecha.

9.5.4. Time

En el procesamiento de este elemento se debe eliminar los elementos sobrantes, en este caso la imagen para seleccionar hora.

9.5.5. Tabs

El procesamiento de las pestañas se realiza mediante un algoritmo recursivo que comprueba los diferentes niveles de las pestañas y los procesa. Se realizan las siguientes transformaciones:

El nombre de la pestaña (originalmente contenido en una lista no numerada) se traduce en un elemento <h4 /> que opcionalmente se puede configurar mediante el parámetro rupTabsElement .

El contenido de la pestaña (capa) se extrae de la capa adicional que la contiene (generalmente con un identificador del tipo “rupRandomLayerId-?”). En caso de que la

Page 15: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 16/18

pestaña sea una sub-pestaña, su identificador se verá modificado añadiéndole “subtab_” por delante.

A continuación se detalla un ejemplo para mejorar la comprensión:

<div id ="tabs">

<ul > <li>< a><div> Pestaña 1 </div></ a></li> <li>< a><div> Pestaña 2 </div></ a></li>

</ul> <div id ="rupRandomLayerId-0">

<div id ="pest2"> <ul >

<li>< a><div> Subpestaña 2.1 </div></ a></li> <li>< a><div> Subpestaña 2.2 </div></ a></li>

</ul> </div>

<div id ="rupRandomLayerId-1"> <div id ="pest22">

<!-- Contenido 2.2--> </div>

</ div > <div id ="rupRandomLayerId-2">

<div id ="pest21"> <!-- Contenido 2.1-->

</div> </ div >

</ div > <div id ="rupRandomLayerId-3">

<div id ="pest1"> <!-- Contenido 1-->

</div> </ div >

</ div > La conversión del rup-tab sería la siguiente:

<h4>Pestaña 1 </h4> <div id ="pest1"><!-- Contenido 1--> </div> <h4>Pestaña 2 </h4> <div id ="subtab_pest2">

<h4> Subpestaña 2.1 </h4> <div id ="pest21"><!-- Contenido 2.1--> </div> <h4>Subpestaña 2.2 </h4> <div id ="pest22"><!-- Contenido 2.1--> </div>

</div>

10. Sobreescritura del theme

El componente wizard se presenta con una apariencia visual definida en el fichero de estilos theme.rup.wizard-x.y.z.css.

Page 16: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 17/18

A continuación se detallan los estilos:

.rup-wizard_stepsDescContainer � UL que contiene los diferentes pasos.

.rup-wizard_stepDesc � Cada uno de los pasos (LI).

.rup-wizard_stepDesc:hover � Cada uno de los pasos (LI) con el ratón encima.

.rup-wizard_stepDesc.current � Paso activo (LI).

.rup-wizard_stepDesc.disabled � Paso deshabilitado (LI).

.rup-wizard_firstStepDesc � Primer paso.

.rup-wizard_lastStepDesc � Último paso (sin tener en cuenta el paso resumen).

.rup-wizard_summary � Paso resumen.

.rup-wizard_stepDesc span � Descripción de cada paso (texto).

Se detalla un ejemplo con su estructura:

<ul id ="steps" class ="rup-wizard_stepsDescContainer">

<li id ="stepDesc0" class ="rup-wizard_stepDesc rup-wizard_firstStepDesc current">

<a href ="#">1. Datos de la cuenta </ a> </ li > <li id ="stepDesc1" class ="rup-wizard_stepDesc

disabled"> <a href ="#">2. Deshabilitado </ a>

</ li > <li id ="stepDesc2" class ="rup-wizard_stepDesc">

<a href ="#">3. Datos del trabajador </ a> </ li > <li id ="stepDesc3" class ="rup-wizard_stepDesc">

<a href ="#">4. Plan de trabajo </ a> </ li > <li id ="stepDesc4" class ="rup-wizard_stepDesc

rup-wizard_summary rup-wizard_lastStepDesc">

<a href ="#">5. Resumen </ a> </ li > </ ul >

Existen estilos asociados a los botones “Anterior” y “Siguiente” que se utilizan para navegar entre los pasos:

.rup-wizard_prev � Botón “Anterior”.

.rup-wizard_next � Botón “Siguiente”.

.rup-wizard_submitButton � Botón “Enviar”.

Estilos asociados a las imágenes para decorar el wizard:

Paso no activo: .rup-wizard_stepDesc a

Page 17: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 18/18

Paso anterior al activo: .rup-wizard_stepDesc.visited a

Paso activo: .rup-wizard_stepDesc.current a

Último paso (no activo): .rup-wizard_lastStepDesc a

Último paso (activo): .rup-wizard_lastStepDesc.current a

10.1.1. Tabs

Cuando se genera el paso resumen y este va a contener algún elemento rup-tabs se realiza una trasformación para modificar la estructura final de la página como se explica el en apartado anterior.

A la hora de realizar dicha transformación existen dos opciones:

Convertir las pestañas en un rup-accordion con lo que la configuración de los estilos se realiza a través de las clases del componente.

No realizar la conversión las pestañas traduciéndose a texto plano (combinación de h4 y div).

Para personalizar la visualización de las pestañas en el resumen se han definido los siguientes estilos:

.rup-wizard_tabLevel-? � Elemento pestaña

.rup-wizard_tabContainerLevel-? � Elemento contenedor de pestañas

Como el componente pestañas permite definir tantos niveles de pestañas como se desee, también los estilos deben poder seguir esa jerarquía de niveles. Es por ello que los estilos aplicados a las diferentes pestañas y subpestañas van aumentando el valor definido con la “?” según se profundiza en los diferentes niveles.

Ejemplo:

.rup-wizard_tabLevel-0

.rup-wizard_tabLevel-1

...

.rup-wizard_tabLevel-n

RUP por defecto trae los estilos de los primeros niveles (0, 1 y 2) aunque se pueden definir tantos como se necesiten.

Page 18: UDA-Componentes RUP. Wizard

Componentes RUP – Wizard 19/18

A la hora de definir las pestañas de un componente rup-tabs existen elementos que contienen datos directamente, es lo que hemos denominado pestañas. Aunque también existen elementos que contienen subpestañas en los que no se contienen datos. Estos últimos elementos los hemos denominado contenedores de pestañas. En función del tipo de elemento que se procesa a la hora de procesar las pestañas se asignará un estilo u otro.

11. Integración con UDA

No aplica.