Este documento describe el componente Autocomplete de RUP. Explica cómo funciona, sus propiedades de configuración, métodos y eventos. El componente permite sugerir búsquedas relacionadas con lo que el usuario ha escrito en un input de texto para mejorar la experiencia de búsqueda.

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

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

3. Componentes RUP – Autocomplete iii/17
Referencias de archivo
Autor:
Nombre archivo:
Localización:

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

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

6. Componentes RUP – Autocomplete 6/17
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:

7. Componentes RUP – Autocomplete 7/17
$("#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"]

8. Componentes RUP – Autocomplete 8/17
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_value"},
...
]
• 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.

9. Componentes RUP – Autocomplete 9/17
• 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”.

10. Componentes RUP – Autocomplete 10/17
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");

11. Componentes RUP – Autocomplete 11/17
• 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);

12. Componentes RUP – Autocomplete 12/17
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(){...} });

13. Componentes RUP – Autocomplete 13/17
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-content 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>

14. Componentes RUP – Autocomplete 14/17
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"
}

15. Componentes RUP – Autocomplete 15/17
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);
}

16. Componentes RUP – Autocomplete 16/17
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", style:"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.CustomSerializerFactoryRegistry">
<property name="serializers">

17. Componentes RUP – Autocomplete 17/17
<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.