Description
The autocomplete widget adds two groups of functionality to a text input. Firstly, it adds support for suggestions based on what the user is typing, and secondly, it adds support for tokenization, allowing the user to enter multiple distinct values into one field. This functionality is useful for entering tags, for example.
Example
@todo
Usage
The autocomplete widget should be initialized on a text input with the correct widget key attribute:
<input type='text' placeholder='Enter text to search' name='field_name' data-ipsAutocomplete data-ipsAutocomplete-dataSource='...'>
Obtaining an autoComplete reference
If you need to control an autoComplete programmatically, you can do so by first obtaining a reference to the instance. To do so, call the getObj method, passing in the element on which the dialog was created as the parameter:
// HTML
<input type='text' id='inputWithAutocomplete' data-ipsAutocomplete>
// Javascript
var autocomplete = ips.ui.autocomplete.getObj( $('#inputWithAutocomplete') );
You can then call the methods below on the returned reference.
Methods
addToken( string value )
Returns boolean; true on success.
Adds a token to the autocomplete with the provided value.
getTokens()
Returns array containing values.
Fetches all of the token values currently present in the autocomplete.
removeToken( element token )
Returns void.
Removes the given token element from the autocomplete. Note that this method expects the DOM/jQuery token element, not the value.
removeAll()
Returns void.
Removes all tokens from the autocomplete.
Options
dataSource
(Mixed; optional)
Specifies the data source that the autocomplete widget should use for suggestions. Possible values:
- URL - when a URL is supplied, the widget will fetch results from this address with the current value as the parameter q, expecting a JSON object in response
- Selector - which locates a datalist element on the page, the options of which will provides the results
- None - initializes the autocomplete widget with no dataSource, meaning suggestions will not be offered to the user
maxItems
(Number; optional)
Specifies the maximum number of tokens the user can enter into the field. When the maximum is reached, no further tokens can be added.
minLength
(Number; optional)
Specifies the minimum length a value must be, when freeChoice is true.
maxLength
(Number; optional)
Specifies the maximum length a value can be, when freeChoice is true.
unique
(Boolean; optional; default false)
Determines whether tokens entered must be unique. If true, a duplicate will not be permitted and a tooltip will inform the user why. In addition, when a token is used it is automatically removed from the list of suggestions offered for further tokens.
freeChoice
(Boolean; optional; default true)
If true, the user will be able to enter their own values. If false, they will only be able to select values from the suggestion list. e.g.
@todo
forceLower
(Boolean; optional; default false)
Forces all tokens entered to be lowercase.
resultsElem
(Selector; optional)
By default, when suggestions are presented they will appear in a floating list attached to the text field. If a selector is provided in this option, the results will instead be inserted into the element it locates.
queryParam
(String; optional; default 'q')
If a URL is used for dataSource, this parameter provides the parameter name used for the lookup e.g. index.php?q=<term>.
addTokenText
(Template key; optional; default 'core.autocomplete.addToken')
If freeChoice is false, this option specifies the template that will be used to build the link that the user will click to display the suggestions list.
fieldTemplate
(Template key; optional; default 'core.autocomplete.field')
The key to the template that will be used to build the widget wrapper (into which the original text field is inserted).
resultsTemplate
(Template key; optional; default 'core.autocomplete.resultItem')
The key to the template that will be used to build an item within the suggestions list. For example, in a list for selecting colors, the template might show a swatch alongside the name.
tokenTemplate
(Template key; optional; default 'core.autocomplete.token')
The key to the template that will be used to render an individual token when it is created in the field.
Events
Events are emitted on the original text field.
autoCompleteReady
Triggered when the autocomplete widget is ready for interaction (i.e. the wrapper is built and existing values have been constructed and inserted).
Event data:
-
elemID
ID of the element the widget was initialized on -
elem
Reference to the above element -
currentValues
Array of current values in the widget (in this case, values that already existed when the widget was initialized)
tokenAdded
Triggered when a token is created in the text field, either by selecting a value or hitting the delimiter character (comma by default)
Event data:
-
token
The value of the token that has been added -
tokenList
Array of all current token values -
totalTokens
Count of the number of tokens added -
html
The HTML representing this item in the results list
tokenDeleted
Triggered when a token is deleted
Event data:
-
token
The value of the token that has been deleted -
tokenList
Array of all current token values -
totalTokens
Count of the number of tokens added
Report Guide