Dropdown list of choices with navigation
GvaScript.ChoiceList - Dropdown list of choices with navigation
var choiceList = new GvaScript.ChoiceList(["foo", "bar", "buz"]); choiceList.fillContainer($('myChoiceDiv'));
Displays a list of "choices", handles navigation in those choices, and generates events when a choice is highlighted, then selected, or when the list display is cancelled.
At any moment the choiceList is bound to maximum one "container", and highlights exactly one choice in the list.
Once a choice list is displayed, the user can move the mouse over the
list, thus highlighting various choices; then click on the highlighted
choice to select it. Alternatively, the user can navigate the list
with keys DOWN
, UP
, HOME
, END
, and then use either
RETURN
(for selecting) or ESCAPE
(for cancelling).
var choiceList = new GvaScript.ChoiceList(choices, options);
The choice list must be an array. Each item in the list is either
this string will be displayed in the choice list
this object is supposed to have a label
property, which
will be displayed in the choice list. Actually, this is the default name
for the property; it can be changed in the constructor options.
The label
property may contain rich HTML, i.e. including
formatting tags.
The options to construct an choiceList object are :
Name of the field that contains the HTML to display
(default is label
).
Prefix that will be used to generate ids for choice elements in
the generated HTML. The default is CL_choice
, so choice elements
will have ids CL_choice.0
, CL_choice.1
, etc.
If defined, the choiceList will add rules to the supplied keymap, instead of creating a new one.
How many items to skip when hitting the
PAGE_UP
or PAGE_DOWN
keys.
Default is 5
Classes that will be assigned to choice elements in the generated
HTML. Possible classes are choiceItem
(default value CL_choiceItem
) and
choiceHighlight
(default value CL_highlight
).
Callback function for generating HTML for the choiceList. This function is called with some pre-built HTML containing all current choices; the wrapper has a chance to modify that HTML for example for adding classes, borders or table headers. Default is the identity function.
HTML tag name for generating a choice entry in the choice list.
Default is "div". Set it to "tr" if you want the choice list
to be displayed as a table (but then you also have to
open and close the table within the htmlWrapper
callback).
choiceList.fillContainer(someDiv);
This method generates HTML from the choice list, and inserts
it in the innerHTML
of the supplied container; furthermore,
it registers a keymap on that container in order to manage navigation
from keyboard (DOWN
, UP
, etc.).
This event is triggered when a choice in the list is highlighted.
The event handler may use event.index
to know the index of the
highlighted choice.
This event is triggered when a choice in the list is "ping-ed", i.e.
either by clicking or by pressing the RETURN
key.
Usually this means "select", but it is up to the event handler to decide
how to interpret the event.
The event handler may use event.index
to know the index of the
ping-ed choice.
This event is triggered when the user presses the ESCAPE
key.