CwComplete – Help

About / FeedbackDemoHelp / 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

Download at Mootools Forge »

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

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