Module documentation for ui.combobox.js

init

Main JQuery method. Call $(selector).combobox(options) on any element, or collection of elements, to turn them into a combobox.

All event handlers take 2 arguments: the original browser event, and an object with the following fields:

• value: the current value of the input field
• index: the index within the option list of the presently-selected value, or -1 if directly inputted.
• isCustom: true if the user has typed in an option not on the list
• inputElement: JQuery object containing the input field
• listElement: JQuery object containing the drop-down list

Params

options (Object)

Options hash

Options

data (Array)

List of options for the combobox

autoShow (Boolean)

If true (the default), then display the drop-down whenever the input field receives focus. Otherwise, the user must explicitly click the drop-down icon to show the list.

matchMiddle (Boolean)

If true (the default), then the combobox tries to match the typed text with any portion of any of the options, instead of just the beginning.

key (Function(e, ui))

Event handler called whenever a key is pressed in the input box.

change (Function(e, ui))

Event handler called whenever a new option is selected on the drop-down list (eg. down/up arrows, typing in the input field).

select (Function(e, ui))

Event handler called when a selection is finished (enter pressed or input field loses focus)

arrowUrl (String)

URL of the image used for the drop-down arrow. Used only by the default arrowHTML function; if you override that, you don't need to supply this. Defaults to "drop_down.png"

arrowHTML (Function())

Function that should return the HTML of the element used to display the drop-down. Defaults to an image tag.

listContainerTag (String)

Tag to hold the drop-down list element.

listHTML (Function(String, Int))

Function that takes the option datum and index within the list and returns an HTML fragment for each option. Default is a span of class ui-combobox-item.

destroy

Remove all combobox functionality from this element, restoring the original element.

setData

Dynamically changes one of the combobox options.

Params

key (String)

Option name.

value (Object)

New value.

showList

Programmatically shows the drop-down list.

Params

e (Event)

Original event triggering this.

hideList

Programmatically hide the drop-down list.