|
GvaScript.Autocompleter - autocompletion on form input fields |
GvaScript.Autocompleter - autocompletion on form input fields
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)">
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.
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 the choiceList manpage 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.
var myAutocompleter = new GvaScript.Autocompleter(datasource, options);
A datasource may be
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.
options.ignorePrefix is true)
or just the list of items that are prefixed by the current value
of the field. See also options.caseSensitive.
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
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.
The options to construct an autocompleter object are :
label).
value).
ARROW_DOWN key is pressed.
ignorePrefix is false.
If true (the default), filtering of the datasource array
from the current value of the input field
will be case-sensitive.
PAGE_UP or PAGE_DOWN keys.
Default is 5
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.
For a general explanation on registering handlers for GvaScript events, see the the event manpage 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.
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.
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.
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.
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.
This event is triggered when the user presses the ESCAPE key.
|
GvaScript.Autocompleter - autocompletion on form input fields |