NAME

GvaScript.Autocompleter - autocompletion on form input fields

SYNOPSIS

In Javascript :

  var autocompleter1 = new GvaScript.Autocompleter(
      "http::/some/url", 
      {minimumChars : 2, 
       strict       : true, 
       onBind       : doSomething,
       onLeave      : doSomethingElse}  );

  var autoCompleter2 = new GvaScript.Autocompleter(
        ["foo", "bar", ...], options);

  var autoCompleter3 = new GvaScript.Autocompleter(
        [{label: "foo", value: "f", otherValue: 123},
         {label: "bar", value: "b", otherValue: 456}, ...], options);

  var autoCompleter4 = new GvaScript.Autocompleter(
        myCompletionFunction, options);

Then, in HTML :

  <input onfocus="autoCompleter1.autocomplete(this)">

DESCRIPTION

Component designed both as an "autocompleter" (anticipating further key events by users) and as a replacement for HTML SELECT form items.

An autocompleter instance encapsulates a datasource (which may be an inline object, a callback function or an Ajax request), together with some behavioral options (detailed below). That autocompleter may then be bound to one or several input fields in a form (but only one at a time), and will take care of capturing user input, navigating in the suggestion list, and filling the field with the chosen value.

An event model is associated with the autocompleter, so that client code can insert its own hooks to various steps of the autocompletion behaviour.

The list of suggestions may contain arbitrary HTML, including rich formatting options.

BEHAVIOUR

When the input field gets focus, the autocompleter starts listening for key events. As soon as minimumChars have been typed, or if the user presses the DOWN arrow key, the autocompleter gets a list of suggestions from the datasource, and displays them in a dropdown list.

The dropdown list can be navigated through arrow keys. Selecting a suggestion in the list is done either by a click, or by pressing the RETURN key (this is handled by the choiceList component of GvaScript). Then the value of that suggestion fills the input field value, the jsonValue property of that field is set to whatever was contained in the suggestion object, and the onComplete event is triggered.

A number of Variations on this behaviour may be controlled by the options described below.

CONSTRUCTOR

  var myAutocompleter = new GvaScript.Autocompleter(datasource, options);

Datasources

Origin

A datasource may be

a plain string

The string is taken as a base URL. Whenever a suggestion list is needed, the autocompleter will send an Ajax requests to that URL, concatenated with the current value in the associated field. So for example if we have

  var ac = new GvaScript.Autocompleter("http://my/server/completion?search=");
  ..
  <input name="someInput" onfocus="ac.complete(this)">

and user has typed ab in the input field, then an Ajax request will be sent to http://my/server/completion?search=ab.

The server should return a JSON array, in the format explained below.

a callback function

That function will be called, with the current value of the field as single argument.

an array

The array is taken as in-memory datasource. The returned suggestion list is either the complete array (when options.ignorePrefix is true) or just the list of items that are prefixed by the current value of the field. See also options.caseSensitive.

Format of suggestions returned by datasources

Datasources should return a list of suggestions in the form of a Javascript array (in case of Ajax requests, the response should be a JSON body containing a single array).

For each suggestion in the array, the autocompleter needs a label (an HTML fragment to display in suggestion dropdown lists) and a value (a plain string to put into the text field when the suggestion is selected). So each suggestion may be either

a plain string

this string will be used both as label and as value.

an inline object

this object is supposed to have a label property and a value property. Actually, these are the default names for the properties; they can be changed in the constructor options.

The label property may contain rich HTML, i.e. including formatting tags.

Options

The options to construct an autocompleter object are :

minimumChars

How many characters are needed before trying to find suggestions.

labelField

Name of the field that contains the HTML to display (default is label).

valueField

Name of the field that contains the value to put in input element (default is value).

autoSuggest

Boolean value; toggles whether suggestions are displayed automatically when available (true by default). If false, suggestions are only displayed when the ARROW_DOWN key is pressed.

autoSuggestDelay

How many milliseconds to wait after a keypress before displaying suggestions. Default is 200.

typeAhead

If true (the default), the current suggestion will be automatically inserted into the input element.

maxHeight

Maximum height for the suggestion DIV (in pixels). Default is 200.

minWidth

Minimum width for the suggestion DIV (in pixels) Default is 200.

offsetX

Offset (in pixels) from the left border of the input element to the left border of the suggestion DIV. Default is 0.

strict

If this option is true and the user leaves the field with an illegal value (not in the suggestion list), the field is marked with a red background. Dfault is false.

blankOK

If this option is defined and false, the field is marked with a red background when left with an empty value. Default is true.

ignorePrefix

If true, and if the datasource is a Javascript array, then that whole array is always displayed as suggestions, whatever may be typed in the input field (so the field behaves more or less like a SELECT). Default is false.

caseSensitive

This option only applies if the datasource is a Javascript array and if ignorePrefix is false. If true (the default), filtering of the datasource array from the current value of the input field will be case-sensitive.

colorIllegal

Which color to put in the background when a "strict" field contains an illegal value (default is red).

scrollCount

How many items to skip when hitting the PAGE_UP or PAGE_DOWN keys. Default is 5

METHODS

autocomplete(inputField)

Returns an event handler to be bound to the onfocus event on an input field, i.e.

  <input name="someInput" onfocus="myAutoCompleter.complete(this)">

The autocompleter will automatically register an onblur handler on the same field, so avoid setting your own, which may cause unpredictable interactions. However the autocompleter has its own event model with an onLeave event to which you can bind your handling code.

detach(inputField)

Detaches the autocomplete object from the input field (i.e. remove onblur and onkeypress handlers that were previously set by the autocomplete method).

displayMessage(messageText)

Displays the given message within a newly created dropdown DIV under the input field. Used internally to warn for example about illegal values.

EVENTS

For a general explanation on registering handlers for GvaScript events, see the event documentation. In short, you can register handlers either on the HTML input element, as in

  <input name="someInput" onfocus = "myAutoCompleter.complete(this)"
                          onBind  = "bindHandler(this, event)"
                          onLeave = "leaveHandler">

or on the javascript object, as in

   myAutocompleter.onBind = function(event) {
        bindHandler(event.target, event)
   };
   myAutocompleter.onLeave = leaveHandler;

Below is the list of events generated by autocompleter objects.

onBind

This event is triggered whenever the autocompleter object becomes associated with an input field; typically this occurs when the input field receives focus and then calls the "autocomplete" method.

onLeave

This event is triggered whenever the autocompleter object cuts the association with an input field; typically this occurs when the input field loses focus ( calls the "autocomplete" method.

onComplete

This event is triggered whenever the user has chosen an item in the displayed suggestion list. The event handler may use event.index to know the index of the selected choice.

onHighlight

This event is triggered when a choice in the dropdown list of choices is highlighted. The event handler may use event.index to know the index of the highlighted choice.

onCancel

This event is triggered when the user presses the ESCAPE key.

cpanm Alien::GvaScript

perl -MCPAN -e shell
install Alien::GvaScript