Show:

Autocomplete enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

The widget is based on popular jQuery UI Autocomplete widget, but it brings some advanced built-in features:

  • caching
  • tokenizing
  • using DOM as a source of suggestions
  • auto-fill
  • built-in button

Methods

close

()

Closes the Autocomplete menu. Useful in combination with the search method, to close the open menu.

destroy

()

Removes the autocomplete functionality completely. This will return the element back to its pre-init state.

disable

()

Disables the autocomplete.

enable

()

Enables the autocomplete.

option

()

option( optionName )

Gets an object containing key/value pairs representing the current autocomplete options hash.

option()

Gets an object containing key/value pairs representing the current autocomplete options hash.

option( optionName, value )

Sets the value of the autocomplete option associated with the specified optionName.

option( options )

Sets one or more options for the autocomplete.

widget

()

Returns a jQuery object containing the menu element. Although the menu items are constantly created and destroyed, the menu element itself is created during initialization and is constantly reused.

Properties

appendTo

Selector

Which element the menu should be appended to. When the value is null, the parents of the input field will be checked for a class of ui-front. If an element with the ui-front class is found, the menu will be appended to that element. Regardless of the value, if no element is found, the menu will be appended to the body.

Default: null

autoFill

Boolean

Auto filling mode previews a selected suggestion in the input as a user types.

Default: false

autoFocus

Boolean

Auto focusing mode selects first suggestion in a list once it appears, so user can just confirm it using enter key.

Default: false

cached

Boolean

Turns suggestions caching on.

In caching mode, autocomplete first tries to look suggestions for given term up in cache given by cacheImplementation option and if no suggestions are found, autocomplete uses classic source to retrieve suggestions.

Default: false

cacheImplementation

Object

Allows to plug in implementation of cache, which in turn allows to use stores like Local Storage for remembering values.

cacheImplementation is an class with two methods:

  • function get(searchTerm) - returns all cached suggestions for given searchTerm prefix
  • function set(searchTerm, suggestions) - stores all provided suggestions into cache under given searchTerm prefix

Default: $.rich.autocomplete.ObjectCache

cachePrefixExtract

Function

Function that determines what prefix of search term will be used to query a cache:

function cachePrefixExtract(searchTerm) - default implementation extracts first minLength characters of a search term

Default: $.rich.autocomplete.cachePrefixExtract

delay

Integer

The delay in milliseconds between when a keystroke occurs and when a search is performed. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.

Default: 0

disabled

Boolean

Disables the autocomplete if set to true.

Default: false

filter

Function

Provide function which will be used to filter array of suggestions by given searchTerm:

function filter(array, searchTerm)

minLength

Number

The minimum number of characters a user must type before a search is performed. Zero is useful for local data with just a few items, but a higher value should be used when a single character search could match a few thousand items.

Default: 0

position

Object

Identifies the position of the suggestions menu in relation to the associated input element. The of option defaults to the input element, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.

Default: `{ my: "left top", at: "left bottom", collision: "none" }`

showButton

Boolean

Allows to append a button to the input to allow opening suggestion box by mouse.

Default: false

source

Unknown

Defines the data to use, must be specified.

Multiple types supported:

  • Array: An array can be used for local data.There are two supported formats:

    • An array of strings: [ "Choice1", "Choice2" ]
    • An array of objects with label and value properties: [ { label: "Choice1", value: "value1" }, ... ]

      The label property is displayed in the suggestion menu. The value will be inserted into the input element when a user selects an item. If just one property is specified, it will be used for both, e.g., if you provide only value properties, the value will also be used as the label.

  • String: When a string is used, the Autocomplete plugin expects that string to point to a URL resource that will return JSON data. It can be on the same host or on a different one (must provide JSONP). The Autocomplete plugin does not filter the results, instead a query string is added with a term field, which the server-side script should use for filtering the results. For example, if the source option is set to "http://example.com" and the user types foo, a GET request would be made to http://example.com?term=foo. The data itself can be in the same format as the local data described above.

  • Function: The third variation, a callback, provides the most flexibility and can be used to connect any data source to Autocomplete. The callback gets two arguments:

    • A request object, with a single term property, which refers to the value currently in the text input. For example, if the user enters "new yo" in a city field, the Autocomplete term will equal "new yo".
    • A response callback, which expects a single argument: the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data. It's important when providing a custom source callback to handle errors during the request. You must always call the response callback even if you encounter an error. This ensures that the widget always has the correct state.

      When filtering data locally, you can make use of the built-in $.ui.autocomplete.escapeRegex function. It'll take a single string argument and escape all regex characters, making the result safe to pass to new RegExp().

token

String

Allows to repeat auto-completion several times by using separator between words.

You can provide multiple tokens.

Default: null

Events

change

Triggered when the field is blurred, if the value has changed.

close

Triggered when the menu is hidden. Not every close event will be accompanied by a change event.

create

Triggered when the autocomplete is created.

focus

Triggered when focus is moved to an item (not selecting). The default action is to replace the text field's value with the value of the focused item, though only if the event was triggered by a keyboard interaction. Canceling this event prevents the value from being updated, but does not prevent the menu item from being focused.

open

Triggered when the suggestion menu is opened or updated.

response

Triggered after a search completes, before the menu is shown. Useful for local manipulation of suggestion data, where a custom source option callback is not required. This event is always triggered when a search completes, even if the menu will not be shown because there are no results or the Autocomplete is disabled.

select

Triggered when an item is selected from the menu. The default action is to replace the text field's value with the value of the selected item. Canceling this event prevents the value from being updated, but does not prevent the menu from closing.

update

Triggered when search is triggered but before raw suggestions are parsed/processed.

It gives chance to update source of suggestions as reflection to current search term.

function update(request [, doneCallback])

  • request is object which contains search term: { term: 'searchTerm' }
  • when doneCallback is provided, widget will wait until doneCallback is called. Usually it is called on the end of AJAX data update.