About / Feedback • Demo • Help / Download
Requirements
- Works in Safari 3+, Firefox 3+, Chrome 3+, IE 6, IE 7, IE 8 and Opera 9+
- Requires mootools 1.23+ Core
Download
Comments? Problems? Feedback? Leave a comment »
GitHub Repository: github.com/mariofischer/cwcomplete »
Documentation
General information
On initialization you provide the id of an input field and an URL (to use Ajax) or a javascript-function (which returns the values).
As soon as the user types more than 2 characters (configurable) the values are being fetched — either via javascript or via Ajax (like: yourscript.php?search=whatusertyped).
The Ajax script has to deliver a JSON-formatted array (see below), consisting of keys and values. Values are the possible completions, keys are what you usually expect in the form (an id for example)
Usage
- This autocomplete tool takes a text input field and fetches a list of possible completions
- The list of completions is shown in a layer below the input field, the user can choose an item via keyboard (up/down/enter) or by clicking
- If the user selects an item, the key of this item is written into a field, usually a hidden form field
- You can provide additional action via the onChoose()-event
Javascript Code
var ac = new CwAutocompleter( 'autoinput1' /* ID of the input field */ , 'http://yourserver.com/ajax.php', /* URL of backend ajax script */
{
targetfieldForKey: 'country_code', /* The ID of the field where the selected key goes */
onChoose: function(selection) {
alert("You selected: " + selection.value + " (" + selection.key + ")"); /* Optional function to execute on user selection */
}
)
});
Parameters
- inputfield: ID of the input field
- url: URL of the Ajax script to call (leave empty if you use javascript instead of Ajax)
Options
- ajaxMethod: get How to call the ajax script, via get or post
- ajaxParam: search Name of the parameter which is sent to the ajax script
- inputMinLength: 3 Number of characters entered after which the auto complete starts
- pause: 0 Milliseconds to wait before ajax autocomplete kicks in (wait until user stopped typing), 0 = immediately
- targetfieldForKey: (optional) An element id into which the user selected key is written
- targetfieldForValue: (optional) An element id into which the user selected value is written. Leave empty to use the input field therefore
- suggestionBoxOuterClass: cwCompleteOuter css-classname, change if necessary
- suggestionBoxListClass: cwCompleteChoices css-classname, change if necessary
- suggestionBoxLoadingClass: cwCompleteLoading css-classname, change if necessary
- suggestionBoxHoverClass: cwCompleteChoicesHover css-classname, change if necessary
- clearChoicesOnBlur: true whether to clear choices when the container loses focus
- clearChoicesOnEsc: true whether to clear choices when the container loses focus via esc
- clearChoicesOnChoose: true whether to clear choices when a value is chosen
- setValuesOnChoose: true whether to set values when a choice is selected
- suggestionContainer: {} an existing element which contains the suggestions (optional)
- choiceContainer: ul the element used to encapsulate all choices
- choiceElement: li the element used to encapsulate the actual choice text
Events
- onChoose – Triggered if the user selects an item, parameter is an object with “key” and “value”
- doRetrieveValues – Optional function to provide the values
Format of the ajax response
The response is a JSON-encoded array of two-element arrays containing the key and the value.
The key is for example a country-code and the value is the country name in English.
Providing the response (PHP-example):
$values = array(
array('de','Germany'),
array('fr','France'),
array('us','United States'),
array('uk','United Kingdom'),
);
header('Content-type: application/json');
echo json_encode($result);
Providing values via Javascript
$values = array(
array('de','Germany'),
array('fr','France'),
array('us','United States'),
array('uk','United Kingdom'),
);
header('Content-type: application/json');
echo json_encode($result);
Providing values via Javascript
You can provide the values also via a javascript function. This function receives the user input as parameter (so you can build your list of possible matches), and it returns a two-dimensional array of keys/values. Here is an example:
var ac = new CwAutocompleter( 'autoinput' , '',
{
targetfieldForKey: 'any_id',
onChoose: function(selection) {
alert("You selected: " + selection.value + " (" + selection.key + ")");
},
doRetrieveValues: function(input) {
return [['1','example'], ['2','something else']];
}
});
Note that this example always provides the same two values, in real life you would match input against a list of possible choices.
FAQ
- Why another autocompletion tool?
This is a quick and simple tool, in many cases sufficient. If you need more options and possibilities there are other (more advanced and proven) tools.
- How do I return only matching values via Javascript?
A good method would be to use "Array.filter" from Mootools, but it depends on your requirements