Skip to content

Commit 63aa789

Browse files
author
Tomas Kirda
authored
Merge pull request devbridge#648 from oshihirii/patch-1
Some readme file changes
2 parents 192bb31 + fa88402 commit 63aa789

File tree

1 file changed

+61
-55
lines changed

1 file changed

+61
-55
lines changed

‎readme.md

Lines changed: 61 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -7,65 +7,71 @@ Devbridge Group accelerates software to market for enterprise clients through de
77
Ajax Autocomplete for jQuery allows you to easily create
88
autocomplete/autosuggest boxes for text input fields.
99

10-
Has no dependencies other than jQuery.
10+
It has no dependencies other than jQuery.
1111

1212
The standard jquery.autocomplete.js file is around 13KB when minified.
1313

1414
## API
15-
16-
* `$(selector).autocomplete(options);`
17-
* Sets up autocomplete for input field(s).
18-
* `options`: An object literal which defines the settings to use for the autocomplete plugin. Available option settings listed below.
19-
20-
### Ajax Settings
21-
* `serviceUrl`: Server side URL or callback function that returns serviceUrl string. Optional if local lookup data is provided.
22-
* `type`: Ajax request type to get suggestions. Default: `GET`.
23-
* `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.
24-
* `paramName`: Default `query`. The name of the request parameter that contains the query.
25-
* `params`: Additional parameters to pass with the request, optional.
26-
* `deferRequestBy`: Number of miliseconds to defer Ajax request. Default: `0`.
27-
* `ajaxSettings`: Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request.
28-
29-
### Configuration Settings
30-
* `noCache`: Boolean value indicating whether to cache suggestion results. Default `false`.
31-
* `delimiter`: String or RegExp, that splits input value and takes last part to as query for suggestions.
32-
Useful when for example you need to fill list of comma separated values.
33-
* `onSearchStart`: `function (params) {}` called before Ajax request. `this` is bound to input element.
34-
* `onSearchComplete`: `function (query, suggestions) {}` called after Ajax response is processed. `this` is bound to input element. `suggestions` is an array containing the results.
35-
* `onSearchError`: `function (query, jqXHR, textStatus, errorThrown) {}` called if Ajax request fails. `this` is bound to input element.
36-
* `transformResult`: `function(response, originalQuery) {}` called after the result of the query is ready. Converts the result into response.suggestions format.
37-
* `onSelect`: `function (suggestion) {}` Callback function invoked when user selects suggestion
38-
from the list. `this` inside callback refers to input HtmlElement.
39-
* `minChars`: Minimum number of characters required to trigger autosuggest. Default: `1`.
40-
* `lookupLimit`: Number of maximum results to display for local lookup. Default: no limit.
41-
* `lookup`: Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals.
42-
* `suggestion`: An object literal with the following format: `{ value: 'string', data: any }`.
43-
* `lookupFilter`: `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive).
44-
* `triggerSelectOnValidInput`: Boolean value indicating if `select` should be triggered if it matches suggestion. Default `true`.
45-
* `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`.
46-
* `autoSelectFirst`: if set to `true`, first item will be selected when showing suggestions. Default value `false`.
47-
* `onHide`: `function (container) {}` called before container will be hidden
48-
49-
### Presentation Settings
50-
* `beforeRender`: `function (container, suggestions) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed.
51-
* `formatResult`: `function (suggestion, currentValue) {}` custom function to
52-
format suggestion entry inside suggestions container, optional.
53-
* `formatGroup`: `function (suggestion, category) {}` custom function to
54-
format group header, optional.
55-
* `groupBy`: property name of the suggestion `data` object, by which results should be grouped.
56-
* `maxHeight`: Maximum height of the suggestions container in pixels. Default: `300`.
57-
* `width`: Suggestions container width in pixels, e.g.: 300, `flex` for max suggestion size and `auto` takes input field width. Default: `auto`
58-
* `zIndex`: 'z-index' for suggestions container. Default: `9999`.
59-
* `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.
60-
* `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.
61-
Set this option to force auto positioning in other cases.
62-
* `orientation`: Default `bottom`. Vertical orientation of the displayed suggestions, available values are `auto`, `top`, `bottom`.
63-
If set to `auto`, the suggestions will be orientated it the way that place them closer to middle of the view port.
64-
* `preserveInput`: if `true`, input value stays the same when navigating over suggestions. Default: `false`.
65-
* `showNoSuggestionNotice`: Default `false`. When no matching results, display a notification label.
66-
* `noSuggestionNotice`: Default `No results`. Text or htmlString or Element or jQuery object for no matching results label.
67-
* `onInvalidateSelection`: `function () {}` called when input is altered after selection has been made. `this` is bound to input element.
68-
* `tabDisabled`: Default `false`. Set to true to leave the cursor in the input field after the user tabs to select a suggestion.
15+
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.
16+
```js
17+
$(selector).autocomplete(options);
18+
```
19+
### General settings (local and Ajax)
20+
| Setting | Default | Description |
21+
| :--- | :--- | :--- |
22+
| `noCache` | `false` | Boolean value indicating whether to cache suggestion results |
23+
| `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. |
24+
| `minChars` | `1` | Minimum number of characters required to trigger autosuggest |
25+
| `triggerSelectOnValidInput` | `true` | Boolean value indicating if `select` should be triggered if it matches suggestion |
26+
| `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` |
27+
| `autoSelectFirst` | `false` | If set to `true`, first item will be selected when showing suggestions |
28+
| `beforeRender` | optional | `function (container, suggestions) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed |
29+
| `formatResult` | optional | `function (suggestion, currentValue) {}` custom function to format suggestion entry inside suggestions container |
30+
| `formatGroup` | optional | `function (suggestion, category) {}` custom function to format group header |
31+
| `groupBy` | optional | property name of the suggestion `data` object, by which results should be grouped |
32+
| `maxHeight` | `300` | Maximum height of the suggestions container in pixels |
33+
| `width` | `auto` | Suggestions container width in pixels, e.g.: 300, `flex` for max suggestion size and `auto` takes input field width |
34+
| `zIndex` | `9999` | 'z-index' for suggestions container |
35+
| `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 |
36+
| `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 |
37+
| `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 |
38+
| `preserveInput` | `false` | If `true`, input value stays the same when navigating over suggestions |
39+
| `showNoSuggestionNotice` | `false` | When no matching results, display a notification label |
40+
| `noSuggestionNotice` | `No results` | Text or htmlString or Element or jQuery object for no matching results label |
41+
| `onInvalidateSelection` | optional | `function () {}` called when input is altered after selection has been made. `this` is bound to input element |
42+
| `tabDisabled` | `false` | Set to true to leave the cursor in the input field after the user tabs to select a suggestion |
43+
44+
45+
### Event function settings (local and Ajax)
46+
| Event setting | Function description |
47+
| :--- | :--- |
48+
| `onSearchStart` | `function (params) {}` called before Ajax request. `this` is bound to input element |
49+
| `onHint` | `function (container) {}` used to change input value to first suggestion automatically |
50+
| `onSearchComplete` | `function (query, suggestions) {}` called after Ajax response is processed. `this` is bound to input element. `suggestions` is an array containing the results |
51+
| `transformResult` | `function(response, originalQuery) {}` called after the result of the query is ready. Converts the result into response.suggestions format |
52+
| `onSelect` | `function (suggestion) {}` Callback function invoked when user selects suggestion from the list. `this` inside callback refers to input HtmlElement.|
53+
| `onSearchError` | `function (query, jqXHR, textStatus, errorThrown) {}` called if Ajax request fails. `this` is bound to input element |
54+
| `onHide` | `function (container) {}` called before container will be hidden |
55+
56+
57+
### Local only settings
58+
| Setting | Default | Description |
59+
| :--- | :--- | :--- |
60+
| `lookupLimit` | `no limit` | Number of maximum results to display for local lookup |
61+
| `lookup` | n/a | Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals |
62+
| `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 }` |
63+
| `lookupFilter` | n/a | `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive) |
64+
65+
### Ajax only settings
66+
| Setting | Default | Description |
67+
| :--- | :--- | :--- |
68+
| `serviceUrl` | n/a | Server side URL or callback function that returns serviceUrl string |
69+
| `type` | `GET` | Ajax request type to get suggestions |
70+
| `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 |
71+
| `paramName` | `query` | The name of the request parameter that contains the query |
72+
| `params` | optional | Additional parameters to pass with the request |
73+
| `deferRequestBy` | `0` | Number of miliseconds to defer Ajax request |
74+
| `ajaxSettings` | optional | Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request |
6975

7076
## Default Options
7177

0 commit comments

Comments
 (0)