UDA-Componentes RUP. Autocomplete (v2.1.0 deprecado)

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

UDA - Utilidades de desarrollo de aplicaciones

Componentes RUP – Autocomplete

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

Componentes RUP – Autocomplete ii/17

Control de documentación

Título de documento: Componentes RUP – Autocomplete

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.0 14/12/2011 Nuevos métodos getRupValue y setRupValue para la interacción con los demás componentes RUP. Nuevas propiedades labelName y valueName.

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.1 13/03/2014 Nuevo método set.

Cambios producidos desde la última versión

Nuevo método set.

Control de difusión

Responsable: Ander Martínez

Aprobado por:

Firma: Fecha:

Distribución:

Componentes RUP – Autocomplete iii/17

Referencias de archivo

Autor:

Nombre archivo:

Localización:

Componentes RUP – Autocomplete iv/17

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

7. Funciones 10

8. Eventos 12

9. Sobreescritura del theme 13

10. Internacionalización (i18n) 14

11. Integración con UDA 15

Componentes RUP – Autocomplete 5/17

1. Introducción

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

En cuanto el usuario comienza a escribir una búsqueda se le sugieren búsquedas relacionadas con lo que ha escrito que pueden ser de su interés.

2. Ejemplo

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

3. Casos de uso

Se recomienda el uso del componente:

• Cuando se desea mejorar la búsqueda ofreciendo sugerencias a los usuarios.

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

Ruta theme: rup/basic-theme/

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

• jquery.ui.autocomplete.js

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

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

• theme.rup.autocomplete-z.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á todos los elementos sobre los que se va a aplicar el componente Autocomplete. Por ejemplo:


