English
资源说明：Flexible Facebook-like auto-complete widget for jQuery
Default value for **template** option:
```html
```
Also note that default options can be overwritten by altering `$.Suggester.defaultOptions`.
Events
-
Events can be passed as options to the constructor, or can be added later using jQuery event methods `.on()`, `.off()`, `.bind()` `.one()`, `.unbind()` and `.trigger()`
For example:
```javascript
// Register events in initial options
$(input).suggester({
data: myData,
onBeforeOpen: doStuff
});
// Register events later (OOP style)
var instance = new $.Suggester(selector, {
data: myData
});
instance.on('BeforeOpen', doStuff);
// Register events later (jQuery style)
$(input).suggester({
data: myData
}).suggester('on', 'BeforeOpen', doStuff);
```
How is data passed to event callbacks?
* Each event callback receives one argument: `event`
* `event` is a jQuery event object
* `event` also contains useful information related to the event. See the [Events](#events) section below for more information.
* When an event has a default action that can be prevented, `event` will have property `cancelable` set to true and `event.isCancelable()` will return true
* To prevent a default action, call `event.preventDefault()`
* To cancel the firing of other attached callbacks, call `event.stopImmediatePropagation()`
* In some case, altering information on the `event` object will change the behavior of the default action
* The callback will be fired in the scope of the Suggester instance. In other words, using `this` in the callback will refer to the Suggester instance. See the [Instance Properties](#instance-properties) and [Instance Methods](#instance-methods) sections below for more information.
The following is a description of each event.
Instance Properties
-
Static Properties
-
Instance Methods
-
Instance methods may be called using an Object Oriented style or with the classic jQuery style:
```javascript
// Object Oriented Style
var suggester = new $.Suggester(input, options);
suggester.methodName(arg1, arg2, argN);
// jQuery Style
$(input).suggester(options);
$(input).suggester('methodName', arg1, arg2, argN);
// jQuery Style followed by Object Oriented Style
$(input).suggester(options);
var instance = $(input).suggester('getInstance');
instance.methodName(arg1, arg2, argN);
```
Static Methods
-
More examples
-
Use an array of strings for suggestions:
```javascript
$('.my-text-input').suggester({
data: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
prompt: 'Enter a day of the week'
});
```
Use ajax to get suggestions:
```javascript
$('.my-text-input').suggester({
dataUrl: 'http://example.com/myjson?query=%s',
prompt: 'Enter a time zone'
});
```
Use the OOP pattern and use an array of objects for `data`:
```javascript
var suggester = new $.Suggester('.my-text-input', {
data: [{"label":"John Doe","value":"John Doe "}/*,...*/],
onAfterSave: function(event) {
saveToServer(event.newValue);
}
});
suggester.on('AfterClose', doStuff);
suggester.focus();
```
See the source on the [live demos](http://sandbox.kendsnyder.com/jQuery-Suggester/demos/) for lots more examples.
Changelog
-
**Version 1.4.0, Aug 2014**
* new event DefaultSuggestions
* cite some jsPerf results
* change 'bind' to 'on' in examples and internal usage
* change default keyDelay to 200ms
* fix docs for static properties and methods
**Version 1.3.1, Apr 2014**
* Fix to hidePlaceholder()
* Fix input hidden name
**Version 1.3.0, Mar 2014**
* Fixes to setValue(), clear(), focus(), blur()
* Use `git watch`
* Documentation improvements
* More unit tests
**Version 1.2.2, Jul 2013**
* Fixes to add()
* Documentation improvements
* More unit tests
**Version 1.2.1, Jul 2013**
* Added onChange event
* Documentation fixes
* Tweaks on build process
**Version 1.2.0, Jun 2013**
* Allow pasting delimited values
* Speed improvements
* Search through this.data to find typed values when applicable
**Version 1.1.1, May 2013**
* Fixed Suggester#getValues()
**Version 1.1.0, May 2013**
* Grunt build process
* Suggester.tags is now a collection of $.Suggester.Tag objects
**Version 1.0.2, April 2013**
* CSS classes for sugg-active and sugg-placeholder-on
* Fix BeforeAdd event to let value to be altered and AfterAdd event to include record
* Documentation fixes
**Version 1.0pre, December 2012**
* initial version
Contributing
-
After using git to clone the repo, you'll need nodejs, npm, and grunt-cli installed. See [gruntjs.com](http://gruntjs.com/getting-started) for more information. Then inside the cloned directory run `npm install` and then `grunt`
Make updates only to the files in the `./src` directory. Then run `grunt` to automatically generate documentation and other files. You may also make changes to the demos by editing `./demos/*` files or improve the build process by editing `./Gruntfile.js`. Then make a pull request.
Reporting Bugs
-
To report bugs, add an issue to the [GitHub issue tracker](https://github.com/kensnyder/jQuery-Suggester/issues).
License
-
Copyright 2012-2013, Ken Snyder
[MIT License](http://www.opensource.org/licenses/mit-license.php)
Inspired by the AutoSuggest plugin by Drew Wilson
Suggester - A Better Autocomplete Widget = Version 1.4.0, Aug 2014, MIT License [Download](https://github.com/kensnyder/jQuery-Suggester/blob/master/Suggester-1.4.0-Download.zip?raw=true), [Demos](http://sandbox.kendsnyder.com/jQuery-Suggester/demos/), [Unit tests](http://sandbox.kendsnyder.com/jQuery-Suggester/test/index.html) Usage: `var suggester = new $.Suggester($input, options);` Table of Contents -
- Introduction
- How to Use
- Options
- Events
- Instance Properties
- Static Properties
- Instance Methods
- Static Methods
- More Examples
- Changelog
- Contributing
- Reporting Bugs
- License
| Type | Option Name | Default | Description |
|---|---|---|---|
| {Array|Boolean} | data | false | Initial data to use for suggestions |
| {String} | valueProperty | "value" | The name of object property that should be used as the tag's value. Only applicable when options.data is set |
| {String} | labelProperty | "value" | The name of object property that should be used as the tag's display text. Only applicable when options.data is set |
| {Array} | searchProperties | Array("value") | The array of object property names that should be searched when generating suggestions. Only applicable when options.data is set |
| {String|Number} | matchAt | "anywhere" | Where to match when finding suggestions. It can be "anywhere", "start", "end" or an integer. Only applicable when options.data is set |
| {Boolean} | caseSensitive | false | If true, find matches regardless of case. Only applicable when options.data is set. Only applicable when options.data is set |
| {String} | dataUrl | false | Url to call to get json or jsonp results. Use %s to indicate where search text should be inserted. e.g. "http://example.com/myjson?query=%s" or "http://example.com/myjsonp?query=%s&callback=%s" |
| {String} | dataType | "json" | Can be "json" or "jsonp". If json, options.dataUrl needs to be in the format "http://example.com/myjsonp?query=%s&mycallback=%s". To handle xml, you'll need to register BeforeFetch and AfterFetch handlers or overwrite the fetchResults method |
| {String} | fly | "down" | Which way should the suggestion box fly. If "up", the suggestion box will appear before the input box in the DOM tree. A css class of "sugg-fly-up" or "sugg-fly-down" is applied to the widget element based on this value |
| {String} | suggListPosition | "relative" | If "absolute", the suggestion box will be appended to <body> and positioned and sized each time it is opened. This is useful for widgets within table elements |
| {Boolean} | multiselect | true | If true, allow multiple tags |
| {Boolean} | preventDuplicates | true | If true, the first tag will be removed when a duplicate is typed in |
| {Boolean} | omitAlreadyChosenItems | true | If true, don't suggest items that have already been chosen as tags. Only applicable when options.data is set |
| {Number} | minChars | 3 | The minimum number of characters a user must type before the suggestion box will appear. If 0, show choices when input is simply focused (like a faux select widget) |
| {Number} | keyDelay | 200 | The number of milliseconds between keystrokes before the suggestion lookup begins |
| {Boolean} | addOnComma | true | If true, typing a comma will add the current text as a tag |
| {Boolean} | addOnTab | true | If true, typing a tab will add the current text as a tag |
| {Boolean} | addOnSemicolon | false | If true, typing a semicolon will add the current text as a tag |
| {Boolean} | addOnSubmit | true | If true, add tag on submit if user has entered text but not typed comma or tab |
| {Boolean} | addOnBlur | false | If true, add tag on blur if user has entered text but not typed comma or tab |
| {Boolean} | submitOnEnter | false | If false, prevent the form from submitting when the user presses enter on the empty input |
| {String} | inputSize | auto | Manually set the input size property to a certain width. If auto, set size to text width |
| {String} | placeholder | Placeholder text to display when no tags are present. e.g. "Enter tags..." | |
| {String} | emptyText | Message to show when there are no suggestions - default is "(Type a comma to create a new item)" | |
| {String} | prompt | Message to display in suggestion list when below min char length | |
| {Number} | maxSuggestions | 10 | Only display this many suggestions (use 0 for no limit) |
| {Boolean} | saveToInput | true | If true, save back to original input each time a tag is added or removed |
| {Boolean} | addHiddenInputs | true | If true, also add a hidden input for each tag (fieldname_tag[]) for easier server-side processing (See options.hiddenName to create a custom name) |
| {String} | hiddenName | The name to use for hidden elements (defaults to the original input's name plus "_tags[]") | |
| {Boolean} | highlightSubstring | true | If true, wrap first matching substring in each suggestion with <strong class="sugg-match"></strong> |
| {String} | template | The html used to generate the widget. You can add more markup, change tag names, or add css classes, but all the sugg-* classes need to remain. See below for default. <div class="sugg-widget"> <!-- this.$widget --> <ul class="sugg-box"> <!-- this.$box --> <li class="sugg-box-item sugg-tag"> <!-- this.$tagTemplate --> <span class="sugg-label">TAG TEXT GOES HERE</span><span class="sugg-remove" title="Click to remove">×</span> </li> <li class="sugg-box-item sugg-input-wrapper"> <!-- this.$inputWrapper --> <input type="text" class="sugg-input" value="" autocomplete="off" /> <!-- this.$input --> </li> </ul> <div class="sugg-list-wrapper"> <ul class="sugg-list" style="display:none"> <!-- this.$suggList --> <li class="sugg-item {record.cssClass}">{record.value}</li> <!-- innerHTML is used as this.listItemTemplate unless options.listItemTemplate is set --> <li class="sugg-empty"></li> <!-- this.$empty --> <li class="sugg-prompt"></li> <!-- this.$prompt --> </ul> </div> </div> | |
| {String} | listItemTemplate | Override the .sugg-item element in options.template | |
| {String} | theme | "coolblue" | The css class to add to widget (e.g. "sugg-theme-coolblue"). The following themes come predefined in the CSS: "coolblue", "faceblue", "graybox", "grayred" |
| {Function} | onInitialize | Add a Initialize event | |
| {Function} | onChange | Add a Change event | |
| {Function} | onDefaultSuggestions | Add a DefaultSuggestions event | |
| {Function} | onBeforeAdd | Add a BeforeAdd event | |
| {Function} | onBeforeAjax | Add a BeforeAjax event | |
| {Function} | onBeforeClose | Add a BeforeClose event | |
| {Function} | onBeforeFetch | Add a BeforeFetch event | |
| {Function} | onBeforeFilter | Add a BeforeFilter event | |
| {Function} | onBeforeFormat | Add a BeforeFormat event | |
| {Function} | onBeforeHandleKey | Add a BeforeHandleKey event | |
| {Function} | onBeforeMove | Add a BeforeMove event | |
| {Function} | onBeforeOpen | Add a BeforeOpen event | |
| {Function} | onBeforeRemove | Add a BeforeRemove event | |
| {Function} | onBeforeRender | Add a BeforeRender event | |
| {Function} | onBeforeSave | Add a BeforeSave event | |
| {Function} | onBeforeSubmit | Add a BeforeSubmit event | |
| {Function} | onBeforeSuggest | Add a BeforeSuggest event | |
| {Function} | onAfterAdd | Add a AfterAdd event | |
| {Function} | onAfterAjax | Add a AfterAjax event | |
| {Function} | onAfterClose | Add a AfterClose event | |
| {Function} | onAfterFetch | Add a AfterFetch event | |
| {Function} | onAfterFilter | Add a AfterFilter event | |
| {Function} | onAfterFormat | Add a AfterFormat event | |
| {Function} | onAfterHandleKey | Add a AfterHandleKey event | |
| {Function} | onAfterMove | Add a AfterMove event | |
| {Function} | onAfterOpen | Add a AfterOpen event | |
| {Function} | onAfterRemove | Add a AfterRemove event | |
| {Function} | onAfterSave | Add a AfterSave event | |
| {Function} | onAfterSuggest | Add a AfterSuggest event |
| Event | Data available on event |
Effect of `event.preventDefault()` |
|---|---|---|
| BeforeAdd Fired before a tag is added |
{String} value The tag to be added (writeable) {String} label The value of the tag to be added (writeable) {jQuery} item The suggestion that was chosen, if any (writeable) {Object} record The record that was chosen, if any (writeable) |
The tag is not added |
| AfterAdd Allows you to take action after a tag is added |
{Suggester.Tag} tag The tag object that was added. Has methods such as getElement(), getHidden(), getValue(), getLabel(), etc. {jQuery} item The suggestion that was chosen, if any {String} record The record that was chosen, if any |
- |
| BeforeAjax Edit settings before ajax request is sent |
{Object} settings Settings sent to $.ajax() {String} term The term for which we will search |
- |
| AfterAjax Access the jqXHR after initiating the ajax call but before it returns |
{Object} settings Settings sent to $.ajax() {String} term The term which was searched {JqXHR} jqXHR The jquery XMLHttpRequest object |
- |
| BeforeBlur Respond after user clicks or tabs out of input box |
{jQuery.Event} event The blur event {String} value The current value in the input box. Changing it will change the effictive value. |
Input box remains focused |
| AfterBlur Respond after input box has blurred |
{jQuery.Event} event The blur event {String} value The current value in the input box {jQuery|undefined} newTag The new tag or undefined if the tag was not added on blur |
- |
| Change Fired after a tag is added or removed or after value is manually set |
- | |
| BeforeClose Fired before suggestion box is hidden |
Suggestion box will stay open | |
| AfterClose Fired after suggestion box is hidden |
- | |
| DefaultSuggestions Fired when options.minChars is 0 to allow you to update how default suggestions are displayed. e.g. show the most commonly used values |
{Array} suggetions The suggestions to show by default. Defaults to the first options.maxSuggestions within this.data. Edit value to use your own suggestions. |
No default suggestions are displayed |
| BeforeFetch A chance to access the jqXHR before the ajax request has been sent |
{JqXHR} jqXHR the jQuery XHR object (see http://api.jquery.com/jQuery.ajax/#jqXHR) {String} term the term that is being searched for |
XHR is aborted |
| AfterFetch |
{JqXHR} jqXHR The jQuery XHR object (see http://api.jquery.com/jQuery.ajax/#jqXHR) {Object[]} records The Array of record objects returned from the XHR {String} term The term that was search for |
Nothing is done with results (i.e. suggestion box is not built and displayed) |
| BeforeFilter Called before the search for results |
{String} text The text to search for |
- |
| AfterFilter Called after the search for results |
{String} text The that was searched for {Array} results The array of records that matched (writeable) |
- |
| AfterFocus Respond after input box has focused |
{jQuery.Event} event The focus event |
- |
| BeforeFormat Call to dynamically inject your own formatting on each suggestion |
{Object} record The record object that is being suggested {String} substr The part of the string that matches the suggestion search fields {String} html If you set event.html, it will be used instead of constructing the HTML |
- |
| AfterFormat Alter the HTML that has been constructed before it is put into the DOM |
{Object} record The record object that is being suggested {String} substr The part of the string that matches the suggestion search fields {String} html Change the HTML before it is put into the dom |
- |
| BeforeHandleKey Access the keydown event before Suggester processes it |
{Event} keydown The keydown event (a raw browser event, not jQuery.Event) |
Key is not handled by Suggester. You may want to call event.keydown.preventDefault(); |
| AfterHandleKey Access the keydown event after Suggester processes it |
{Event} keydown The keydown event (a raw browser event, not jQuery.Event) |
- |
| Initialize Do something after the widget is completely rendered and initialized. Note that it fires during instantiation, so an onInitialize property must be set in the constructor. |
- | |
| BeforeMove Fire in response to up or down arrow while suggestion list is focused |
{String} direction "up" or "down" {jQuery|null} current jQuery object with the currently selected item or null if there isn't one (writeable) {jQuery|null} next jQuery object with the item that will be selected next (writeable) |
Movement is cancelled |
| AfterMove Fired after selected suggestion is changed in response to up or down arrow |
{String} direction "up" or "down" {jQuery|null} last The previously selected item {jQuery} current The newly selected item |
- |
| BeforeOpen Fires before suggestion box is displayed |
Box is not displayed | |
| AfterOpen Fires after suggestion box is displayed |
- | |
| BeforePaste Respond before values are pasted |
{jQuery.Event} event The paste event {String} value The raw value that was pasted {Array} tags The array of tags to be added (if the value was successfully split on tab, semicolon, or comma). If changed, the added tags will change. |
tags are not added and paste is cancelled |
| AfterPaste Respond after values are pasted |
{jQuery.Event} event The paste event {String} value The raw value that was pasted {Array} tags The array of tags that were added (if the value was successfully split on tab, semicolon, or comma) |
- |
| BeforeRemove Fired before a tag is removed |
{jQuery} tag The tag to be removed {String} value The value of the tag to be removed (writeable) {String} label The label of the tag to be removed |
The tag will not be removed |
| AfterRemove Fired after a tag is removed |
{jQuery} tag The tag element that was removed {String} value The value of the tag that was removed {String} label The label of the tag that was removed {Suggester.Tag} The tag object that was removed |
- |
| BeforeRender Modify this.$widget or any of its child elements before it is manipulated or appended. Can be used to modify this.options.template with DOM methods. Note that it fires during instantiation, so an onBeforeRender property must be set in the constructor. |
{jQuery} widget A reference to this.$widget |
- |
| AfterRender Do something after the widget is completely rendered. Note that it fires during instantiation, so an onAfterRender property must be set in the constructor. |
{jQuery} widget A reference to this.$widget |
- |
| BeforeSave Inject functionality before saving |
{String} newValue The value that will be written to the original input (writeable) |
- |
| AfterSave Do something after saving value to original input |
{String} oldValue The value before saving {String} newValue The value that was written to the original input |
- |
| BeforeSubmit Respond before form is submitted and before Suggester adds on submit |
{jQuery.Event} The jQuery-wrapped browser event {HTMLFormElement} form The input's form (same as this.$form) |
Form will not be submitted |
| BeforeSuggest Modify suggestion box behavior before it opens |
{String} text The text that was searched for |
The suggestion list is built but not displayed |
| AfterSuggest Fires after displaying suggestions |
- |
| Type | Name | Description |
|---|---|---|
| {jQuery} | $originalInput | The input used to make the widget |
| {Object[]} | data | Array of static data used instead of an ajax call |
| {Suggester.Tag[]} | tags | An array of Suggester.Tag objects |
| {String} | hiddenName | The name to use for hidden elements (defaults to the original input's name plus "_tags[]") |
| {jQuery} | $focusedTag | The tag that is selected for deletion |
| {jQuery} | $currentItem | The item currently selected in the suggestion box |
| {jQuery} | pubsub | The publish and subscribe handle - equal to $(this) |
| {jQuery} | $widget | The element that wraps the widget |
| {jQuery} | $box | The container that holds the chosen tags |
| {jQuery} | $tagTemplate | The tag element that is cloned to make new tags |
| {jQuery} | $input | The input that users type in |
| {jQuery} | $inputWrapper | The container for the input |
| {jQuery} | $suggList | The suggestion list element |
| {jQuery} | $suggListWrapper | The element that is positioned relatively to hold the absolutely positioned suggestion list |
| {jQuery} | $empty | The element enclosing the empty text |
| {jQuery} | $prompt | The element enclosing the prompt |
| {String} | listItemTemplate | The html to use for suggestion list items |
| {String} | _searchTerm | The search term we are currently searching for |
| {String} | _text | The text in the input box that will be used to fetch results (i.e. what the user just typed) |
| {JqXHR} | _jqXHR | The jQuery XHR object used initilized for fetching data - http://api.jquery.com/jQuery.ajax/#jqXHR |
| Type | Name | Description |
|---|---|---|
| {Object} | defaultOptions | Default options. Change these to globally change the default options See constructor for documentation on each option |
| {Array} | instances | A collection of all the instances |
|
destroy([options]) Completely remove Suggester widget and unhide the original input box (with values populated) @param {Object} [options] @return {jQuery} The original input |
|
add(value[, label=value][, $item]) Add a tag by a record or value @param {String} value the tag to add@param {String} [label=value] the text to display in the new tag@param {jQuery} [$item] Set internally when the record is added by choosing from the suggestion box @return {jQuery} The jQuery object containing the newly created label or undefined if one was not created |
|
pushTag(value, label) Add a tag directly without triggering BeforeAdd or AfterAdd @param {String|Number} value The value of the tag@param {String} label The text to display on the tag @return {Suggester.Tag} The new tag object |
|
addCurrentBuffer() Add a tag with the contents of the input; e.g. when the user has typed something but clicks on another part of the form Note: this happens on blur when this.options.addOnBlur is true @return {Suggester} |
|
moveSelection([direction=up]) Move the selection up or down in the suggestion box @param {String} [direction=up] Either "up" or "down" @return {Suggester} |
|
selectItem($tag) Select a suggestion @param {jQuery} $tag @return {Suggester} |
|
deselectItem($tag) Deselect a suggestion @param {jQuery} $tag @return {Suggester} |
|
deselectAllItems() Deselect all suggestions @return {Suggester} |
|
suggest(text) Open suggestion list for the given text @param {String} text @return {Suggester} |
|
addData(data) Add more data records to the autosuggest list. Does not apply when dataUrl is set @param {Object[]} data More records in the same object format as initially set @return {Suggester} |
|
setData(data) Set data records to the autosuggest list. Does not apply when dataUrl is set @param {Object[]} data @return {Suggester} |
|
getData() Get all the records in the autosuggest list. Does not apply when dataUrl is set @return {Object[]} |
|
setFlyDirection(direction) Set the direction of the suggestion menu, to fly upwards or downwards @param {String} direction either "up" or "down" @return {Suggester} |
|
focusTag($tag) Focus on a previously added tag @param {jQuery} $tag The .sugg-tag element to focus @return {Suggester} |
|
unfocusTag() Unfocus the previously focussed tag @return {Suggester} |
|
removeFocusedTag(evt) Remove the focused tag @param {jQuery.Event} evt (optional) Used to check if $document keypress is backspace or delete @return {Suggester} |
|
remove($tag) Remove a tag given its text or jQuery element or HTML element @param {String|jQuery|HTMLElement} $tag the tag to remove @return {Suggester} |
|
findRecord(text) Find a suggestion record by text. Only applies when this.options.data is set. @param {String} text The text to search for @return {Object|false} The matched record object or false if nothing matched. |
|
searchData(value, props) Search through this.data to find a record with a value or label equal to the given value @param {String} value The value or label to find@param {Array} props An array of strings of property names to search @return {Object|Boolean} Returns the record if found, false if not found |
|
suggestIfNeeded() Initiate suggestion process if the input text is >= this.options.minChars, otherwise show prompt @return {Suggester} |
|
showPrompt() Show the prompt text to give a hint to users. Only called when there are no items and this.options.prompt is truthy @return {Suggester} |
|
showEmptyText() Show text indicating there are no suggestions - defined in this.options.emptyText @return {Suggester} |
|
fetchResults(text) Fetch suggestions from an ajax URL @param {String} text The text to search for @return {JqXHR} The jQuery XHR transport that is fetching the data |
|
abortFetch() Cancel the XHR. Used when user starts typing again before XHR completes @return {Suggester} |
|
handleSuggestions(records) Take the given records and build and display suggestion box. Usually only called internally. @param {Array} records The result records to use to build the suggestion list @return {Suggester} |
|
isSuggestBoxOpen() Return true if suggestion box is open @return {Boolean} |
|
openSuggestBox() Manually open the suggestion box in whatever state it is. Usually only called internally. @return {Suggester} |
|
closeSuggestBox() Hide the suggestion box @return {Suggester} |
|
focus() Focus cursor on text input box @return {Suggester} |
|
blur() Unfocus the cursor from the text input box @return {Suggester} |
|
getResults(text) Get suggestion result records given some text (local data) @param {String} text Gather suggestions based on this text @return {Array} Array of Objects of matching records |
|
clear() Clear all the chosen tags @return {Suggester} |
|
getTags() Get a collection of all the chosen tag objects (a shallow copy of this.tags) @return {Array} |
|
eachTag(iterator) Iterate through each of the chosen tag objects @param {Function} iterator The iterator function - function(i, tag) {} @return {Suggester} |
|
serialize() Return a URL query string representing the hidden values of the input @return {String} |
|
getValues() Pluck all the tag values from the chosen tags @return {Array} |
|
getValue() Get the current value as a comma-delimited string @return {String} |
|
_handleEmptyValue() Helper function for setValue() @return {Suggester} |
|
setTheme(themeName) Set the widget's CSS theme - Adds a class "sugg-theme-%name%" to the widget @param {String} themeName The name of the theme to use @return {Suggester} |
|
showPlaceholder([text=this.options.placeholder]) Replace the contents of this.$input with the placeholder value. Automatically fires when this.options.placeholder is set And there are no tags and we are blurring or initially rendering @param {String} [text=this.options.placeholder] The text to set for the placeholder (defaults to this.options.placeholder) @return {Suggester} |
|
hidePlaceholder() Replace placeholder string with empty text @return {Suggester} |
|
publish(type[, data]) Publish the given event name and send the given data @param {String} type The name of the event to publish@param {Object} [data] Additional data to attach to the event object @return {jQuery.Event} The event object which behaves much like a DOM event object |
|
getInstance() Get this instance. Useful for jQuery-style usage: var instance = $('input').suggester(options).suggester('getInstance') @return {Suggester} |
|
_processOptions(options) Set options and interpret options @param {Object} options Settings passed to constructor @return {undefined} |
|
_render() Render the widget and get handles to key elements @return {undefined} |
|
_handleStartValue() Look at the initial element's start value and populate tags as appropriate @return {undefined} |
|
_setupListeners() Attach event handlers @return {undefined} |
|
_onInputFocus(evt) Event handler for when this.$input is focused @param {jQuery.Event} evt The focus event @return {undefined} |
|
_onInputBlur(evt) Event handler for when this.$input is blurred @param {jQuery.Event} evt blur event @return {undefined} |
|
_onTagRemoveClick(evt) Event handler for when .sugg-remove is clicked @param {jQuery.Event} evt The click event @return {undefined} |
|
_onTagClick(evt) Event handler for when .sugg-tag is clicked @param {jQuery.Event} evt The click event @return {undefined} |
|
_onListMouseover(evt) Event handler for when autosuggest list is moused over @param {jQuery.Event} evt The mouseover event @return {undefined} |
|
_onListClick(evt) Event handler for when autosuggest list is clicked @param {jQuery.Event} evt The click event @return {undefined} |
|
_onBoxClick(evt) Event handler for when this.$box is clicked @param {jQuery.Event} evt The click event @return {undefined} |
|
_onKeydown(evt) Handle keypresses while in tag input field @param {Event} evt The keydown event (a raw browser event, not jQuery.Event) @return {undefined} |
|
_onCutDelete(evt) Handle cut and delete on this.$input @param {jQuery.Event} evt The cut, paste, or delete event @return {undefined} |
|
_onPaste(evt) Handle paste on this.$input. Look for places to split pasted value For example pasting "a, b, c" will immediately add 3 tags (when this.options.addOnComma is true) It attempts to split on tab, then if there are no tabs then semicolons, then if there are no semicolons, commas @param {jQuery.Event} evt the paste event @return {undefined} |
|
_key_UP(evt) Handle UP key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_DOWN(evt) Handle DOWN key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_BACKSPACE(evt) Handle BACKSPACE key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_TAB_COMMA(evt) Handle TAB and COMMA and SEMICOLON key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_ESC(evt) Handle ESC key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_ENTER(evt) Handle ENTER key on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_key_other(evt) Handle other keys (e.g. printable characters) on this.$input @param {Event} evt The keydown event @return {undefined} |
|
_onSubmit(jqEvent) Handler for form submission @param {jQuery} jqEvent The submit event @return {undefined} |
|
_beforeFetch(jqXHR) The handler function that is passed to $.ajax({beforeSend:...}) to alter XHR if needed @param {JqXHR} jqXHR The jQuery XHR object (see http://api.jquery.com/jQuery.ajax/#jqXHR) @return {undefined} |
|
_afterFetch(records) Handler passed to $.ajax().done(function(){...}) that handles suggestion data that is returned @param {Array} records The Array of record objects returned from the XHR @return {undefined} |
|
_closeOnOutsideClick(evt) Callback used to close the suggestion box when the user clicks off of it @param {jQuery.Event} evt The click event @return {undefined} |
|
_formatSuggestion(record, substr) Format a suggestion before display @param {Object} record The record that was suggested@param {String} substr The string that generated the list of suggestions @return {String} HTML to use as the item (e.g. '<li class="sugg-item">Suggestion</li>') |
|
_updateInputSize() Update the size when this.options.inputSize is "auto" @return {undefined} |
|
save() Set the value of the original input to a comma-delimited set of labels @return {String} The new value |
|
_spliceTag(value) Given tag text, remove a tag from the internal collection and from the DOM @param {String} value The text of the tag @return {Object|undefined} The record associated with that tag or undefined if not found |
|
_spliceTagByIdx(idx) Given an array index, remove a tag from the internal collection and from the DOM @param {Number} idx The index position in the internal collection @return {Suggester.Tag} The Suggester.Tag object that was removed |
|
getTagIndex(value) Find a tag given value @param {String} value The text of the tag @return {Number} The index position of the tag in the internal collection or -1 if not found |
|
_setupPubsub() Setup publish/subscribe system that uses jQuery's event system. Allows subscribing this way: instance.on('AfterFilter', myhandler) @return {undefined} |
|
_isCursorAtStart() Given an input element, get the cursor position. Used to determine if backspace key should delete the previous tag @return {Boolean} true if the cursor is at the start and no text is selected |
|
setValue(valueOrValues) Set the tags using an array or a comma-delimited string. Commas inside the tag name may be escaped with a backslash. @param {String|Array} valueOrValues To clear value, set to empty string, false, null or undefined @return {Suggester} |
|
addData(data) Add data to all instances @param {Object[]} data Add more data to all the registered instances @return {Suggester} |
|
subclass(jQueryMethodName[, properties]) Create a subclass of Suggester @param {String} jQueryMethodName The method name to add to jQuery.fn@param {Object} [properties] Additional properties and methods to add to subclass @return {Function} The new class object |
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
