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 653 -

- -

- - -

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 832 - - - - - -

- - -

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 - - isChanged(){boolean} - - - - - ui.js, line 141 - - - - - -

- - -

Check whether the input value was altered by the user.

- - - - - - - - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Returns:

- - - - - - - - - - - - - - - - - - - - -

Type	Description
- - boolean - - -	Returns `true` if the input value has been altered by the user or -`false` if it is unchaged. Note that if the user modifies the initial -value and changes it back to the original state, it is still reported -as changed.

- - - - -

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

- - -

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 203 - - - - - -

- - -

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 744 - - - - - -

- - -

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 271 - - - - - -

- - -

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

- - -

Set the current placeholder value of the input widget.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name	Type	Description
`value`	- - -string -\| - -Array.<string> -\| - -null - - - -	- - The placeholder to set for the input element. Only applicable to text -inputs, not to radio buttons, selects or similar.

- - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - inherited - - setUpdateEvents(targetNode, events) - - - - - ui.js, line 228 - - - - - -

- - -

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 845 - - - - - -

- - -

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 168 - - - - - -

- - -

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - - -

- -