From aca25b9047f95b23ddb2ef631584805dbc091f2c Mon Sep 17 00:00:00 2001 From: oshihirii Date: Sat, 9 Sep 2017 13:39:50 +1000 Subject: [PATCH 1/2] Re-categorised settings information in readme Re-categorised settings information in readme for easier reference. Added settings information to tables for increased readability. Added entry for the `onHint` setting which is currently undocumented. --- readme.md | 101 +++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 47 deletions(-) diff --git a/readme.md b/readme.md index 905cce8..49f9f87 100644 --- a/readme.md +++ b/readme.md @@ -17,55 +17,62 @@ The standard jquery.autocomplete.js file is around 13KB when minified. * 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 -* `serviceUrl`: Server side URL or callback function that returns serviceUrl string. Optional if local lookup data is provided. -* `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. -* `paramName`: Default `query`. The name of the request parameter that contains the query. -* `params`: Additional parameters to pass with the request, optional. -* `deferRequestBy`: Number of miliseconds to defer Ajax request. Default: `0`. -* `ajaxSettings`: Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request. +### General settings (for local and Ajax searches) +| 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 | -### 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 -* `beforeRender`: `function (container, suggestions) {}` 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. -* `formatGroup`: `function (suggestion, category) {}` custom function to - format group header, 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, `flex` for max suggestion size and `auto` takes input field width. Default: `auto` -* `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. -* `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. -* `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. -* `preserveInput`: if `true`, input value stays the same when navigating over suggestions. Default: `false`. -* `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. +### Event function settings (for local and Ajax searches) +| Event setting | Function description | +| :--- | :--- | +| `onSearchStart` | `function (params) {}` called before Ajax request. `this` is bound to input element | +| `onHint` | `function (container) {}` used to change input value to first suggestion automatically | +| `onSearchComplete` | `function (query, suggestions) {}` called after Ajax response is processed. `this` is bound to input element. `suggestions` is an array containing the results | +| `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.| +| `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 | + + +### Local only settings +| Setting | Default | Description | +| :--- | :--- | :--- | +| `lookupLimit` | `no limit` | Number of maximum results to display for local lookup | +| `lookup` | n/a | Callback function or lookup array for the suggestions. It may be array of strings or `suggestion` object literals | +| `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 }` | +| `lookupFilter` | n/a | `function (suggestion, query, queryLowerCase) {}` filter function for local lookups. By default it does partial string match (case insensitive) | + +### Ajax only settings +| Setting | Default | Description | +| :--- | :--- | :--- | +| `serviceUrl` | n/a | Server side URL or callback function that returns serviceUrl string | +| `type` | `GET` | Ajax request type to get suggestions | +| `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 | +| `paramName` | `query` | The name of the request parameter that contains the query | +| `params` | optional | Additional parameters to pass with the request | +| `deferRequestBy` | `0` | Number of miliseconds to defer Ajax request | +| `ajaxSettings` | optional | Any additional [Ajax Settings](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) that configure the jQuery Ajax request | ## Default Options From fa88402642e15488fb55126bfde5f40090f47665 Mon Sep 17 00:00:00 2001 From: oshihirii Date: Sat, 9 Sep 2017 13:53:01 +1000 Subject: [PATCH 2/2] Updated readme Readability changes --- readme.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/readme.md b/readme.md index 49f9f87..29dcd8d 100644 --- a/readme.md +++ b/readme.md @@ -7,17 +7,16 @@ Devbridge Group accelerates software to market for enterprise clients through de Ajax Autocomplete for jQuery allows you to easily create 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. ## API - -* `$(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. - -### General settings (for local and Ajax searches) +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 | @@ -43,7 +42,7 @@ The standard jquery.autocomplete.js file is around 13KB when minified. | `tabDisabled` | `false` | Set to true to leave the cursor in the input field after the user tabs to select a suggestion | -### Event function settings (for local and Ajax searches) +### Event function settings (local and Ajax) | Event setting | Function description | | :--- | :--- | | `onSearchStart` | `function (params) {}` called before Ajax request. `this` is bound to input element |