Autocomplete

Page history last edited by Scott González 1 month, 1 week ago

type: widget

release: 1.8

status: complete

documentation: http://docs.jquery.com/UI/Autocomplete

demo: http://jqueryui.com/demos/autocomplete

TODOs

Add aria-owns to the text input, pointing at the menu's id. Add this to the spec.

Also add live-regions to announce available options. Test alternative to textbox role, mostly combobox.
Everett is working on this

1 - Description:

An autocomplete widget helps entering data into text inputs by providing a list of suggetions based on a partial input. Similar behaviour is available in most browsers, but limited to data that the browser already knows about. This widget allows the application developer to provide application specific data, like results from a product search.

If your input or textarea needs multiple (autocompleted) values, use ListBuilder, which builds upon Autocomplete. Autocomplete behavior can also be attached to a select element, in the form of a Combobox.

2 - Visual Design:

3 - Functional Specifications/Requirements:

The list of suggestions...

is displayed when the input has focus and at least one character (or more, depending on minLength option) is entered

when the input has a value and gets focus, the value has to be modified to display the list.

updates on each keydown event.
closes on Tab, and...

focus moves to the next tabbable element.
selects the item that had focus (if any).

selects the item that has focus on Enter and prevents the default form submit.
allows the form to submit on Enter if no item has focus.
is navigable with the keyboard.

Datamodel

The autocomplete requires an array of objects (maps), containing two required properties:

A label property to display in the autocomplete list ("John Doe <john@doe.com>").

this will be displayed as plain-text

A value property that ends up in the input field once selected ("john@doe.com");

if undefined, same as label

Each object can have any amount of additional data associated, usually for filling in related field. This could include:

an id property: a primary key in a database (65313, "FIN57984GFGH69FA")
an index to map to an object (0, 1, ..., n)
a shorthand like a country or province value ('US', 'NY')

If only an array of strings is provided, the widget will normalize that to an array of objects, using each string as both label and value. If only label is provided, its also used as value, and the other way round.

This data must be provided by the source-option.

Options:

delay (number, default: 300)

The delay in milliseconds the autocomplete waits after a keystroke to activate itself.
should be set to something close to 0 for local datasources

minLength (number, default: 1)

The minimum number of characters a user has to type before the autocomplete activates.

source (various, default: null)

a string

gets interpreted as an asynchronous JSON source, with a GET parameter "term" containing the value
the response must be a JSON array

an array

gets intepreted as a local synchronous source

a callback

receives two arguments

request is an object with a single term property and the current input as the value
response is another callback, it expects the suggestions as its single argument

can implement any kind of datasource

use jQuery's $.ajax and customize error handling
delegate to another library
implement custom caching

Methods:

search( [value] )

triggers a search event, which, when data is available, will display the suggestions
can be used by a selectbox-like button to open the suggestions when clicked
if no value is specified, the current input's value is used
call with an empty string and minLength: 0 to display all items

close()

closes the autocomplete menu
useful in combination with the search method, to close the open menu

Events:

triggered before a request (source-option) is started, after minLength and delay are met
can be cancelled to prevent the search

response

triggered after a request (source-option) completes, before the menu is shown
ui.content contains the result and can be modified to change the results that will be shown

open

triggered when the menu is shown

focus

triggered before focus is moved to an item (not selecting)
ui.item refers to the focused item
the default action of focus is to replace the text field's value with the value of the focused item

canceling this event prevents the value from being updated, but does not prevent the menu item from being focused

select

triggered when an item is selected from the menu
ui.item refers to the selected item
the default action of select 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

triggered when the menu is closed
doesn't have to occur together with a change

change

triggered on blur, when the input changed
ui.item refers to the selected item, if one was selected from the suggestion list, else it's null

Keyboard

When the menu is open:

UP: Move focus to the previous item. If on first item, move focus to the input. If on the input, move focus to last item.
DOWN: Move focus to the next item. If on last item, move focus to the input. If on the input, move focus to the first item.
ESCAPE: Close the menu.
ENTER: Select the currently focused item and close the menu.
TAB: Select the currently focused item, close the menu, and move focus to the next focusable element.
PAGE UP/DOWN: Scroll through a page of items (based on height of menu).