Autocomplete é um recurso interessante para adicionarmos em sites/sistemas, ele facilita bastante agilizando a inserção de informações dos usuário eliminando em muitos casos erros de digitação gerariam alguma dificuldade no uso. O EasyAutocomplete é um pluguin jQuery que torna bastante fácil a inserção deste recurso em nossas páginas, com ele é possível utilizar dados tanto local como remoto para o autocomplete, sendo fácil de configurar e fornecer bastante recursos, como tratamento de eventos por exemplo.

Exemplo de autocomplete com EasyAutocomplete
Exemplo de autocomplete com EasyAutocomplete

Adicionando o EasyAutocomplete

Para começar, devemos fazer como em qualquer plugin, baixe ele da página do desenvolvedor, e adicione a biblioteca do jQuery e do plugin em seu código.

<link rel="stylesheet" href="easy-autocomplete.min.css" type="text/css">
<link rel="stylesheet" href="easy-autocomplete.themes.min.css" type="text/css">

<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<script src="jquery.easy-autocomplete.min.js"></script>

O uso básico do plugin é bastante simples, basta chamar a função easyAutocomplete, passando um objeto de opções com os dados do autocomplete.


<input type="text" name="email" id="email" class="form-control" autocomplete="false">

var options = {
    data: [ 'rodrigoaramburu@gmail.com',
            'angela@gmail.com',
            'julia@hotmail.com',
            'andreson@hotmail.com',
            'marcio@gmail.com',
            'miticopazuzu@hotmail.com',
            'boteco@botecodigital.info'],
}
$('#email').easyAutocomplete(options);

Podemos ver o resultado do pequeno exemplo aqui.

Usando uma fonte de dados JSON

Embora simples, não é muito prático colocar os dados que serão utilizados para auto completar o campo dentro do próprio código, então é interessante tê-los em uma fonte externa. Uma forma muito comum de armazenar as informações é através de JSON.

[ 
    { "email" : "rodrigoaramburu@gmail.com" , "nome": "Rodrigo Aramburu"},
    { "email" : "angela@gmail.com", "nome": "Angela"},
    { "email" : "julia@hotmail.com" , "nome": "Julia"},
    { "email" : "andreson@hotmail.com" , "nome": "Anderson"},
    { "email" : "marcio@gmail.com" , "nome": "Marcio"},
    { "email" : "miticopazuzu@hotmail.com" , "nome": "Carlos"},
    { "email" : "boteco@botecodigital.info" , "nome": "Rodrigo"}
]

Acima temos um documento JSON, nele temos um array de objetos, sendo cada objeto contendo os campos de e-mail e nome de um contato. Iremos salvar este arquivo no mesmo diretório do nosso código com o nome de email.json, ele irá servir como fonte do código abaixo:

var options = {
    url: 'emails.json',
    getValue: "email",
    list: {
        match: {
            enabled: true
        }
    }
}
$('#email').easyAutocomplete(options);

No exemplo acima utilizamos o arquivo JSON, como fonte(provider) na linha 2 fornecendo seu endereço para a propriedade url. Na linha 3, através da propriedade getValue informamos qual campo do nosso documento JSON utilizaremos o valor. Se você notou no exemplo básico, o último item da nossa lista, não estava aparecendo, pois tínhamos mais mais valores do que podíamos mostrar. Isto pode ser contornado utilizando a propriedade list, que dentro dela podemos definir a propriedade match para true, assim mostrando somente os resultados que coincidem com o texto previamente digitados no campo gerando uma lista menor.

Veja o exemplo

A propriedade getValue não aceita somente uma string como valor do campo, podemos também utilizar uma função se estamos utilizando uma conjunto de dados mais complexo. A função recebe como parâmetro cada um dos elementos do array do documento JSON, e nela podemos selecionar a propriedade que queremos para o valor do auto completar.

getValue: function(element){
    return element.email;
},

Usando uma fonte de dados XML

Para utilizar uma fonte de dados XML para o auto completar, primeiramente é claro iremos precisar um documento XML com os dados. Segue abaixo um exemplo.

<?xml version="1.0" encoding="utf-8"?>
<paises>

    <pais>
        <nome>Brasil</nome>
        <codigo>BRA</codigo>
    </pais>
    <pais>
        <nome>Argentina</nome>
        <codigo>ARG</codigo>
    </pais>
    <pais>
        <nome>Uruguai</nome>
        <codigo>URU</codigo>
    </pais>
    <pais>
        <nome>Chile</nome>
        <codigo>CHI</codigo>
    </pais>
    <pais>
        <nome>Portugal</nome>
        <codigo>POR</codigo>
    </pais>
    <pais>
        <nome>Espanha</nome>
        <codigo>ESP</codigo>
    </pais>
    <pais>
        <nome>França</nome>
        <codigo>FRA</codigo>
    </pais>
    
</paises>

O documento é bastante simples somente com um nó raiz paises, e cada nó filho(pais) com os item propriamente dito. Cada nó pais tem dentro dele um nome e codigo, iremos utilizar somente o nome mesmo.

Agora o código de auto completar.

