agerix/jQuery-Autocomplete
2
0
Fork 0
mirror of https://github.com/devbridge/jQuery-Autocomplete.git synced 2024-12-23 11:28:53 +00:00
Code Issues Releases Activity

Update readme.md

Browse Source 
Split descriptions of options into 3 blocks and sort as possible by logic of process.
This commit is contained in:
Roman 2015-05-29 16:20:05 +09:00
parent 7f81f72a43
commit 4c802be297
1 changed files with 29 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
readme.md
View File

@ -12,48 +12,51 @@ The standard jquery.autocomplete.js file is around 2.7KB when minified via Closu
* `$(selector).autocomplete(options);` * `$(selector).autocomplete(options);`
* Sets up autocomplete for input field(s). * Sets up autocomplete for input field(s).
* `options`: An object literal which defines the settings to use for the autocomplete plugin. * `options`: An object literal which defines the settings to use for the autocomplete plugin.
* __Ajax settings__
* `serviceUrl`: Server side URL or callback function that returns serviceUrl string. Optional if local lookup data is provided. * `serviceUrl`: Server side URL or callback function that returns serviceUrl string. Optional if local lookup data is provided.
* `ajaxSettings`: Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request. * `type`: Ajax request type to get suggestions. Default: `GET`.
* `lookup`: Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals. * `dataType`: type of data returned from server. Either 'text' (default) or 'jsonp', which will cause the autocomplete to use jsonp. You may return a json object in your callback when using jsonp.
* `suggestion`: An object literal with the following format: `{ value: 'string', data: any }`. * `paramName`: Default `query`. The name of the request parameter that contains the query.
* `lookupFilter`: `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive).
* `lookupLimit`: Number of maximum results to display for local lookup. Default: no limit.
* `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`.
* `maxHeight`: Maximum height of the suggestions container in pixels. Default: `300`.
* `deferRequestBy`: Number of miliseconds to defer ajax request. Default: `0`.
* `width`: Suggestions container width in pixels, e.g.: 300. Default: `auto`, takes input field width.
* `params`: Additional parameters to pass with the request, optional. * `params`: Additional parameters to pass with the request, optional.
* `formatResult`: `function (suggestion, currentValue) {}` custom function to * `deferRequestBy`: Number of miliseconds to defer ajax request. Default: `0`.
format suggestion entry inside suggestions container, optional. * `ajaxSettings`: Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request.
* __Searching process__
* `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. * `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 coma separated values. Useful when for example you need to fill list of coma separated values.
* `zIndex`: 'z-index' for suggestions container. Default: `9999`.
* `type`: Ajax request type to get suggestions. Default: `GET`.
* `noCache`: Boolean value indicating whether to cache suggestion results. Default `false`.
* `onSearchStart`: `function (query) {}` called before ajax request. `this` is bound to input element. * `onSearchStart`: `function (query) {}` 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. * `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. * `onSearchError`: `function (query, jqXHR, textStatus, errorThrown) {}` called if ajax request fails. `this` is bound to input element.
* `onInvalidateSelection`: `function () {}` called when input is altered after selection has been made. `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`. * `triggerSelectOnValidInput`: Boolean value indicating if `select` should be triggered if it matches suggestion. Default `true`.
* `preventBadQueries`: Boolean value indicating if it shoud 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`. * `preventBadQueries`: Boolean value indicating if it shoud 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`.
* `beforeRender`: `function (container) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed.
* `tabDisabled`: Default `false`. Set to true to leave the cursor in the input field after the user tabs to select a suggestion.
* `paramName`: Default `query`. The name of the request parameter that contains the query.
* `transformResult`: `function(response, originalQuery) {}` called after the result of the query is ready. Converts the result into response.suggestions format.
* `autoSelectFirst`: if set to `true`, first item will be selected when showing suggestions. Default value `false`. * `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
* __Displaying__
* `beforeRender`: `function (container) {}` called before displaying the suggestions. You may manipulate suggestions DOM before it is displayed.
* `formatResult`: `function (suggestion, currentValue) {}` custom function to
format suggestion entry inside suggestions container, optional.
* `groupBy`: property name of the suggestion `data` object, by which results should be grouped.
* `maxHeight`: Maximum height of the suggestions container in pixels. Default: `300`.
* `width`: Suggestions container width in pixels, e.g.: 300. Default: `auto`, takes input field width.
* `zIndex`: 'z-index' for suggestions container. Default: `9999`.
* `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. * `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.
* `dataType`: type of data returned from server. Either 'text' (default) or 'jsonp', which will cause the autocomplete to use jsonp. You may return a json object in your callback when using jsonp.
* `showNoSuggestionNotice`: Default `false`. When no matching results, display a notification label.
* `noSuggestionNotice`: Default `No results`. Text or htmlString or Element or jQuery object for no matching results label.
* `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. * `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.
Set this option to force auto positioning in other cases. Set this option to force auto positioning in other cases.
* `orientation`: Default `bottom`. Vertical orientation of the displayed suggestions, available values are `auto`, `top`, `bottom`. * `orientation`: Default `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. If set to `auto`, the suggestions will be orientated it the way that place them closer to middle of the view port.
* `groupBy`: property name of the suggestion `data` object, by which results should be grouped.
* `preserveInput`: if `true`, input value stays the same when navigating over suggestions. Default: `false`. * `preserveInput`: if `true`, input value stays the same when navigating over suggestions. Default: `false`.
* `onHide`: `function (container) {}` called before container will be hidden * `showNoSuggestionNotice`: Default `false`. When no matching results, display a notification label.
* `noSuggestionNotice`: Default `No results`. Text or htmlString or Element or jQuery object for no matching results label.
* `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.
Autocomplete instance has following methods: Autocomplete instance has following methods: