Autocompleter-neo NPM

Autocompleter Neo

Este paquete cuenta con un componente principal llamado GoigSearch que a su vez contiene un componente de input de texto y un diálogo. El diálogo muestra sugerencias de direcciones y sitios de interés de la Ciudad Autónoma de Buenos Aires dependiendo del texto que se escriba en el input, siendo posible navegar por las opciones con el teclado, al presionar la tecla Enter se realiza la búsqueda del texto ingresado. El resultado puede ser manipulado a través de la función handleSearch que se pasa como parámetro al componente principal.

Instalación y configuración

Instalar el paquete

npm install autocompleter-neo

Importar el paquete

Importar el componente principal GoigSearch con su instancia de Autocompleter.
Importar SuggesterOptions, que contiene todos los posibles suggesters (por el momento existen AddressSuggester y PlaceSuggester).
Importar neoAutocompleter que contiene las instancia de Autocompleter.
En el caso de estar utilizando TypeScript, es posible importar la interfaz SearchResponse para tipar el resultado de la búsqueda.
Es posible también importar SkinOptions con las skins que contiene el paquete, la skin por defecto es goigLight.

import React, { useEffect, useRef } from "react";

import GoigSearch from "./components/GoigSearch/GoigSearch";
import { SkinOptions } from "./models/Options/SkinOptions";
import neoAutocompleter from "./services/NeoAutocompleter";
import { SearchResponse } from "./models/Responses/SearchResponse";

import "./App.scss";

Configuración

Para que el paquete realice las peticiones, es necesario configurar credenciales.

neoAutocompleter.setCredentials(process.env.CLIENT_ID, process.env.CLIENT_SECRET);

Función requerida

Es la función que permite manipular el resultado de la búsqueda, se debe pasar como parámetro al componente principal.

const handleSearch = (searchResult: SearchResponse) => {
        console.log("searchResult", searchResult);
    };

Configuración del Suggester

Se pueden elegir los parámetros de configuración o se tomarán los valores por defecto.
Los parámetros de configuración son:
- minTextLength: el mínimo de caracteres necesarios para iniciar una búsqueda. El valor por defecto y mínimo posible de este parámetro es 3.
- waitingTime: el tiempo que se va a esperar antes de iniciar una búsqueda. El valor por defecto es 1000, el mínimo posible es 500 y su unidad es milisegundos.
- maxSuggestions: la cantidad máxima de sugerencias que aparecen en el diálogo. El valor por defecto y máximo posible de este parámetro es 10.
Se sugiere colocarlo dentro de un useEffect como en el ejemplo para que sólo se ejecute 1 vez.

const minTextLength = 4;
const waitingTime = 500;
const maxSuggestions = 5;

useEffect(() => {
    neoAutocompleter.getSuggesters()["AddressSuggester"].setConfigurations(minTextLength,waitingTime,maxSuggestions)
    neoAutocompleter.getSuggesters()["PlaceSuggester"].setConfigurations(minTextLength,waitingTime,maxSuggestions)
}, []);

Componente principal

Props (opcionales) del componente principal:

getSearchResult (función) que permite manipular el resultado de la búsqueda.
skin (string) permite cambiar el la paleta de colores del componente Dialog. Las posibles opciones están en SkinOptions (goigLight y goigDark).
placeholder (string) permite agregar un texto al component Input
legeneds (boolean) permite agregar leyendas para los distintos tipos de Suggesters
childRef (hook) es posible agregar un botón que realice la búsqueda. Para esto, es necesario instanciar useRef y crear una función manejador del evento click. Con la propiedad current del useRef es posible capturar la función getSearch(), la cual permite realizar la búsqueda.

Ejemplo completo

const goigComponentRef = useRef<{ getSearch: () => void }>(null);

const handleSearch = (searchResult: SearchResponse) => {
        console.log("searchResult", searchResult);
    };

const handleParentClick = () => {
    if (goigComponentRef.current) {
        goigComponentRef.current.searchAddress();
    }
};

return (
    <div className="main-app">
        <GoigSearch
            skin={SkinOptions.goigDark}
                getSearchResult={(searchResult: SearchResponse) => handleSearch(searchResult)}
                placeholder=""
                childRef={goigComponentRef}
                legends={true}
        />
        <button className="button-search" onClick={handleParentClick}>
            Buscar
        </button>
    </div>
);

Ejemplo basico

const handleSearch = (searchResult: SearchResponse) => {
        console.log("searchResult", searchResult);
    };

return (
    <div className="main-app">
        <GoigSearch getSearchResult={(searchResult: SearchResponse) => handleSearch(searchResult)}} />
    </div>
);

Aclaraciones

El diálogo que muestra las sugerencias tiene definido un z-index: 100.

Suggesters

