By giving an Autocomplete field focus or entering something into it, the plugin starts
searching for entries that match and displays a list of values to choose from.
By entering more characters, the user can filter down the list to better matches.
This
can be used to enter previous selected values, for example you could use Autocomplete
for entering tags, to complete an address, you could enter a city name and get
the zip code, or maybe enter email addresses from an address book.
You
can pull data in from a local and/or a remote source: Local is good for small
data sets (like an address book with 50 entries), remote is necessary for big
data sets, like a database query with hundreds or millions of entries to select
from.
Autocomplete can be customized to work with various data sources,
by just specifying the source option. A data source can be:
An Array with local data
A String, specifying a URL
A Callback
The local data can be a simple Array of Strings, or it can contain
Objects for each item in the array, with either a label or value property or
both. The label property would be displayed in the suggestion menu. The value
will be inserted into the input element after the user selected something from
the menu. If just one property is specified, it will be used for both, eg. if
you provide only value-properties, the value will also be used as the label.
When
a String is used, the Autocomplete plugin expects that string to point to a URL
resource that will return JSON data. It can be on the same host or on a different
one (if different, must provide JSONP). The request parameter "term"
gets added to that URL. The data itself can be in the same format as the local
data as above.
The third variation, the callback, provides the most
flexibility, and can be used to connect any data source to Autocomplete. The
callback gets two arguments:
A request object, with a single property
called "term", which refers to the value currently in the text input.
For example, when the user entered "new yo" in a city field, the Autocomplete
term will equal "new yo".
A response callback, which expects
a single argument to contain the data to suggest to the user. This data should
be filtered based on the provided term, and can be in any of the formats described
above for simple local data (String-Array or Object-Array with label/value/both
properties). It's important when providing a custom source callback to handle
errors during the request. You must always call the response callback even if
you encounter an error. This ensures that the widget always has the correct state.
The
label is always treated as text, if you want the label to be treated as html
you can use an html extension by Scott Gonzalez. The demos all focus on different variations of the source-option - look for the
one that matches your use case, and take a look at the code.
There are a number of options when setting up the Autocomplete. Here
is an example of how these are set:
$( ".selector" ).autocomplete({ autoFocus: true });
And another:
$( ".selector" ).autocomplete( "option", "delay", 0 );
You can view the full documentation here.
Let's wire up a simple demo using the familiar Northwind Database
(the Employees table) with an ASP.NET ASHX WebHandler providing the endpoint. First,
here's what needs to be in the markup of the page:
<!DOCTYPE
html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Auto complete demo</title>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/jquery-ui.min.js"></script>
<link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/themes/base/jquery-ui.css"
rel="stylesheet" type="text/css" />
<script type="text/javascript">
$(document).ready(function
()
{
$("#tags").autocomplete({source:
'/Autocomplete.ashx'});
});
</script>
</head>
<body>
<input type="text" id="tags" />
</body>
</html>
Note that we are using the google CDN urls to load our scripts, with specific version numbers. You want to do this as there is a good chance these scripts are already in the browser's cache. The last script simply uses the jQuery $(document).ready function to set up the autocomplete plugin on the <input ..> element with id "tags", and specify the data source. This
is all that is required for the default settings.
And here is an example handler that receives the request and returns the data
in the expected JSON format:
<%@ WebHandler Language="C#" Class="Autocomplete" %>
using System;
using System.Configuration;
using System.Data;
using System.Data.SqlClient;
using System.Web;
using System.Web.Script.Serialization;
using System.Linq;
public class Autocomplete : IHttpHandler
{
public void ProcessRequest(HttpContext context)
{
context.Response.ContentType
= "application/javascript";
string cnString = ConfigurationManager.ConnectionStrings["test"].ConnectionString;
string
sql = "SELECT Firstname + ' ' + Lastname as NAME from Employees where Lastname
like @term+ '%'";
SqlCommand cmd = new SqlCommand(sql, new SqlConnection(cnString));
cmd.CommandType=
CommandType.Text;
cmd.Parameters.AddWithValue("@term", context.Request.QueryString["term"]);
SqlDataAdapter da = new SqlDataAdapter(cmd);
DataTable
dt = new DataTable();
da.Fill(dt);
string[] items = new string[dt.Rows.Count];
int ctr = 0;
foreach
(DataRow row in dt.Rows)
{
items[ctr]
= (string) row["NAME"] ;
ctr++;
}
//convert the string array to Javascript and send it out
context.Response.Write(new JavaScriptSerializer().Serialize(items));
}
public bool IsReusable
{
get
{
return false;
}
}
}
When
the handler is requested by the Autocomplete plugin, it puts the typed in term
on the querystring as a "term" item. Our code simply needs to grab that and use it in a SQL LIKE statement to get the matching resultset. We then convert the values to a string array,pass it into the JavaScriptSerializer to convert to JSON, and send it on out as ContentType "application/javascript".
The plugin on the page will then display the choices and the user can select one. When this is done, the selected choice is populated into the <input ..> element.
You can download the complete Visual Studio 2010 Solution containing this demo here.