type: widget

release: 1.8

status: complete

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

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

 

 

---

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.

 

The autocomplete can be attached to a select-element, but that isn't the primary focus. For select elements with only a few items (less then 15), Selectmenu is the better choice. For selects with a lot of items, Autocomplete can make it easier to select elements.

 

If your input or textarea needs multiple (autocompleted) values, use ListBuilder, which builds upon Autocomplete.

 

The widget depends on Position to handle positioning of the suggestion list, as well as bgiframe.

---

 

2 - Visual Design:

 

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

Common behaviors:

 

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, another character has to be added to display the list
• is also displayed to display the list via a click on a double click (can be triggered with an additional arrow-down button), even without any value entered (and minLength: 0)
• updates on each keydown event
• a Tab keypress will always close the autocomplete and tab to the next field, and...
• insert the item that had focus in the suggestion list into the input
• do nothing when no item had focus
• a Enter keypress will select the selected item (preventing the default form submit) or do nothing special when there is no selected item (allow the default form submit)
• must be navigable with the keyboard:
• arrow down to move focus from the input to the first suggestion (then to the 2nd item with the next down arrow)
• page up/down to skip a page of items, depending on the size of the select in a scrollable list
• when nothing is selected, same behaviour as arrow up/down
• when something is selected, either stop at top or bottom edges, or scroll a full page, no matter if the first, last or any other item is focused on the current page
• from the first suggestion, arrow up to bring focus back to the input
• from the last suggestion, arrow down to bring focus back to the input
• arrow up from the input to focus last suggestion
• in other words, there are number of suggestions + 1 focusable items, where up/down rotates the focus, looping at the start and end
• whenever an item gets focus, its result-value is inserted into the textfield; when the focus goes back to the input, the original input value is restored (not mouse events)
• hide suggestions on escape

 

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 can be HTML markup, if a seperate markup-free value is specified.
• A value property that ends up in the input field once selected ("john@doe.com");
• if undefined, same as label
• this must be plain-text (no markup)

 

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 autocompleter waits after a keystroke to activate itself.
• should be set to something close to 0 for local datasources (eg. as part of the select-autocomplete plugin)
• minLength (number, default: 1)
• The minimum number of characters a user has to type before the autocompleter activates.
• source (various, default: none)
• a string
• gets interpreted as an asynchronous JSON source, with a GET parameter "term" containing the value
• the response must be a JSON array, containing either strings or objects with either a label or value properties, or both
• the response can contain any additional properties on each object
• an array
• gets intepreted as a local synchronouse source
• can be a string array, then each value is used as both label and value
• can be an array of objects, containing at least a label or value property; can contain any additional data
• 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 suggetions as the single argument
• can implement any kind of datasource
• use jQuery's $.ajax and customize error handling
• delegate to another library
• customize response, eg. highlighting the matched term in each label

 

Methods:

• search( [value] )
• triggers a search event, which, when data is available, then 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()
• close the autocomplete menu
• useful in combination with the search method, to close the open menu

Events:

• search
• before a request (source-option) is started, after minLength and delay are met
• can be cancelled
• open
• after the result is back, before it is actually displayed; also indicating the list to open
• focus
• 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
• close
• when the list is hidden
• doesn't have to occur together with a change
• change
• 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

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

    <input type="text" />

 

     4.2 Recommended transformed HTML markup

 

 

     http://jquery-ui.googlecode.com/svn/trunk/autocomplete/tests/static/autocomplete/autocomplete.html

 

     4.3 Accessibility recommendation

 

     Not defined yet.

     See http://www.w3.org/WAI/PF/aria/#aria-autocomplete

 

     4.4 CSS & Theme

 

    Found in markup (see 4.2).

     In addition, while data is loaded, a class "ui-autocomplete-loading" is added to the input element. This can be used to display a loading indicator, eg. an animated gif.

---

 

5 - Latest version of plugin:

 

 

http://jquery-ui.googlecode.com/svn/trunk/tests/visual/autocomplete/default.html

 

Transforming a select into a combobox:

 

http://jquery-ui.googlecode.com/svn/trunk/demos/autocomplete/combobox.html

 

Using a jsonp webservice (via geonames.org):

 

http://jquery-ui.googlecode.com/svn/trunk/demos/autocomplete/remote-jsonp.html

 

---

 

6 - Open issues being discussed

 

Add a blur event since we have a focus event?

 

A cache option may eventually look like this:

• cache (boolean, default: true)
• if true, results will be cached when the returned resultset will only get smaller by further filtering
• if false, caching is disabled and new data is always requested
• One measure of figuring out if the result will only get smaller, or is still just a subset, is to compare the result size between two requests: When "foo" returns 50 results, and "foot" return 50 results, do another request for "foote".

  When "foo" returns 50 results, and "foot" returns 45 results, use the local cache for anything further ("foote", "footer", etc.).

 

An implementation that doesn't require any configuration would be preferable. For now, anyone interested has to implement it himself using the source option, using this as a reference: http://jqueryui.com/demos/autocomplete/#remote-with-cache