AddressSuggester

Sugiere y busca direcciones dentro de la Ciudad Autónoma de Buenos Aires y devuelve su información.

Las opciones de búsqueda son:

Para Direcciones: - Calle: devuelve las coordenadas del inicio de la calle. - Calle y altura: devuelve las coordenadas de la puerta buscada. - Intersección de calles: devuelve las coordenadas de la esquina.

Para Sitios de Interés - Sitios de interés: devuelve coordendas e información del sitio.

Ejemplo de respuesta de AddressSuggester

{
    "altura": null,
    "barrio": "PALERMO",
    "codCalle_1": 1736,
    "codCalle_2": null,
    "codPartido": "CABA",
    "comuna": "Comuna 14",
    "coordenada_x": -58.4353511196483,
    "coordenada_y": -34.57492803603612,
    "direccion": "CABILDO AV.",
    "manzanaInf": null,
    "nombreCalle_1": "CABILDO AV.",
    "nombreCalle_2": null,
    "nombreLocalidad": "CABA",
    "nombrePartido": "CABA",
    "parcelaInf": null,
    "sectorInf": null,
    "smp": "023-005-000B",
    "tipoCatastro": "formal",
    "tipoDireccion": "calle_altura"
}

Ejemplo de respuesta de PlaceSuggester

{
"categoria":"SALUD",
"coordenadas":
{
    "x":-58.40051657411195,
    "y":-34.58476564075079
},
"direccion":"LAS HERAS GENERAL AV. 2670",
"id_categoria":2,
"id_sitio":1,
"nombre":"HOSP. GENERAL DE AGUDOS B. RIVADAVIA"
}

Configuraciones

Parámetro	Descripción	Default
minTextLength	Mínimo de caracteres con el que empieza la búsqueda. (Mínimo 3).	3
waitingTime	El tiempo que espera para iniciar la búsqueda. (Mínimo 500).	1000
maxSuggestions	La cantidad máxima de respuestas. (Máximo 10).	10

Modificaciones estéticas

En caso de ser necesario, se puede modificar la estética de los componentes mediante SCSS o CSS.

Hay 3 clases principales que pueden ser modificadas:

goig-input: para modificar el input de texto.
goig-suggestion-container: para modificar el diálogo de sugerencias.
goig-error-container: para modificar el diálogo de error.

Notese que en el caso de modificar el tamaño del input de texto, va a ser necesario mover los dialogos. Y en caso de necesitar modificar el valor de la propiedad z-index tener en cuenta que debe modificarse tanto GoigDialog como GoigDialogError.

Ejemplo

.goig-input {
    height: 32px;
}

.goig-suggestion-container {
    top: 43px;
    z-index: 100;
}

.goig-error-container {
    top: 43px;
    z-index: 100;
}

Advertencia

Este método no debe ser usado para posicionar el componente a lo largo de su aplicación, solo en el caso de necesitar redimensionar los objetos debe usarse el reposicionamiento de los mismos.

Ejemplo completo

import React, { useEffect, useRef } from "react";

import GoigSearch from "./components/GoigSearch/GoigSearch";
import { SkinOptions } from "./models/Options/SkinOptions";
import neoAutocompleter from "./services/NeoAutocompleter";
import { SearchResponse } from "./models/Responses/SearchResponse";

import "./App.scss";


function App() {
    const goigComponentRef = useRef<{ getSearch: () => void }>(null);

    const minTextLength = 3;
    const waitingTime = 500;
    const maxSuggestions = 1;

    //Importar credenciales desde variables de entorno
    const CLIENT_ID = import.meta.env.VITE_API_CLIENT_ID;
    const CLIENT_SECRET = import.meta.env.VITE_API_CLIENT_SECRET;
    
    useEffect(() => {

        neoAutocompleter.getSuggesters()["AddressSuggester"].setConfigurations(minTextLength,waitingTime,maxSuggestions)
        neoAutocompleter.getSuggesters()["PlaceSuggester"].setConfigurations(minTextLength,waitingTime,maxSuggestions)
        neoAutocompleter.setCredentials(CLIENT_ID, CLIENT_SECRET);
    }, []);    

    const handleSearch = (searchResult: SearchResponse) => {
        console.log("searchResult", searchResult);
    };

    const handleParentClick = () => {
        if (goigComponentRef.current) {
            goigComponentRef.current.getSearch();
        }
    };

    return (
        <div className="main-app">
            <GoigSearch
                skin={SkinOptions.goigDark}
                getSearchResult={(searchResult: SearchResponse) => handleSearch(searchResult)}
                placeholder=""
                childRef={goigComponentRef}
                legends={true}
            />
            <button className="button-search" onClick={handleParentClick}>
                Buscar
            </button>
        </div>
    );
}

export default App;