Class: UWA.Controls.Autocomplete

UWA/Controls/Autocomplete. UWA.Controls.Autocomplete

new UWA.Controls.Autocomplete(options)

An autocompletion control.

Available Events

UWA.Controls.Abstract events plus:

Event Description
onSubmit Triggered when "return" is pressed in the input and a completion isn't running
onSetSuggestion Triggered with the suggestion object when the user validate a suggestion
onChange Triggered when the value changed, either on blur or when setting a suggestion
Example
var autocomplete = new UWA.Controls.Autocomplete({
    adaptorOptions: {
        url: "http://gd.geobytes.com/AutoCompleteCity?q={text}"
    }
}).inject(widget.body);
Parameters
Name Type Description
options Object

Options hash or a option/value pair.

Properties
Name Type Argument Default Description
typeDelay String <optional>
 500

debounce key strokes by a delay in millisecond
adaptor AutocompleteAdaptors.Abstract <optional>
 AutocompleteAdaptors.Data

an adaptor to get and render suggestions
adaptorOptions Object <optional>
 {}

options passed to the specified adaptor
inputOptions Object <optional>
 {}

options passed to the input
multiline Boolean <optional>
 false

display a textarea instead of a a single line text input
floatingSuggestions Boolean <optional>
 false

show suggestions in a floating dropdown instead of below the input (only available for multiline input)
previewSuggestion Boolean <optional>
 false

show the currently highlighted suggestion inserted inside the input, selected. This may be helpfull for complicated completions. This will disable the automatic selection of the first suggestion.

Extends

  • UWA.Controls.Abstract

Mixes In

  • UWA.Class.Timed

Index

Members

Methods

Members

name :String

The control name

Type
  • String

options

The default options values.

Methods

isFloating() → {Boolean}

Test if this control has floating suggestions

Returns

whether this control is floating or not

Type
Boolean

getAdaptor() → {AutocompleteAdaptors.Abstract}

Ge the adaptor instance to use for this instance. The adaptor instance is built lazily

Returns

an adaptor instance

Type
AutocompleteAdaptors.Abstract

getContent() → {HTMLelement}

Returns control container.

Returns

Control container.

Type
HTMLelement

getInputControl() → {Input.Text}

Get the control used to display the text input.

Returns
Type
Input.Text

getInputElement() → {DOMElement}

Get the native text input

Returns
Type
DOMElement

<protected> buildSkeleton()

Build the control content. This method is called internally once by instance.

updateSuggestions(options) → {Promise}

Update the suggestion dropdown. This will hide or display the suggestion dropdown, populated with an up to date list of suggestions depending on the current state of the input.

Parameters
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Default Description
resetInput Boolean <optional>
 true

reset the input to its previous value
typeDelay Boolean <optional>

you may override the typeDelay option here
Returns
Type
Promise

getSuggestions(text, caret) → {Promise}

Get a suggestion list from the adaptor. See Adaptor#getSuggestions for the format of suggestion objects.

Parameters
Name Type Description
text String

current text to get suggestions from
caret Number

the caret position inside the text
Returns

resolved with an Array of suggestions objects.

Type
Promise

areSuggestionsDisplayed() → {Boolean}

Check if the suggestion dropdown is shown

Returns
Type
Boolean

displaySuggestions(suggestions)

Opens the dropdown and displays a list of suggestions. See Adaptor#getSuggestions for the format of suggestion objects.

Parameters
Name Type Description
suggestions Array

list of suggestions objects.

hideSuggestions(options)

Closes the dropdown.

Parameters
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Default Description
resetInput Boolean <optional>
 true

reset the input to its previous value
cancelUpdateSuggestions Boolean <optional>
 true

cancel the suggestion update

getValue() → {String}

Get current value from the input.

Returns
Type
String

setValue()

Set the value. This will hide the suggestions dropdown.

<protected> _selectionMouseHandler(event)

Event handler for the mouse events on the dropdown

Parameters
Name Type Description
event Event

the mouse event

<protected> _getParts(start, end) → {Object}

Split the current value into three parts (before, between and after). The two separator indexes are optional and defaults to the current caret positions.

Parameters
Name Type Argument Default Description
start Number <optional>
 caret start

first index to split the value
end Number <optional>
 caret end

second index to split the value
Returns

an object with the fields before, between and after

Type
Object

<protected> _setParts(parts, caretPosition)

Set the input value using an object specifying the content to put after, before and inside (between) the caret.

Parameters
Name Type Argument Default Description
parts Object

an object with the tree fields before, between and after
caretPosition String <optional>
 "end"

the position of the caret after the value is set. Can be "start" (start of the content), "end" (end of the content) or "around" (select the content)

<protected> _getSuggestionIndex(id) → {Number/undefined}

Get the suggestion index (inside the currently displayed suggestions) from either a suggestion object or a DOM element. If the argument is omitted, the current selected sugestion index is returned. If the argument is already a number, it will be returned.

Parameters
Name Type Argument Default Description
id Number/DOMElement/Object <optional>
 current id
Returns

the index or undefined if it is not found

Type
Number/undefined

<protected> _getSuggestion(id) → {Object/undefined}

Get the suggestion object from either an index or a DOM element. If the argument is omitted, the current selected suggestion object is returned. If the argument is already a suggestion object, it will be returned.

Parameters
Name Type Argument Default Description
id Number/DOMElement/Object <optional>
 current id
Returns

the suggestion object or undefined if it is not found

Type
Object/undefined

<protected> _getSuggestionElement(id) → {DOMElement/undefined}

Get the suggestion element from either a suggestion object or an index. If the argument is omitted, the current selected suggestion DOM element is returned. If the argument is a DOM element and is associated with a suggestion, it will be returnerd.

Parameters
Name Type Argument Default Description
id Number/DOMElement/Object <optional>
 current id
Returns

the suggestion Element or undefined if it is not found

Type
DOMElement/undefined

<protected> _resetSuggestion(resetInput)

Remove currently selected suggestion.

Parameters
Name Type Argument Default Description
resetInput Boolean <optional>
 true

reset the input to its previous value

<protected> _getSuggestionParts(suggestion) → {Object}

Gets what should be inserted before, between and after the current input selection for a given suggestion. A fourth value is added, previous, representing the value that will be replaced by the selection.

Parameters
Name Type Description
suggestion Object
Returns

an object with fields before, between, after and previous

Type
Object

<protected> _highlightSuggestion(suggestion)

Select a suggestion, displaying a preview in the input and highlighting it in the dropdown.

Parameters
Name Type Description
suggestion Object/DOMElement/Number

any argument valid for getSuggestion

<protected> _isInlineSuggestionAvailable(suggestion)

Check if inline suggestion is available for a given suggestion

Parameters
Name Type Description
suggestion Object

<protected> _setSuggestion(suggestion, options)

Validate a suggestion. Change the input value by adding the suggestion content and close suggestions dropdown.

Parameters
Name Type Argument Description
suggestion Object/DOMElement/Number

any argument valid for getSuggestion
options Object <optional>
Properties
Name Type Argument Default Description
selectionAtStart Boolean <optional>
 false

set the caret at the beginning of the content

onHideSuggestions()

Invoked when the list of suggestions is hidden.

onShowSuggestions()

Invoked when the list of suggestions is displayed.

onKeyDown()

Invoked when a key is typed in the autocomplete field.