agerix/jQuery-Autocomplete
2
0
Fork 0
mirror of https://github.com/devbridge/jQuery-Autocomplete.git synced 2024-11-29 08:14:06 +00:00
Code Issues Releases Activity

Merge pull request #648 from oshihirii/patch-1

Browse Source 
Some readme file changes
This commit is contained in:
Tomas Kirda 2017-09-09 09:01:40 -05:00 committed by GitHub
commit 63aa789722
1 changed files with 57 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
readme.md
View File

@ -7,65 +7,71 @@ Devbridge Group accelerates software to market for enterprise clients through de
Ajax Autocomplete for jQuery allows you to easily create Ajax Autocomplete for jQuery allows you to easily create
autocomplete/autosuggest boxes for text input fields. autocomplete/autosuggest boxes for text input fields.
Has no dependencies other than jQuery. It has no dependencies other than jQuery.
The standard jquery.autocomplete.js file is around 13KB when minified. The standard jquery.autocomplete.js file is around 13KB when minified.
## API ## API
The following sets up autocomplete for input fields where `options` is an object literal that defines the settings to use for the autocomplete plugin. All available option settings are shown in the tables below.
```js
$(selector).autocomplete(options);
```
### General settings (local and Ajax)
| Setting | Default | Description |
| :--- | :--- | :--- |
| `noCache` | `false` | Boolean value indicating whether to cache suggestion results |
| `delimiter` | optional | String or RegExp, that splits input value and takes last part to as query for suggestions. Useful when for example you need to fill list of comma separated values. |
| `minChars` | `1` | Minimum number of characters required to trigger autosuggest |
| `triggerSelectOnValidInput` | `true` | Boolean value indicating if `select` should be triggered if it matches suggestion |
| `preventBadQueries` | `true` | Boolean value indicating if it should prevent future Ajax requests for queries with the same root if no results were returned. E.g. if `Jam` returns no suggestions, it will not fire for any future query that starts with `Jam` |
| `autoSelectFirst` | `false` | If set to `true`, first item will be selected when showing suggestions |
| `beforeRender` | optional | `function (container, suggestions) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed |
| `formatResult` | optional | `function (suggestion, currentValue) {}` custom function to format suggestion entry inside suggestions container |
| `formatGroup` | optional | `function (suggestion, category) {}` custom function to format group header |
| `groupBy` | optional | property name of the suggestion `data` object, by which results should be grouped |
| `maxHeight` | `300` | Maximum height of the suggestions container in pixels |
| `width` | `auto` | Suggestions container width in pixels, e.g.: 300, `flex` for max suggestion size and `auto` takes input field width |
| `zIndex` | `9999` | 'z-index' for suggestions container |
| `appendTo` | optional | Container where suggestions will be appended. Default value `document.body`. Can be jQuery object, selector or HTML element. Make sure to set `position: absolute` or `position: relative` for that element |
| `forceFixPosition` | `false` | Suggestions are automatically positioned when their container is appended to body (look at `appendTo` option), in other cases suggestions are rendered but no positioning is applied. Set this option to force auto positioning in other cases |
| `orientation` | `bottom` | Vertical orientation of the displayed suggestions, available values are `auto`, `top`, `bottom`. If set to `auto`, the suggestions will be orientated it the way that place them closer to middle of the view port |
| `preserveInput` | `false` | If `true`, input value stays the same when navigating over suggestions |
| `showNoSuggestionNotice` | `false` | When no matching results, display a notification label |
| `noSuggestionNotice` | `No results` | Text or htmlString or Element or jQuery object for no matching results label |
| `onInvalidateSelection` | optional | `function () {}` called when input is altered after selection has been made. `this` is bound to input element |
| `tabDisabled` | `false` | Set to true to leave the cursor in the input field after the user tabs to select a suggestion |
* `$(selector).autocomplete(options);`
* Sets up autocomplete for input field(s).
* `options`: An object literal which defines the settings to use for the autocomplete plugin. Available option settings listed below.
### Ajax Settings ### Event function settings (local and Ajax)
* `serviceUrl`: Server side URL or callback function that returns serviceUrl string. Optional if local lookup data is provided. | Event setting | Function description |
* `type`: Ajax request type to get suggestions. Default: `GET`. | :--- | :--- |
* `dataType`: type of data returned from server. Either `text` (default), `json` or `jsonp`, which will cause the autocomplete to use jsonp. You may return a json object in your callback when using jsonp. | `onSearchStart` | `function (params) {}` called before Ajax request. `this` is bound to input element |
* `paramName`: Default `query`. The name of the request parameter that contains the query. | `onHint` | `function (container) {}` used to change input value to first suggestion automatically |
* `params`: Additional parameters to pass with the request, optional. | `onSearchComplete` | `function (query, suggestions) {}` called after Ajax response is processed. `this` is bound to input element. `suggestions` is an array containing the results |
* `deferRequestBy`: Number of miliseconds to defer Ajax request. Default: `0`. | `transformResult` | `function(response, originalQuery) {}` called after the result of the query is ready. Converts the result into response.suggestions format |
* `ajaxSettings`: Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request. | `onSelect` | `function (suggestion) {}` Callback function invoked when user selects suggestion from the list. `this` inside callback refers to input HtmlElement.|
| `onSearchError` | `function (query, jqXHR, textStatus, errorThrown) {}` called if Ajax request fails. `this` is bound to input element |
| `onHide` | `function (container) {}` called before container will be hidden |
### Configuration Settings
* `noCache`: Boolean value indicating whether to cache suggestion results. Default `false`.
* `delimiter`: String or RegExp, that splits input value and takes last part to as query for suggestions.
Useful when for example you need to fill list of comma separated values.
* `onSearchStart`: `function (params) {}` called before Ajax request. `this` is bound to input element.
* `onSearchComplete`: `function (query, suggestions) {}` called after Ajax response is processed. `this` is bound to input element. `suggestions` is an array containing the results.
* `onSearchError`: `function (query, jqXHR, textStatus, errorThrown) {}` called if Ajax request fails. `this` is bound to input element.
* `transformResult`: `function(response, originalQuery) {}` called after the result of the query is ready. Converts the result into response.suggestions format.
* `onSelect`: `function (suggestion) {}` Callback function invoked when user selects suggestion
from the list. `this` inside callback refers to input HtmlElement.
* `minChars`: Minimum number of characters required to trigger autosuggest. Default: `1`.
* `lookupLimit`: Number of maximum results to display for local lookup. Default: no limit.
* `lookup`: Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals.
* `suggestion`: An object literal with the following format: `{ value: 'string', data: any }`.
* `lookupFilter`: `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive).
* `triggerSelectOnValidInput`: Boolean value indicating if `select` should be triggered if it matches suggestion. Default `true`.
* `preventBadQueries`: Boolean value indicating if it should prevent future Ajax requests for queries with the same root if no results were returned. E.g. if `Jam` returns no suggestions, it will not fire for any future query that starts with `Jam`. Default `true`.
* `autoSelectFirst`: if set to `true`, first item will be selected when showing suggestions. Default value `false`.
* `onHide`: `function (container) {}` called before container will be hidden
### Presentation Settings ### Local only settings
* `beforeRender`: `function (container, suggestions) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed. | Setting | Default | Description |
* `formatResult`: `function (suggestion, currentValue) {}` custom function to | :--- | :--- | :--- |
format suggestion entry inside suggestions container, optional. | `lookupLimit` | `no limit` | Number of maximum results to display for local lookup |
* `formatGroup`: `function (suggestion, category) {}` custom function to | `lookup` | n/a | Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals |
format group header, optional. | `suggestion` | n/a | Not a settings, but in the context of above row, a suggestion is an object literal with the following format: `{ value: 'string', data: any }` |
* `groupBy`: property name of the suggestion `data` object, by which results should be grouped. | `lookupFilter` | n/a | `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive) |
* `maxHeight`: Maximum height of the suggestions container in pixels. Default: `300`.
* `width`: Suggestions container width in pixels, e.g.: 300, `flex` for max suggestion size and `auto` takes input field width. Default: `auto` ### Ajax only settings
* `zIndex`: 'z-index' for suggestions container. Default: `9999`. | Setting | Default | Description |
* `appendTo`: container where suggestions will be appended. Default value `document.body`. Can be jQuery object, selector or HTML element. Make sure to set `position: absolute` or `position: relative` for that element. | :--- | :--- | :--- |
* `forceFixPosition`: Default: `false`. Suggestions are automatically positioned when their container is appended to body (look at `appendTo` option), in other cases suggestions are rendered but no positioning is applied. | `serviceUrl` | n/a | Server side URL or callback function that returns serviceUrl string |
Set this option to force auto positioning in other cases. | `type` | `GET` | Ajax request type to get suggestions |
* `orientation`: Default `bottom`. Vertical orientation of the displayed suggestions, available values are `auto`, `top`, `bottom`. | `dataType` | `text` | type of data returned from server. Either `text`, `json` or `jsonp`, which will cause the autocomplete to use jsonp. You may return a json object in your callback when using jsonp |
If set to `auto`, the suggestions will be orientated it the way that place them closer to middle of the view port. | `paramName` | `query` | The name of the request parameter that contains the query |
* `preserveInput`: if `true`, input value stays the same when navigating over suggestions. Default: `false`. | `params` | optional | Additional parameters to pass with the request |
* `showNoSuggestionNotice`: Default `false`. When no matching results, display a notification label. | `deferRequestBy` | `0` | Number of miliseconds to defer Ajax request |
* `noSuggestionNotice`: Default `No results`. Text or htmlString or Element or jQuery object for no matching results label. | `ajaxSettings` | optional | Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request |
* `onInvalidateSelection`: `function () {}` called when input is altered after selection has been made. `this` is bound to input element.
* `tabDisabled`: Default `false`. Set to true to leave the cursor in the input field after the user tabs to select a suggestion.
## Default Options ## Default Options