$("#id_input").rup_autocomplete(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.

Para facilitar la gestión de los datos del formulario, el input sobre el que se aplica el componente pasará a tener como nombre su nombre original seguido de “_label” y contendrá la descripción del valor seleccionado. El valor interno se guardará en un campo oculto cuyo nombre será el nombre original del input sobre el que se aplica el componente. Veámoslo con un ejemplo:

1. Se define el input sobre el que se aplica el componente:

<input id =lenguaje name=lenguaje />

2. Se invoca el componente sobre el input:

$( "#lenguaje" ). rup_autocomplete ({...});

3. Se modifica el código HTML y se convierte en:

<input id =” lenguaje_label” name=” lenguaje_label” ruptype =”autocomplete” ... />

<hidden id =” lenguaje” name=” lenguaje” ” ruptype =”autocomplete” ... />

6. Propiedades

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

• source: este parámetro determina el tipo de autocomplete: local o remoto y define los datos que va a tener el autocomplete.

o remoto se define la url a la que se solicitan los datos a cargar:

source : "autocomplete/remote"

Los datos devueltos por el servidor deberán seguir esta estructura JSON:

[ {label: "Autocomplete_es", value:"Autocomplete"}, {label: "Combo_es", value:"Combo"}, {label: "Dialog_es", value:"Dialog"}, ...

]

o local puede ser de dos tipos si los literales a mostrar dependen del idioma o no:

� sin dependencia: se define un array en JSON con los datos:

source : ["asp", "c", "c++", "coldfusion", "groovy", "haskell", "java", "javascript", "perl", "php", "python", "ruby", "scala"]


� con dependencia: se define un array en JSON de objetos con su valor (value) y su literal a mostrar (i18nCaption):

source : [ {i18nCaption: "asp", value:"asp_value"}, {i18nCaption: "c", value:"c_value"}, {i18nCaption: "c++", value:"c++_value"}, {i18nCaption: "coldfusion", value:"coldfusion_va lue"}, ...

]

• sourceParam: en el caso de un autocomplete remoto, deben configurarse los siguientes datos:

o label: nombre de la columna de BBDD de la que se extrae la descripción (el literal a mostrar).

o value: nombre de la columna de BBDD de la que se extrae el valor.

Por ejemplo:

sourceParam: {

label:"desc_"+$.rup.lang,

value:"code"

}

NOTA: En caso de utilizar una disposición horizontal para el idioma (varias columnas según idioma) se podrá hacer uso de la función “$.rup.lang” que devuelve el idioma actual (es, eu,…) para concatenarlo al nombre de la columna y obtener así el nombre de la columna que se desea.

• minLength: define el número mínimo de caracteres a introducir antes de que se lance la búsqueda de datos. El valor por defecto en la búsqueda local es de 1 carácter, mientras que en remoto es de 3 caracteres mínimo, es decir que si se define un valor mayor se sobrescribe pero no con un valor menor.

• disabled: determina si se deshabilita el componente Autocomplete sobre el input al que se aplica. De tal modo que por mucho que se interactué con el elemento no se hará una búsqueda. Su valor por defecto es false .

• delay: indica en milisegundos el tiempo que se espera entre que se pulsa una tecla y se lanza la búsqueda de los datos. Su valor por defecto es 300 .

• defaultValue: valor que se cargará por defecto en el input y con el que se lanzará una búsqueda para mostrar valores propuestos.

• contains: valor que determina si la búsqueda debe ser del tipo “contiene” (se buscarán elementos que contengan en cualquier posición el literal introducido) o del tipo “comienza por” (se buscarán elementos que comiencen por el literal introducido). El valor por defecto es true .

NOTA: Se tiene en cuenta que el valor indicado para lanzar sugerencias deba cumplir el tamaño mínimo (minLength) o no se hará la búsqueda.


• valueName: determina el valor de la propiedad name del campo que utilizará internamente el componente para almacenar el identificador del elemento seleccionado por el usuario. En caso de no especificarse, se tomará como valor el valor de la propiedad name del elemento sobre el cual se ha definido el componente.

• labelName: : determina el valor de la propiedad name del campo que utilizará internamente el componente para almacenar el texto del elemento seleccionado por el usuario. En caso de no especificarse, se tomará como valor el valor de la propiedad name del elemento sobre el cual se ha definido el componente, añadiéndole el sufijo “_label”.


7. Funciones

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

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

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

• on: habilita el autocomplete (solo la parte de sugerencias). La invocación se realizará de la siguiente manera:

$( selector ) .rup_autocomplete ( "on" );

• off: deshabilita el autocomplete (solo la parte de sugerencias, el input sigue habilitado). La invocación se realizará de la siguiente manera:

$( selector ) .rup_autocomplete ( "off" );

• disable: deshabilita el autocomplete. Internamente invoca al método off. La invocación se realizará de la siguiente manera:

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

• enable: habilita el autocomplete. Internamente invoca al método on. La invocación se realizará de la siguiente manera:

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

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

o Establecer una propiedad:

$( selector ) .rup_autocomplete ( "option", "minLegth", 2 );

o Establecer varias propiedades:

$( selector ) .rup_autocomplete ( "option", {minLegth:2, delay:1000} );

• search: lanza una búsqueda en el autocomplete con el parámetro indicado y el foco va a parar al input. La invocación se realizará de la siguiente manera:

$( selector ) .rup_autocomplete ( "search", "java" );

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

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


• val: devuelve el valor del autocomplete. Este es el valor que se guarda en el campo oculto antes descrito al final del apartado 7. La invocación se realizará de la siguiente manera:

$( selector ) .rup_autocomplete ( "val" );

Para obtener la descripción (dato que se muestra en el input) se invocará a la función estándar de jQuery:

$( selector ) .val() ;

• getRupValue: método utilizado para obtener el valor del componente. Este método es el utilizado por el resto de componentes RUP para estandarizar la obtención del valor del Autocomplete.

$( selector ) .rup_autocomplete ( "getRupValue" );

• setRupValue: método utilizado para asignar el valor al componente. Este método es el utilizado por el resto de componentes RUP para estandarizar la asignación del valor al Autocomplete.

$( selector ) .rup_autocomplete ( "setRupValue",value );

• set: método utilizado para asignar el valor y el literal al componente. El valor se almacena en el campo hidden creado por el componente. El contenido indicado en la propiedad label se mostrará en el campo input del componente.

$( selector ) .rup_autocomplete ( "set",value, label );


8. Eventos

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

• create: permite asociar una función que se ejecutará cuando se cree el autocomplete. Se configura de la siguiente manera:

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

• search: permite asociar una función que se ejecutará antes de lanzar la búsqueda del autocomplete. Se configura de la siguiente manera:

$( selector ) .rup_autocomplete ({ search: function(){...} });

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

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

• focus: permite asociar una función que se ejecutará cuando se reciba el foco en el autocomplete. Se configura de la siguiente manera:

$( selector ) .rup_autocomplete ({ focus: function(){...} });

• select: permite asociar una función que se ejecutará cuando se seleccione un valor del autocomplete. Se configura de la siguiente manera:

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

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

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


9. Sobreescritura del theme

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

Ejemplo base de la estructura generada por el componente:

<input class ="ui-autocomplete-input" /> <ul class ="ui-autocomplete ui-menu ui-widget ui-widget-conten t ui-corner-all" > <li class ="ui-menu-item" > <a class ="ui-corner-all" >item 1 </ a> </ li > <li class ="ui-menu-item" > <a class ="ui-corner-all" >item 2 </ a> </ li > <li class ="ui-menu-item" > <a class ="ui-corner-all" >item 3 </ a> </ li > </ ul >


10. Internacionalización (i18n)

La internacionalización se realiza mediante el fichero de recursos definido para la aplicación que se encontrará en la parte estática bajo codAplic/resources/codAplic.i18n.json (con sus variantes según idioma ej: codAplic/resources/codAplic.i18n_es.json). En dicho fichero se deberá declarar un objeto JSON cuyo nombre sea el mismo que el id del elemento html sobre el que se aplica el componente. Ejemplo:

"lenguaje" : { "asp":"asp_es", "c":"c_es", "c++":"c++_es", "coldfusion":"coldfusion_es", "groovy":"groovy_es", "haskell":"haskell_es", "java":"java_es", "javascript":"javascript_es", "perl":"perl_es", "php":"php_es", "python":"python_es", "ruby":"ruby_es", "scala":"scala_es" }


11. Integración con UDA

El componente Autocomplete permite recuperar los datos almacenados en base de datos. Para ello se requiere cierta configuración en el Controller al que se invoca.

Se deben declarar dos parámetros (que el componente envía automáticamente):

� q: termino introducido en el input. El termino introducido podría contener comodines (wildcards) que podrían obtener datos no deseados como son el carácter “_” que equivale a cualquier carácter o el carácter “%” que equivale a cualquier literal. Por ello en la petición al servidor se envía escapados automáticamente. Ejemplo de una petición con los caracteres escapados:

http://localhost:7001/x21aDemoWAR/fase3/autocomplete/remote?q=\%\%\%\%&c=false

� c: booleano que determina si la búsqueda es del tipo “contiene” (true) o del tipo “empieza por” (false).

El Service que invoca el Controller tendrá el método findAllLike (entidad, paginación, c) (si se ha generado con el plugin UDA) que se empleará para realizar la búsqueda. Sus parámetros son los siguientes:

� entidad: objeto creado por el desarrollador que contendrá en el campo por el que se desea buscar el termino introducido:

MiEntidad miEntidad = new Entidad();

miEntidad.setCampoBusqueda(q);

� paginación: objeto empleado para hacer filtrados/paginaciones. En el ejemplo actual se manda null ya que no se requiere esta funcionalidad.

� c: parámetro enviado por el componente que determina el tipo de búsqueda.

A continuación se muestra un ejemplo (se destacan con fondo gris los elementos a configurar):

@RequestMapping (value = "autocomplete/remote" , method=RequestMethod. GET) public @ResponseBody List<Patrones> getRemoteAutocomplete( @RequestParam(value = "q" , required = true ) String q, @RequestParam(value = "c" , required = true ) Boolean c){ //Idioma Locale locale = LocaleContextHolder. getLocale( ); //Filtro según idioma Patrones patrones = new Patrones(); if (com.ejie.x38.util.Constants. EUSKARA.equals(locale.getLanguage())

){ patrones.setDescEu(q); } else { patrones.setDescEs(q); }


return patronesService .findAllLike(patrones, null , c);

}

