Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/suevalov/jquery.richautocomplete
Autocomplete plugin with some advanced features
https://github.com/suevalov/jquery.richautocomplete
autocomplete-plugin javascript jquery
Last synced: 8 days ago
JSON representation
Autocomplete plugin with some advanced features
- Host: GitHub
- URL: https://github.com/suevalov/jquery.richautocomplete
- Owner: suevalov
- Created: 2013-09-05T08:06:54.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2013-09-25T09:14:02.000Z (about 11 years ago)
- Last Synced: 2023-08-03T12:43:06.976Z (over 1 year ago)
- Topics: autocomplete-plugin, javascript, jquery
- Language: JavaScript
- Size: 285 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
jquery.richAutocomplete
=======================
Autocomplete plugin with some advanced features:
* Different data providers: asychronous data provider, local data provider. Possibility to create your own data providers, for example, local storage data provider.
* Placeholder for input, which works in all browsers.
* Possibility to setup template for result item.
* Possibility to group results to differents chunks.
* Possibility to setup different templates for different chunks.
* Possibility to multiple choice.
### Dependecies ###
* jQuery
* Underscore
### Basic initialization
```js
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteAjaxProvider("some/sample/url")
});
```
### Settings
There are some properties that you can setup:
| Property | Description |
| ------------- |-------------|
| provider | Data provider *[required]* |
| minLength | Minimal characters count to start searching *[default_value = 1]* |
| placeholder | Placeholder for input, you should pay attention, that 'placeholder' attribute in input overriders 'placeholder' setting |
| maxViewedCount | Maximum items count, which will be visible in popup container *[default_value = false]* |
| containerWidth | By default popup container width equals input width, but you can override it by setting up this parameter with concrete pixels *[default_value = false]* |
| initialValue | Initial object value which will be set to input on plugin initialization. *[default_value = false ]* |
| highlightResults | Searching and highlighting entered value in item template ( within "-label" class) *[default_value = true]* |
| defaultTerm | Value in incoming result object which will be main. *[default_value = "label"]* |
| groups | Settings for grouped results (See explanation below) *[default_value = null ]* |
| cache | Cache incoming results. *[default_value = false]* |
| cacheLimit | Cache size limit. *[default_value = 20]* |
| mode | Determines single or multiple mode. *[default_value = "single"] : "single", "multi"* |
| additionalMode | Determines additional container type. *[default_value = "empty"] : "empty", "create", "nothing"* |
| maxSelectedOptions | Determines max selected options for multiple choice. *[default_value = false] : false, 1 - n* |
| removeButton | Options in multiple choice have remove buttons. *[default_value = false : false, true]*|
| render | Settings for rendering items (see below) |
### Data providers
There are 2 implemented data providers for plugin:
* static data provider;
* asychronous data provider;
You can implement your own data provider (for example, local storage provider). Creating new data provider described below.
#### Static data provider
```js
var cities = [
{
id: 1,
label: "New York",
country: "USA"
},
...
{
id: 10,
label: "Moscow",
country: "Russia"
}
];
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteDataProvider(cities)
});
```
By default, *richAutocompleteDataProvider* filters items by comparing *data.label* value with entered value at lowercase.
If you want to compare another field, you can pass *field name* as a second parameter of provider function.
```js
provider: $.richAutocompleteDataProvider(cities, "country")
```
If you want to implement your own complex comparator, you can pass it as a third parameter of provider function.
```js
/**
* @param {Object} comparable object
* @param {String} entered value
* @param {Number} index of group which data come from (see later)
*/
var myComparator = function(data, value, groupIndex) {
// implement your own logic
// function should return true or false as a result
};
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteDataProvider(cities, null, myComparator)
});
```
#### Asychronous data provider
```js
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteAjaxProvider("/some/url")
});
```
By default you should pass only *url address* to data provider. In that case, it will generate AJAX call with the following parameters:
```js
$.ajax({
type: 'get',
url: "/some/url",
dataType: 'json',
data: {
term: value
}
})
```
You can change send data and request type by passing some extra paramenters to provider function.
```js
// additional data can be an object
var additionalSendData = {
param1: "param1",
param2: "param2"
}
// or a function which returns an object
var additionalSendData = function() {
return {
param1 : getMeParam1(),
param2 : getMeParam2()
};
}
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteAjaxProvider("/some/url", additionalSendData, "label", "post")
});
```
That configuration will generate the following AJAX request:
```js
$.ajax({
type: 'post',
url: "/some/url",
dataType: 'json',
data: {
label: value,
param1: "param1",
param2: "param2"
}
})
```
#### Creating your own provider
If you want to implement your own provider you should create function with following pattern:
```js
var myProviderFunction = function(param1, param2) {
var someDataStorage;
return function(value) {
// this function should return jQuery.promise object
var deferred = new $.Deferred();
var result = someDataStorage.findAllItemByValue(value);
return deferred.resolve(result);
}
}
```
### Defining item template
You can override default item template by setting up **defaultLabelTemplate** property.
```js
var cities = [
{
id: 1,
label: "New York",
country: "USA",
population: "8.3 millions"
},
...
{
id: 10,
label: "Moscow",
country: "Russia",
population: "11.5 millions"
}
];
// template can be a string
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteDataProvider(cities),
render: {
itemTemplate: "
<%= label %> - <%= country %>
"
}
});
// or template can be a function
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteDataProvider(cities),
render: {
itemTemplate: function(data) {
if (data.id % 2 === 0) {
return "
<%= label %> - <%= country %>
";
} else {
return "
<%= label %> - <%= population %>
"
}
}
}
});
```
### Grouped results
Additional plugin feature is possibility to accept and show grouped results. What does it mean? Lets look at the example!
```js
// Lets say that we have three arrays of cities: the first includes only capitals,
// the second - cities with population more than 1 million people, the third - cities with population less than 1 million people
var cities = [
[
{
label: "Washington, D.C.",
country: "USA"
},
{
label: "London",
country: "UK"
}
],
[
{
label: "New York",
country: "USA",
population: "8.3 millions"
},
{
label: "Birmingham",
country: "UK",
population: "1 million"
}
],
[
{
label: "Springfield",
country: "USA",
population: "150k",
region: "Massachusetts"
},
{
label: "Manchester",
country: "UK",
population: "500k",
region: "North West England"
}
]
];
// As you can see, each group has different data properties and we want to define unique template for each group
$("input[name=someInputName]").richAutocomplete({
provider: $.richAutocompleteDataProvider(cities),
groups: [
{
itemTemplate: function(data) {
return "
<%= label %><%= country %>";
},
headerTemplate: "Capitals
",
groupClass: "-citiesCapitalsClass"
},
{
itemTemplate: function(data) {
return "<%= label %><%= country %><%= population %>";
},
headerTemplate: "Megalopolis
",
groupClass: "-citiesMegalopolisesClass"
},
{
itemTemplate: function(data) {
return "<%= label %> , <%= region %><%= country %><%= population %>";
},
headerTemplate: "Other cities
",
groupClass: "-citiesOtherClass"
}
]
});
```