API documentation

Content:

• autocomplete( url or data, [options] )
• result( handler )
• search([handler] )
• flushCache( )
• setOptions( options )
• unautocomplete( )

##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 the next arguments:
• a default event object as first
• the selected list item as second argument
• formatted value is value that is inserted into inputfield

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

or

• handler Function
  Defines a function that replace the default trigger of result event.
  function(result) gets one argument result, an object containing data(array/string of row data), result and value. The result object is only defined when the search term exists.

Default action:

$input.trigger("result", result && [result.data, result.value])

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
});

unautocomplete( )

Returns: jQuery

Removes autocomplete from input.

Arguments:

• no arguments

Example:

Clicking on #clear removes from all input elements the autocompleter.

$("#clear").click(function() {
	$(":input").unautocomplete();
});