Ajax.Autocompleter

Controls > Ajax.Autocompleter

Introduction

Ajax.Autocompleter allows for server-powered autocompleting text fields.

Syntax

new Ajax.Autocompleter(id_of_text_field, id_of_div_to_populate, url, options);

Options (Inherited from Autocompleter.Base)

Option	Default Value	Description
paramName	the ‘name’ of the element	Name of the parameter for the string typed by the user on the autocompletion field
tokens	[]	See Autocompleter.Base
frequency	0.4	How often (in seconds) the input field should be polled for changes before firing an Ajax request.
minChars	1	The minimum number of characters that must be in the input field before an Ajax request is made.
indicator	null	The HTML id of an element to display (using Element.show) while sending the Ajax request. This element will also be hidden with Element.hide when the request is completed. This is useful for displaying an animated spinner during processing. See Ajaxload for some image examples.
updateElement	null	Hook for a custom function called after the element has been updated (i.e. when the user has selected an entry). This function is called instead of the built-in function that adds the list item text to the input field. The function receives one parameter only, the selected item (the <li> item selected)
afterUpdateElement	null	Hook for a custom function called after the element has been updated (i.e. when the user has selected an entry). This function is called after the built-in function that adds the list item text to the input field (note differeence from above). The function receives two parameters, the autocompletion input field and the selected item (the <li> item selected)
callback	null	This function is called just before the Request is actually made, allowing you to modify the querystring that is sent to the server. The function receives the completer’s input field and the default querystring (‘value=XXX’) as parameters. You should return the querystring you want used, including the default part.
parameters	null	If you need to send any additional parameters through your search form, add them here, in the usual {field: 'value',another: 'value'} or 'field=value&another=value' manner.

Example

HTML

<input type="text" id="autocomplete" name="autocomplete_parameter"/>
<div id="autocomplete_choices" class="autocomplete"></div>

Javascript

new Ajax.Autocompleter("autocomplete", "autocomplete_choices", "/url/on/server", {});

HTML with indicator

<input type="text" id="autocomplete" name="autocomplete_parameter"/>
<span id="indicator1" style="display: none">
  <img src="/images/spinner.gif" alt="Working..." />
</span>
<div id="autocomplete_choices" class="autocomplete"></div>

(As with any element destined to work with Prototype’s Element.toggle/show/hide, your indicator element should use an inline style attribute with a display property, here initially set to none. If you need to assign it CSS rules, put the class attribute before the style attribute to avoid override.)

Javascript with options

new Ajax.Autocompleter("autocomplete", "autocomplete_choices", "/url/on/server", {
  paramName: "value", 
  minChars: 2, 
  updateElement: addItemToList, 
  indicator: 'indicator1'
});

CSS
The styling of the div and the returned UL are important.
Applying a visual cue that an item is selected allows the user to take advantage of the keyboard navigation of the dropdown and adding background colors, borders, positioning, etc to the div (as the demo does) allows the UI element to stand out. The CSS from the demo applied to the examples would be:

div.autocomplete {
  position:absolute;
  width:250px;
  background-color:white;
  border:1px solid #888;
  margin:0px;
  padding:0px;
}
div.autocomplete ul {
  list-style-type:none;
  margin:0px;
  padding:0px;
}
div.autocomplete ul li.selected { background-color: #ffb;}
div.autocomplete ul li {
  list-style-type:none;
  display:block;
  margin:0;
  padding:2px;
  height:32px;
  cursor:pointer;
}

Server Return

Look through your POST environment variable for the current entry in the text-box.

The server-side will receive the typed string as a parameter with the same name as the name of the element of the autocompletion (name attribute). You can override it setting the option paramName.

The server must return an unordered list.
For instance this list might be returned after the user typed the letter “y”

<ul>
    <li>your mom</li>
    <li>yodel</li>
</ul>

If you wish to display additional information in the autocomplete dropdown that you don’t want inserted into the field when you choose an item, surround it in a <span> (could work with others but not tested) with the class of “informal”.

For instance the following shows a list of companies and their addresses, but only the company name will get inserted:

<ul>
    <li>ACME Inc <span class="informal"> 5012 East 5th Street</span></li>
    <li>Scriptaculous <span class="informal"> 1066 West Redlands Parkway</span></li>
</ul>

Another way to get aditional information, just send and ID in every list, and redefine afterUpdate Element

<ul>
    <li id="1">your mom</li>
    <li id="2">yodel</li>
</ul>

new Ajax.Autocompleter("autocomplete", "autocomplete_choices", "/url/on/server", {
  afterUpdateElement : getSelectionId
});

function getSelectionId(text, li) {
    alert (li.id);
}

Notes

When a choice is highlighted the Autocompleter applies a class of “selected” to the li element. This allows the end user to style the selected element as desired.

Tutorials

A short tutorial on using Autocompleter, together with Ruby and WEBrick, prepared for the Linux Users Group, Villafranca, Verona, Italy.