Class: Combobox

LuCI.ui. Combobox

The Combobox class implements a rich, stylable dropdown menu which allows to enter custom values. Historically, comboboxes used to be a dedicated widget type in LuCI but nowadays they are direct aliases of dropdown widgets with a set of enforced default properties for easier instantiation.

UI widget instances are usually not supposed to be created by view code directly, instead they're implicitely created by LuCI.form when instantiating CBI forms.

This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Combobox. To import it in external JavaScript, use L.require("ui").then(...) and access the Combobox property of the class instance value.

new LuCI.ui.Combobox(value, choices, options)

ui.js, line 1860

Instantiate a rich dropdown choice widget allowing custom values.

Name Type Default Description
value string | Array.<string> null optional

The initial input value(s).
choices Object.<string, *>

Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels.
options LuCI.ui.Combobox.InitOptions optional

Object describing the widget specific options to initialize the dropdown.

Extends

Methods

inherited addChoices(values, labels)

ui.js, line 1606

Add new choices to the dropdown menu.

This function adds further choices to an existing dropdown menu, ignoring choice values which are already present.

Name Type Description
values Array.<string>

The choice values to add to the dropdown widget.
labels Object.<string, *>

The choice label values to use when adding dropdown choices. If no label is found for a particular choice value, the value itself is used as label text. Choice labels may be any valid value accepted by LuCI.dom#content.

inherited clearChoices(reset_value)

ui.js, line 1571

Remove all existing choices from the dropdown menu.

This function removes all preexisting dropdown choices from the widget, keeping only choices currently being selected unless reset_values is given, in which case all choices and deselected and removed.

Name Type Default Description
reset_value boolean false optional

If set to true, deselect and remove selected choices as well instead of keeping them.

inherited closeAllDropdowns()

ui.js, line 1639

Close all open dropdown widgets in the current document.

inherited isValid(){boolean}

ui.js, line 107

Check whether the current input value is valid.

Returns:
Type Description
boolean Returns true if the current input value is valid or false if it does not meet the validation constraints.

inherited registerEvents(targetNode, synevent, events)

ui.js, line 156

Dispatch a custom (synthetic) event in response to received events.

Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.

The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.

Name Type Description
targetNode Node

Specifies the DOM node on which the native event listeners should be registered.
synevent string

The name of the custom event to dispatch to the widget root DOM node.
events Array.<string>

The native DOM events for which event handlers should be registered.

inherited setChangeEvents(targetNode, events)

ui.js, line 224

Setup listeners for native DOM events that may change the widget value.

Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.

Name Type Description
targetNode Node

Specifies the DOM node on which the event listeners should be registered.
events string repeatable

The DOM events for which event handlers should be registered.

inherited setUpdateEvents(targetNode, events)

ui.js, line 181

Setup listeners for native DOM events that may update the widget value.

Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.

Name Type Description
targetNode Node

Specifies the DOM node on which the event listeners should be registered.
events string repeatable

The DOM events for which event handlers should be registered.

inherited triggerValidation()

ui.js, line 121

Force validation of the current input value.

Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.

Type Definitions

LuCI.ui.Combobox.InitOptionsLuCI.ui.Dropdown.InitOptions

Comboboxes support the same properties as Dropdown.InitOptions but enforce specific values for the following properties:

Properties:
Name Type Default Description
multiple boolean false

Since Comboboxes never allow selecting multiple values, this property is forcibly set to false.
create boolean true

Since Comboboxes always allow custom choice values, this property is forcibly set to true.
optional boolean true

Since Comboboxes are always optional, this property is forcibly set to true.