Alien::GvaScript::AutoCompleter(3)

NAME
Alien::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 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 Alien::GvaScript::ChoiceList component of GvaScript). Then the value of that suggestion fills the input field value, dependent fields (if any) are updated, and the "onLegalValue" 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("/myapp/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 "/myapp/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".

an object (JSONP)
    Useful when accessing data on a different domain via JSONP services.

      Ex :   { json_url: 'http://search.yahooapis.com/WebSearchService/V1/relatedSuggestion?appid=YahooDemo&query=?1&output=json&callback=?2',
               json_list: 'ResultSet/Result' }

    The object should hold details of the JSONP service to be called.

    "json_url" : url to call with placeholders (?1, ?2) for value to look for and callback method respectively.

    "json_list" : path to the list in the json response

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

htmlWrapper
    See the "ChoiceList" documentation.

choiceItemTagName
    See the "ChoiceList" documentation.

classes
    Classes that will be assigned at various stages to autocompleter DOM elements . Possible classes are

    loading
        Class added to the input or textarea field while an Ajax request is pending. Default is "AC_loading", a class that displays an Ajax-loading icon.

    dropdown
        Class for the dropdown div that displays the autocompletion choices. Default is "AC_dropdown".

    message
        Class for displaying warning messages. Default is "AC_message".

additional_params
    Other parameters to be added in the Ajax query for autocompletion. Can be either an array or an already encoded string (see "Ajax.Options" in "prototype.js"). [TODO: should be camelCase to be consistent with other options; check dependencies in DMWeb].

dependentFields
      var ac =  new GvaScript.Autocompleter(url, {
                  dependentFields : {
                    foo : "firstname",
                    bar : "lastname",
                    id  : "id"
                  } } );

    Inline object that specifies dependencies between the field controlled by the autocompleter, and other fields in the same form. When leaving the autocompleted field ("onBlur"), the dependent fields will be updated automatically. This only works for autocompleters in strict mode.

    Each key in the inline object specifies the name of a field related to the autocompleted field. If field names are in dotted notation, then the related field is taken as a path relative to the autocompleted field : so for example if the autocompleted field has name "some.very.3.long.2.path", then the "foo" entry in "dependentFields" will refer to field "some.very.3.long.2.foo".

    The corresponding value (in our example above: "firstname") is the name of a property to extract from the "choice" member that validated the current input. However, the autocompleted field may also contain an empty value (in which case the related fields are also emptied), or an illegal value (in which case the related fields are filled with string "ILLEGAL_***", where "***" is the key from the inline object).

    If the "choice" member is not an object, but just a string, then that string is copied to the dependent field, therefore ignoring the hash value ("firstname" in our example).

    As a special case, if the hash value is an empty string, then the dependent field is emptied, ignoring whatever information may be in the "choice" element.

    The dependent fields structure might also be specified as an HTML attribute "ac:dependentFields", instead of an option to the Javascript object :

      <input name="some.very.3.long.2.path"
             onfocus="ac.autocomplete(this)"
             ac:dependentFields="{foo:'firstname',bar:'lastname',id:'id'}" />
      ...
      <input type="hidden"
             name="some.very.3.long.2.id" />

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 "onblur", "onclick" and "onkeydown" handlers on the same field, so avoid setting your own, which may cause unpredictable interactions. However the autocompleter has its own event model to which you can bind your handling code (see the EVENTS section below).

  detach(inputField)
Permanently detaches the input field from the autocompleter object (i.e. removes "onblur" and "onkeypress" handlers that were previously set by the first invocation of 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.

If in strict mode, the autocompleter object will also check if the final value is legal or illegal with respect to the list of available choices. This may require an additional Ajax call, so the "onLeave" event may be triggered before the "onLegalValue" or "onIllegalValue" events.

  onComplete
[OBSOLETE; use "onLegalValue" or "onIllegalValue" instead]

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.

  onLegalValue
This event is triggered when the autocompleter is in strict mode, the input field has just been left ("onBlur" event), and the autocompleter was able to verify that the current input value belongs to the list of available choices.

The event contains a "value" property (current value in the input element), and a "choice" property (member of the "choices" array that matches the current value). The "controller" property is null because the event may occur after the autocompleter object has been detached from the input field and has been perhaps already bound to another field, so interacting with the autocompleter from the event handler would lead to inconsistencies.

  onIllegalValue
This event is triggered when the autocompleter is in strict mode, the input field has just been left ("onBlur" event), and the autocompleter was not able to verify that the current input value belongs to the list of available choices.

The event only contains a "value" property (current value in the input element). The "controller" property is null (same reasons as "onLegalValue" above).

return "true" in onIllegalValue handler to override the illegal behavior; i.e. coloring the input in red and invalidating the dependentFields.

  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.