var options = {
    url: 'paises.xml',
    dataType: "xml",
    xmlElementName: "pais",
    
    getValue: function(element){
        return $(element).find("nome").text();
    },
    
    list: {
        match: {
            enabled: true
        }
    }
}
$('#pais').easyAutocomplete(options);

O código não muda muito do exemplo com JSON, apenas trocamos a url do arquivo que utilizamos como fonte(linha 2), na linha 3 definimos que o tipo de dados que estamos utilizando é XML e na linha 4 definimos que nossos elementos que queremos utilizar os dados é o nó pais. Para fazer o auto completar cada um dos nós pais será passado para a função getValue onde devemos filtrar o valor que nos interessa, neste caso pegamos via seletor jQuery o nó pais, buscamos o nó nome dentro dele e pegamos o conteúdo de texto dentro deste nó para utilizar.

Veja o exemplo

Usando uma fonte de dados Remota – AJAX

O EasyAutocomplete também pode acessar uma API para buscar seus dados, não sendo muito diferente dos exemplos anteriores, bastando passar o valor a ser pesquisado para endereço da API, vejamos como:

var options = {
    url: function(busca) {
        return "api/paises.php?busca=" + busca;
    },      
    
    getValue: function(element){
        return element.nome;
    },
    
    list: {
        match: {
            enabled: true
        }
    }
}
$('#pais').easyAutocomplete(options);

Na linha 2, em vez da passarmos um endereço em formato de string, estamos passando uma função que recebe o valor que foi digitado no campo que será auto completado como parâmetro. Este valor é necessário para a API realizar a busca em seus dados e retornar nossa resposta, no nosso caso, passamos ele como um parâmetro de url. A url que retornarmos nesta função será chamada pelo plugin.

Os demais campos das opções permanecem os mesmos. Veja o exemplo.

O EasyAutocomplete utiliza o método Ajax do jQuery para realizar a chamada, então se necessitarmos utilizar algum parâmetro diferente, como fazer a chamada via POST, devemos utilizar a propriedade de ajaxSettings para fazê-lo.

var options = {
    url: function(busca) {
        return "api/paises-post.php";
    },      
    
    getValue: function(element){
        return element.nome;
    },

    ajaxSettings: {
        dataType: "json",
        method: "POST",
        data: { }
    },

    preparePostData: function(data) {
        data.busca = $("#pais").val();
        return data;
    },
    
    list: {
        match: {
            enabled: true
        }
    }
}
$('#pais').easyAutocomplete(options);

Como vemos, trocamos a url de acesso, e adicionamos na linha 10 definimos a propriedade ajaxSettings onde definimos a o tipo de dados da requisição(dataType), o method, que irá ser utilizado para fazer a requisição e os dados (data) , neste exemplo atribuímos um objeto vazio, ao qual será adicionado uma propriedade posteriormente.

Na linha 16 é chamada a função preparePostData que tem a função de preparar os dados da requisição antes dela ser enviada, ela recebe de parâmetro o objeto data anteriormente definido em ajaxSettings , ao qual iremos adicionar nosso parâmetro de busca, que no nosso caso é o valor do conteúdo do campo auto completar, por fim retornamos o objeto modificado.

Veja o exemplo.

Eventos

O EasyAutocomplete fornece diversos eventos que nos permitem realizar chamadas em determinadas determinados momentos da sua execução. Temos as seguintes ações:

  • onSelectItemEvent: Invoca a função quando o item selecionado é alterado.
  • onLoadEvent: Invoca a função quando a lista de sugestões é carregada.
  • onClickEvent: Invoca a função quando o usuário clica em um item da lista de sugestões.
  • onKeyEnterEvent: Invoca a função quando o usuário digita “enter” no campo de entrada.
  • onChooseEvent: Invoca a função quando o usuário digita “enter” no campo de entrada ou clica em um item da lista de sugestões.
  • onMouseOverEvent: Invoca a função quando o mouse passa em cima de um item da lista de sugestões.
  • onMouseOutEvent: Invoca a função quando o mouse sai de cima de um item da lista de sugestões.
  • onShowListEvent: Invoca a função que aparece na lista de sugestões.
  • onHideListEvent: Invoca a função que oculta a lista de auto completar.

Vejamos um exemplo:

var options = {
    url: function(busca) {
        return "api/paises.php?busca=" + busca;
    },      
    
    getValue: function(element){
        return element.nome;
    },
    
    list: {
        match: {
            enabled: true
        },

        onSelectItemEvent: function() {
            var value = $("#pais").getSelectedItemData().codigo;
            $("#codigo").html(value);
        }
    }
}

Na linha 15 adicionamos na propriedade list o evento de onSelectItemEvent, que como vimos chama a função quando o item selecionado é alterado, nela pegamos o valor selecionado através da função getSelectedItemData, que retorna o objeto completo da fonte, com todas suas propriedades, permitindo pegar outro valor e exibi-lo em outra área por exemplo, no nosso caso um outro elemento com id #codigo.

Veja o exemplo.

O EasyAutocomplete fornece ainda outro recursos como templates e animações que podem ser visto no seu guia, é bastante simples e intuitivo.

Bom era isso, até a próxima 🙂