Jump to content

Guides

ips.ui.autoComplete

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


×