Class: Select

LuCI .ui. Select

The Select class implements either a traditional HTML <select> element or a group of checkboxes or radio buttons, depending on whether multiple values are enabled or not.

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.Select. To import it in external JavaScript, use L.require("ui").then(...) and access the Select property of the class instance value.

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

ui.js, line 614

Instantiate a select dropdown or checkbox/radiobutton group.

Name	Type	Default	Description
`value`	string \| Array.<string>	null	optional The initial input value(s).
`choices`	Object.<string, 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.Select.InitOptions		optional Object describing the widget specific options to initialize the inputs.

Extends

LuCI.ui.AbstractElement

Methods

inherited getValue(){string|Array.<string>|null} ui.js, line 787

Read the current value of the input widget.

Returns:

Type	Description
string \| Array.<string> \| null	The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as `DynamicList` instances may result in an array of strings or `null` for unset values.

inherited isValid(){boolean} ui.js, line 113

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 162

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 render(){Node} ui.js, line 705

Render the widget, setup event listeners and return resulting markup.

Returns:

Type	Description
Node	Returns a DOM Node or DocumentFragment containing the rendered widget markup.

inherited setChangeEvents(targetNode, events) ui.js, line 230

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 187

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 setValue(value) ui.js, line 800

Set the current value of the input widget.

Name	Type	Description
`value`	string \| Array.<string> \| null	The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as `DynamicList` instances may accept string array or `null` values.

inherited triggerValidation() ui.js, line 127

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.Select.InitOptionsLuCI.ui.AbstractElement.InitOptions

In addition to the AbstractElement.InitOptions the following properties are recognized:

Properties:

Name	Type	Argument	Default	Description
`multiple`	boolean	<optional>	false	Specifies whether multiple choice values may be selected.
`widget`	string	<optional>	select	Specifies the kind of widget to render. May be either `select` or `individual`. When set to `select` an HTML `<select>` element will be used, otherwise a group of checkbox or radio button elements is created, depending on the value of the `multiple` option.
`orientation`	string	<optional>	horizontal	Specifies whether checkbox / radio button groups should be rendered in a `horizontal` or `vertical` manner. Does not apply to the `select` widget type.
`sort`	boolean \| Array.<string>	<optional>	false	Specifies if and how to sort choice values. If set to `true`, the choice values will be sorted alphabetically. If set to an array of strings, the choice sort order is derived from the array.
`size`	number	<optional>		Specifies the HTML `size` attribute to set on the `<select>` element. Only applicable to the `select` widget type.
`placeholder`	string	<optional>	-- Please choose --	Specifies a placeholder text which is displayed when no choice is selected yet. Only applicable to the `select` widget type.