El método devuelve una lista de entidades en este caso List<Patrones> donde cada entidad tendrá todos y cada uno de los atributos cargados con los valores de la Base de Datos. Al devolver la lista con la anotación @ResponseBody, entrará en funcionamiento Jackson (parseador de JSON de Spring) para convertir la lista JAVA en una lista JSON:

� JAVA:

patronesList :

patronesList [0] � code = Autocomplete

descEs = Autocomplete_es

descEu = Autocomplete_eu

css = filter

patronesList [1] � code = Combo

descEs = Combo_es

descEu = Combo_eu

css = print

…

� JSON:

[ {code="Autocomplete", descEs="Autocomplete_es",

descdescEu="Autcomplete_eu", css="filter" }, {code="Combo", descEs="Combo_es",

descEu="Combo_eu", css="print" }, …

]

Como se ha explicado en anteriormente en el atributo source en el apartado 8 (propiedades) el componente requiere de una estructura de terminada para cargar el combo:

[ {label: "Autocomplete_es", value:"Autocomplete", s tyle:"aaa"}, {label: "Combo_es", value:"Combo ", style:"bbb"}, {label: "Dialog_es", value:"Dialog", style:"ccc"}, ... ]

La traducción entre la estructura devuelta por el controller y la que espera el componente se realiza mediante un serializador propio de UDA. Para que este entre en funcionamiento simplemente se deberá configurar el fichero mvc-config del WAR (/xxxWAR/WebContent/WEB-INF/spring/mvc-config.xml) indicando que el modelo utilizado utilice el serializador de UDA:

<bean id ="jacksonJsonCustomSerializerFactory" class ="com.ejie.x38.serialization.CustomSerializerFactory Registry" > < property name="serializers" >


<map> <entry key ="com.ejie.x21a.model.Patrones" value-ref ="customSerializer" /> ... </ map> </ property >

</ bean >

Para que la serialización se realice correctamente, el componente envía en la petición una cabecera de RUP con la información necesaria para realizar la serialización.

{"label":"descEs","value":"code","style":"css"}

NOTA: Al generar el código con el plugin de UDA, se añade este serializador para todos los objetos del modelo creados.

Technology

UDA-Componentes RUP. Autocomplete (v2.1.0 deprecado)