J Query UIAutocomplete

Homepage: http://api.jqueryui.com/autocomplete/
Author(s): see http://jqueryui.com/about
Version: 1.12.0

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 J Query 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.

When specifying a remote source in the autocomplete html attribute, the additional css class .jqUIAutocomplete isn't required.

See http://docs.jquery.com/UI/Autocomplete#options for further useful options that can be specified as metadata.

%JQREQUIRE{"ui::autocomplete"}%

<input type='text' class='jqUIAutocomplete {source:["term1", "term2", "..."], delay:500, minLength:3}' />

<input type='text' autocomplete='http://...url to term backend...' />

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.

Array of strings:

[ "term1", "term2", "..." ]

Array of json objects:

[
  {
    label: "display this",
    value: "value is this",
  },
  {
    label: "display this",
    value: "value is this"
  },
  ...
]

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:

<input type="text" id="project" />
<input type="hidden" id="project-id"/>

<img id="project-icon" src="..." />
<div id="project-description"></div>

<literal>
<script type="text/javascript">
var projects = [
  {
      value: "jquery",
      label: "jQuery",
      desc: "the write less, do more, JavaScript library",
      icon: "jquery_32x32.png"
  },
  {
      value: "jquery-ui",
      label: "jQuery UI",
      desc: "the official user interface library for jQuery",
      icon: "jqueryui_32x32.png"
  },
  {
      value: "sizzlejs",
      label: "Sizzle JS",
      desc: "a pure-JavaScript CSS selector engine",
      icon: "sizzlejs_32x32.png"
  }
];

jQuery(function($) {

  $("#project").autocomplete({
    source: projects,
    select: function( event, ui ) {
      $("#project").val(ui.item.label);
      $("#project-id").val(ui.item.value);
      $("#project-description").html(ui.item.desc);
      $("#project-icon").attr("src", "images/" + ui.item.icon );
      return false;
    }
  }).data("ui-autocomplete")._renderItem = function(ul, item) {
      return $("<li></li>")
        .data("item.autocomplete", item)
        .append("<a>" + item.label + "<br>" + item.desc + "</a>")
        .appendTo( ul );
  };
});
</script>
</literal>

Examples

Using local data

Using remote data

This implementation extracts the list of countries from Country List:

%STARTSECTION{"data"}%<noautolink>
%SEARCH{
 "^\| [^\*].*%URLPARAM{"term"}%.* \| *$"
 web="%SYSTEMWEB%"
 topic="CountryList"
 type="regex"
 multiple="on"
 nonoise="on"
 casesensitive="off"
 header="["
 format="\"$pattern(.*?\| ([^\|]*) \|.*)\""
 separator=", "
 footer="]"
}%
</noautolink>%ENDSECTION{"data"}%

See http://jqueryui.com/demos/autocomplete/ for more demos.