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

By giving an Autocomplete field focus or entering something into it, the plugin
starts searching for entries that match and displays a list of values to choose
from. By entering more characters, the user can filter down the list to better
matches.

You can pull data in from a local and/or a remote source: Local is good for
small data sets (like an address book with 50 entries), remote is necessary for
big data sets, like a database with hundreds or millions of entries to select
from.

Autocomplete can be customized to work with various data sources, by just
specifying the source option. A data source can be:

an Array with local data

a String, specifying a URL

a Callback

The local data can be a simple Array of Strings, or it contains Objects for
each item in the array, with either a label or value property or both. The
label property is displayed in the suggestion menu. The value will be inserted
into the input element after the user selected something from the menu. If just
one property is specified, it will be used for both, eg. if you provide only
value-properties, the value will also be used as the label.

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 request parameter "term" gets added to
that URL. The data itself can be in the same format as the local data described
above.

The third variation, the 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 property called "term", which refers to the value currently in the text input. For example, when the user entered "new yo" in a city field, the Autocomplete term will equal "new yo".

A response callback, which expects a single argument to contain 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 (String-Array or Object-Array with label/value/both properties). 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.

Usage

Use %JQREQUIRE{"ui::autocomplete"}% to make use of the library on a wiki page.
Add the .jqUIAutocomplete css class to enable autocompletion.
Specify the url to fetch terms in the autocomplete html attribute.
Add JQuery Metadata to specify further parameters.
When specifying a local data source for autocompletion terms use the source
option within a metadata json object as specified in the examples below.

Writing autocomplete backends

When fetching autocompletion terms from a remote backend the endpoint has to return a json object
of a specific format interpreted by the library. This can either be a plain array of strings or
an array of json objects with a label and an value property.

Custom properties may be specified as part of each json object in the array. Note however to make
use of these you will have to initialize autocompletion using javascript and by
specifying a renderer for items in the autocompltion dropbox yourself like
this: