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