Autocomplete com jQuery EasyAutocomplete
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.
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.
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.
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 🙂