forked from dyve/jquery-autocomplete
/
jquery.autocomplete.txt
210 lines (146 loc) · 8.55 KB
/
jquery.autocomplete.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
Autocomplete - a jQuery plugin :
================================
Usage :
=======
$("selector").autocomplete(url [, options]);
Restriction :
=============
Selector should select one input element. Anything else will cause Autocomplete to exit with an error message.
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:
inputClass (default value: "acInput")
This class will be added to the input box.
loadingClass = (default value: "acLoading")
The class for the input box while results are being fetched from the server.
resultsClass (default value: "acResults")
The class for the UL that will contain the result items (result items are LI elements).
selectClass = (default value: "acSelect")
The class for the input box while results are being fetched from the server.
queryParamName = (default value: "q")
The url parameter used to request the autocomplete list. The value used is what the user entered.
limitParamName = (default value: "limit")
The url parameter used to limit the number of entries returned from the server.
The value of maxItemsToShow is used as the limit.
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").
remoteDataType (default value: false)
If this is set to 'json', the autocompleter expects a JSON array from the server. Any other
settings, it defaults to the native text format using lineSeparator and Cellseparator (see below).
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: 2)
The minimum number of characters a user has to type before the autocompleter activates.
maxItemsToShow (default value: 10)
Set the maximum number of items to show. Also used as the limit value used by limitParamName.
If set to 0, all items will be shown.
delay (default value: 400)
The delay in milliseconds the autocompleter waits after a keystroke to activate itself.
useCache (default value: true)
Set to true if caching is wanted.
maxCacheLength (default value: 10)
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: true)
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: false)
Whether or not the comparison is case sensitive. Only important if you use caching.
matchInside (default value: true)
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: false)
If set to 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.
selectFirst (default value: false)
If this is set to true, the first autocomplete value will be automatically selected, and highlighted.
selectOnly (default value: false)
If this is set to true, and there is only one autocomplete when the user hits tab/return,
it will be selected even if it has not been handpicked by keyboard or mouse action.
This overrides selectFirst.
showResult (default value: null)
A JavaScript function that can provide advanced markup for an item. For each row of results,
this function will be called. The returned value will be displayed inside an LI element in the
results list. Autocompleter will provide the value and the data.
onItemSelect (default value: null)
A JavaScript function 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.
autoFill (default value: false)
If this is set to true, the autocompleter will automatically fill the search box with the
first entry in the results.
filterResults (default value: true)
If this is set to true, the autocompleter will filter the results presented by the server,
selecting only those that begin with the user input.
If this is set to false, the autocompleter will consider every result from the server a
valid response.
sortResults (default value: true)
If this is set to true, the autocompleter will sort the results presented in alphanumeric
order, see sortFunction for custom sort.
sortFunction (default value: null)
Use this sort function to sort results if set instead of the built-in alphanumeric sort
function. Sorting will only happen if sortResults is set to true.
onNoMatch (default value: null)
A JavaScript function that will be called if there are no matches.
onFinish (default value: null)
A JavaScript function that will be called when finishing the autocompleter (only called if active).
preventDefaultReturn (default value: true)
Whether or not to prevent the default behavior of the Return key when this is used to select an item.
Return will usually submit the form.
preventDefaultTab (default value: false)
Whether or not to prevent the default behavior of the Tab key when this is used to select an item.
Tab will usually jump to the next input field of the form.
matchStringConverter (default value: null)
A javascript function which is used to convert the input value and the results before comparing them.
Can be used to implement accent folding. Only used when filterResults is set to true.
beforeUseConverter (default value: null)
A JavaScript function which is used to convert the input value before sending it to the backend.
autoWidth (default value: "min-width")
The CSS property to set the width of the results list to. Leave empty to stop jquery-autocomplete
from interfering with your results width. Other sensible values are "min-width" (default) and "width".
useDelimiter (default value: false)
Whether or not to delimit separate autocomplete strings within the same input field with a
comma. For example, you may want to allow the user to enter a comma separated list of values--and
each value will autocomplete without erasing the other delimited values in the input field.
getData (default value: null)
Function which return data to be processed. If several sources are present, then data is fetched
in following order: "data" option, "getData" option call, ajax query to remote url.
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({ url: "my_autocomplete_backend.php" }); // Set the autocompleter
var ac = $("#input_box").data('autocompleter'); // A handle to our autocompleter
There are currently 2 functions that can be called to influence the behaviour at run-time:
flushCache()
This flushes the cache.
setExtraParams(obj)
This 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.