jquery.autocomplete
v1.2.0
Published
jquery.autocomplete ===================
Downloads
18,398
Readme
jquery.autocomplete
Autocomplete on any element*. Data source can be an ajax query response or from provided data.
Status
Test
npm i -g phantomjs
npm test
This kicks off selenium server and tests the library using phantomjs. To use firefox for testing simply set an environment variable of BROWSER with value firefox:
BROWSER=firefox npm test
How to use
Here is an autocomplete sample for the text field with id 'autocomplete':
<input type="text" name="q" id="autocomplete" />
You can have multiple instances on a single page.
var options = { serviceUrl: 'service/autocomplete.ashx' }
var a = $('#autocomplete').autocomplete(options)
You can add extra options:
var a = $('#query').autocomplete({
serviceUrl: 'service/autocomplete.ashx',
minChars: 2,
delimiter: /(,|;)\s*/, // regex or character - pass null for single word autocomplete
appendChars: ' ',
maxHeight: 400,
width: 300,
zIndex: 9999,
deferRequestBy: 0, // miliseconds
params: { country: 'Yes' }, // additional parameters
noCache: false, // default is false
onSelect: function(value, data) { alert('You selected: ' + value + ', ' + data) },
lookup: ['January', 'February', 'March', 'April', 'May'], // local lookup values
maxSuggestions: null, // Maximum suggestions to display (applies to local results only)
searchEverywhere: false, // Search any part of data not just from beginning
// only applicable to local data lookups
prefix: '', // Only start autocompleting after this character e.g. '@' or '+'
dataKey: 'data' // Provide values as objects and use this key as the inserted data.
// Allows users to specify a template for autocomplete suggestions
searchKey: 'search', // Search on this data field
disableMouseOver: false, // If true don't update selected option on mouseover
identifier: 'some-unique-identifier' // added to attribute data-identifier of the autocomplete div
})
Use lookup option only if you prefer to inject an array of autocompletion options, rather than sending Ajax queries.
If your lookup
values are objects then you must provide values for dataKey
and searchKey
.
Note: Autocomplete uses both data in dataKey
and searchKey
to find suggestions.
Ajax Responses
Responses from ajax requests much be in the following format:
{
query: 'Ba',
suggestions: ['Bahamas', 'Bahrain', 'Bangladesh', 'Barbados'],
data: ['BHS', 'BHR', 'BGD', 'BRB']
}
Notes:
- query - original query value
- suggestions - comma separated array of suggested values
- data (optional) - data array, that contains values for callback function when data is selected.
Setting options
Autocomplete functionality can be disabled or enabled programmatically.
var ac = $('#query').autocomplete(options)
ac.disable()
ac.enable()
Options can be changed programmatically at any time, only options that are passed get set:
ac.setOptions({ zIndex: 1001 });
If you need to pass additional parameters, you can set them via setOptions too:
ac.setOptions({ params: { first: 'John', last: 'Doe' } })
Formatting results
formatResult: function that formats values that are displayed in the autosuggest list. It takes three parameters: data we are attempting to autocomplete on, matching data entry, the third being the context of the Autocomplete object in case you want to use the matching regex. Default function for this:
formatResult: function(value, data) {
var search = (this.searchKey) ? data[this.searchKey] : ''
if (this.dataKey) data = data[this.dataKey]
var pattern = '(' + value.replace(this.regEx, '\\$1') + ')'
return ((search + ' (' + data).replace(new RegExp(pattern, 'gi'), '<strong>$1<\/strong>') + ')')
},
e.g. January (1st month)
Cleaning up
In order to remove the element once you are done simply do:
ac.remove()
Insert special data into the DOM
Rather that simply insert the autcompleted data it is also possible to pass in a function to handle data insertion.
This is achieved by passing a function as the insertDomContent
key. Default function for this:
function(data, suggestion, context) {
var val = context.getValue(suggestion)
if ('object' === typeof(data))
val = context.getValue(data[context.options.dataKey])
if (context.options.appendChars) val = val + context.options.appendChars
return val
},
Note: Remember to call context.getValue()
to get current input element contents.
When doing local lookups the options object should use the following format:
{
lookup: [
{ search: 'January', data: '1st month' },
{ search: 'Feburary', data: '2nd month' },
{ search: 'March', data: '3rd month' },
{ search: 'April', data: '4th month' },
{ search: 'May', data: '5th month' }
],
dataKey: 'data',
searchKey: 'search'
}
For 'January' for example on autocomplete selection '1st month' will be substituted into the autocomplete target.
Styling
Script generates the following HTML (sample query 'Ba'). Active element is marked with class "selected". You can style it any way you wish.
<div class="autocomplete-w1">
<div style="width:299px;" id="Autocomplete_1240430421731" class="autocomplete">
<div><strong>Ba</strong>hamas</div>
<div><strong>Ba</strong>hrain</div>
<div><strong>Ba</strong>ngladesh</div>
<div class="selected"><strong>Ba</strong>rbados</div>
</div>
</div>
CSS:
.autocomplete-w1 { position: absolute; top: 0px; left: 0px; margin: 6px 0 0 6px; }
.autocomplete { border: 1px solid #999; background: #FFF; cursor: default; text-align: left; max-height: 350px; overflow: auto; margin: -6px 6px 6px -6px; }
.autocomplete .selected { background: #F0F0F0; }
.autocomplete div { padding: 2px 5px; white-space: nowrap; overflow: hidden; }
.autocomplete strong { font-weight: normal; color: #3399FF; }
Licence
MIT.
Source
This autocomplete has been updated and adapted from http://www.devbridge.com/projects/autocomplete/jquery/.
- Keyboard not currently working for non-form input types