API documentation

##autocomplete( url or data, options )

Makes an input or textarea autocompleteable.

$("#input").autocomplete( url or data, [options] )

Arguments:

url or data String or Array The first argument as string, is read as an URL pointing at a remote resource. An array is taken as local data.

For remote data:
When the user starts typing, a request is send to the specified backend ("search.php"), with a GET parameters:

• q: that contains the current value of the input box
• limit: with the (default) value specified for the max option
• timestamp: current time (added by jQuery.ajax)

Input value "foo" would result in this request url:

search.php?q=foo&limit=150&timestamp=1320325727677

The result must return with one value on each line. The result is presented in the order the backend sends it.

Example response:

Key1|value1
Key2|value2
Key3 on this line |value3
Key4|value4

Example serverside script

<?php
$q = strtolower($_GET["q"]);
if (!$q) return;
$items = array(
	"Great <em>Bittern</em>"=>"Botaurus stellaris",
	"Little <em>Grebe</em>"=>"Tachybaptus ruficollis",
	"Black-necked Grebe"=>"Podiceps nigricollis",
	"Little Bittern"=>"Ixobrychus minutus",
	... ...
);

$i = 0;
foreach ($items as $key=>$value) {
	if (strpos(strtolower($key), $q) !== false) {
		echo "$key|$value\n";
		$i++;
		if($i >= (int)$_GET['limit']){
			exit;
		}
	}
}
?>

options (Optional) Options

A set of key/value pairs that configure the autocomplete. All options are optional.
Options in jQuery are plain JavaScript objects.

Extended description of all options: Options

result( handler )

Returns: jQuery

Handle the result of a search event.
Is executed when the user selects a value or a programmatic search event is triggered (see search()). You can add and remove (using unbind("result")) this event at any time.

Arguments:

• handler Function The event handler, gets a default event object as first and the selected list item as second argument.

Example:

Bind a handler to the result event to display the selected value in a #result element. The first argument is a generic event object, in this case with type "result". The second argument refers to the selected data, which can be a plain string value or an array or object. The third argument is the formatted value that is inserted into the input field.

$('input#suggest').result(function(event, data, formatted) {
	$("#result").html( !data ? "No match!" : "Selected: " + formatted);
});

search( )

Returns: jQuery

Trigger a search event. See result(Function) for binding to that event.
A search event mimics the same behaviour as when the user selects a value from the list of autocomplete items. You can use it to execute any function (bound via result() method) that does something with the selected value, beyond simply putting the value into the input and submitting it. For example, it can be useful to verify whether the entered value is an existing option.

Arguments:

• no arguments

Examples:

Triggers a search event.

$('input#suggest').search();

Verifies if the entered value was an existing option after the element loses focus.

$('input#suggest').result(function(event, data, formatted) {
	$('#result').html( !data ? "No match!" : "Selected: " + formatted);
}).blur(function(){
	$(this).search();
});

flushCache( )

Returns: jQuery

Flush (empty) the cache of matched input's autocompleters.

Arguments:

• no arguments

Example:

Flush the cache of #suggest.

$('input#suggest').flushCache();

setOptions( options )

Returns: jQuery

Updates the options for the current autocomplete field.
This allows you to change things like the URL, max items to display, etc. If you're changing the URL, be sure to call the flushCache() method.

Arguments:

• options Options
  The options to set. Extended description of all options: Options

Example:

Changes the maximum number of items to display to 15.

$('input#suggest').setOptions({
	max: 15
});