I should put this on the web somewhere, but for now I'll dump it on
this list. This is the first draft of documentation for my
Autocompleter. Use it to implement my plugin, or to pick up some ideas
for your own autocompleter.
Autocomplete - a jQuery plugin
Usage:
======
$("selector").autocomplete(url [, options]);
Demo page (search for English bird names, type "com" for example):
==================================================================
http://www.dyve.net/jquery?autocomplete
Advice:
=======
Make sure that selector selects on ly one element, unless you really,
really know what you are doing.
Example:
========
$("#input_box").autocomplete("my_autocomplete_backend.php");
In the above example, Autocomplete expects an input element with the
id "input_box" to exist. When a user starts typing in the input box,
the autocompleter will request my_autocomplete_backend.php with a GET
parameter named q that contains the current value of the input box.
Let's assume that the user has typed "foo"(without quotes).
Autocomplete will then request my_autocomplete_backend.php?q=foo.
The backend should output possible values for the autocompleter, each
on a single line. Output cannot contain the pipe symbol "|", since
that is considered a separator (more on that later).
An appropiate simple output would be:
foo
fool
foot
footloose
foo fighters
food fight
Note that the autocompleter will present the options in the order the
backend sends them.
Advanced options:
=================
You can pass advanced options as a JavaScript object, notation {
name:value, ..., name: value }
Example: $("#input_box").autocomplete("my_autocomplete_backend.php", {
minChars:3 });
These options are available:
wrapperClass (default value: "ac_wrapper")
The class for the DIV that will be wrapped around the input element to
contain the extra DOM elements (such as the results). Use this to
style your autocompleter.
resultsClass (default value: "ac_results")
The class for the UL that will contain the result items (result items
are LI elements).
loadingClass = (default value: "ac_loading")
The class for the input box while results are being fetched from the server.
lineSeparator = (default value: "\n")
The character that separates lines in the results from the backend.
cellSeparator (default value: "|")
The character that separates cells in the results from the backend.
minChars (default value: 1)
The minimum number of characters a user has to type before the
autocompleter activates.
delay (default value: 400)
The delay in milliseconds the autocompleter waits after a keystroke to
activate itself.
cacheLength (default value: 1)
The number of backend query results to store in cache. If set to 1
(the current result), no caching will happen. Do not set below 1.
matchSubset (default value: 1)
Whether or not the autocompleter can use a cache for more specific
queries. This means that all matches of "foot" are a subset of all
matches for "foo". Usually this is true, and using this options
decreases server load and increases performance. Remember to set
cacheLength to a bigger number, like 10.
matchCase (default value: 0)
Whether or not the comparison is case sensitive. Only important only
if you use caching.
matchContains = options.matchContains || 0;
Whether or not the comparison looks inside (i.e. does "ba" match "foo
bar") the search results. Only important if you use caching.
mustMatch (default value: 0)
If set to 1 (true), the autocompleter will only allow results that are
presented by the backend. Note that illegal values result in an empty
input box. In the example at the beginning of this documentation,
typing "footer" would result in an empty input box.
extraParams (default value: {})
Extra parameters for the backend. If you were to specify { bar:4 },
the autocompleter would call my_autocomplete_backend.php?q=foo&bar=4
(assuming the input box contains "foo").
onSelectItem (default value: none)
A JavaScript funcion that will be called when an item is selected. The
autocompleter will specify a single argument, being the LI element
selected. This LI element will have an attribute "extra" that contains
an array of all cells that the backend specified. See the source code
of http://www.dyve.net/jquery?autocomplete for an example.
More advanced options
=====================
If you want to do more with your autocompleter, you can change some
options on the fly.
The autocompleter is accessed as an attribute of the input box.
Example:
$("#input_box").autocomplete("my_autocomplete_backend.php"); // Set
the autocompleter
var ac = $("#input_box")[0].autocompleter; // A handle to our autocompleter
There are currently 2 functions that can be called to influence the
behaviour at run-time:
flushCache()
Flushes the cache
setExtraParams(obj)
Sets the extra parameters of the autocompleter to obj (which should be
a JavaScript object, see above)
It's often wise to flush the cache after calling setExtraParameters.
_______________________________________________
jQuery mailing list
discuss@jquery.com
http://jquery.com/discuss/
