Ajax.Autocompleter

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

 

Availability

 

script.aculo.us V1.1 ???

 

Syntax

 

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

 

Options (inherited from Autocompleter.Base)

 

 

Option

Default

Description

paramName

‘name’ of the element

Name of the parameter for the string typed by the user on the autocompletion field

tokens

(empty array) []

See Autocompleter.Base

frequency

0.4


minChars

1

Minimum characters required to query the server

indicator

null

When sending the Ajax request Autocompleter shows this element with Element.show. You can use this to e.g. display an animated “please-wait-while-we-are-working” gif. See here for examples. When the request has been completed it will be hidden with Element.hide.

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)

 

Examples

 

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 Styles

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>

 

Display additional information

 

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:

 

Response

<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>

 

Working with Callback

 

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

 

Response

<ul>

    <li id="1">your mom</li>

    <li id="2">yodel</li>

</ul>

 

Javascript

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.