Class: Dropdown

Constructor

Instantiate a rich dropdown choice widget.

Parameters:

Name	Type	Attributes	Default	Description
`value`	string \| Array.<string>	<optional>	null	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.Dropdown.InitOptions	<optional>		Object describing the widget specific options to initialize the dropdown.

Source: ui.js, line 929

Extends

LuCI.ui.AbstractElement

Methods

addChoices(values, labels)

Add new choices to the dropdown menu.

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

Parameters:

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`.

Source: ui.js, line 1804

clearChoices(reset_valueopt)

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.

Parameters:

Name	Type	Attributes	Default	Description
`reset_value`	boolean	<optional>	false	If set to `true`, deselect and remove selected choices as well instead of keeping them.

Source: ui.js, line 1769

closeAllDropdowns()

Close all open dropdown widgets in the current document.

Source: ui.js, line 1837

getValidationError() → {string}

Returns the current validation error

Inherited From: LuCI.ui.AbstractElement#getValidationError
Source: ui.js, line 169

Returns:

The validation error at this time

Type:: string

getValue() → {string|Array.<string>|null}

Read the current value of the input widget.

Overrides: LuCI.ui.AbstractElement#getValue
Source: ui.js, line 2111

Returns:

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.

Type:: string | Array.<string> | null

isChanged() → {boolean}

Check whether the input value was altered by the user.

Inherited From: LuCI.ui.AbstractElement#isChanged
Source: ui.js, line 144

Returns:

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

Type:: boolean

isValid() → {boolean}

Check whether the current input value is valid.

Inherited From: LuCI.ui.AbstractElement#isValid
Source: ui.js, line 157

Returns:

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

Type:: boolean

registerEvents(targetNode, synevent, events)

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.

Parameters:

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 From: LuCI.ui.AbstractElement#registerEvents
Source: ui.js, line 219

render() → {Node}

Render the widget, set up event listeners and return resulting markup.

Overrides: LuCI.ui.AbstractElement#render
Source: ui.js, line 1086

Returns:

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

Type:: Node

setChangeEvents(targetNode, …events)

Set up 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.

Parameters:

Name	Type	Attributes	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 From: LuCI.ui.AbstractElement#setChangeEvents
Source: ui.js, line 288

setPlaceholder(value)

Set the current placeholder value of the input widget.

Parameters:

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 From: LuCI.ui.AbstractElement#setPlaceholder
Source: ui.js, line 116

setUpdateEvents(targetNode, …events)

Set up 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.

Parameters:

Name	Type	Attributes	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 From: LuCI.ui.AbstractElement#setUpdateEvents
Source: ui.js, line 244

setValue(value)

Set the current value of the input widget.

Parameters:

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.

Overrides: LuCI.ui.AbstractElement#setValue
Source: ui.js, line 2084

triggerValidation() → {boolean}

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.

Inherited From: LuCI.ui.AbstractElement#triggerValidation
Source: ui.js, line 184

Returns:

Type:: boolean

Type Definitions

InitOptions

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

Type:

LuCI.ui.AbstractElement.InitOptions

Properties

Name	Type	Attributes	Default	Description
`optional`	boolean	<optional>	true	Specifies whether the dropdown selection is optional. In contrast to other widgets, the `optional` constraint of dropdowns works differently; instead of marking the widget invalid on empty values when set to `false`, the user is not allowed to deselect all choices. For single value dropdowns that means that no empty "please select" choice is offered and for multi value dropdowns, the last selected choice may not be deselected without selecting another choice first.
`multiple`	boolean	<optional>		Specifies whether multiple choice values may be selected. It defaults to `true` when an array is passed as input value to the constructor.
`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.
`select_placeholder`	string	<optional>	-- Please choose --	Specifies a placeholder text which is displayed when no choice is selected yet.
`custom_placeholder`	string	<optional>	-- custom --	Specifies a placeholder text which is displayed in the text input field allowing to enter custom choice values. Only applicable if the `create` option is set to `true`.
`create`	boolean	<optional>	false	Specifies whether custom choices may be entered into the dropdown widget.
`create_query`	string	<optional>	.create-item-input	Specifies a CSS selector expression used to find the input element which is used to enter custom choice values. This should not normally be used except by widgets derived from the Dropdown class.
`create_template`	string	<optional>	"script[type='item-template']"	Specifies a CSS selector expression used to find an HTML element serving as template for newly added custom choice values. Any `{{value}}` placeholder string within the template elements text content will be replaced by the user supplied choice value, the resulting string is parsed as HTML and appended to the end of the choice list. The template markup may specify one HTML element with a `data-label-placeholder` attribute which is replaced by a matching label value from the `choices` object or with the user supplied value itself in case `choices` contains no matching choice label. If the template element is not found or if no `create_template` selector expression is specified, the default markup for newly created elements is `<li data-value="{{value}}"><span data-label-placeholder="true" /></li>`.
`create_markup`	string	<optional>		This property allows specifying the markup for custom choices directly instead of referring to a template element through CSS selectors. Apart from that it works exactly like `create_template`.
`display_items`	number	<optional>	3	Specifies the maximum amount of choice labels that should be shown in collapsed dropdown state before further selected choices are cut off. Only applicable when `multiple` is `true`.
`dropdown_items`	number	<optional>	-1	Specifies the maximum amount of choices that should be shown when the dropdown is open. If the amount of available choices exceeds this number, the dropdown area must be scrolled to reach further items. If set to `-1`, the dropdown menu will attempt to show all choice values and only resort to scrolling if the amount of choices exceeds the available screen space above and below the dropdown widget.
`placeholder`	string	<optional>		This property serves as a shortcut to set both `select_placeholder` and `custom_placeholder`. Either of these properties will fallback to `placeholder` if not specified.
`readonly`	boolean	<optional>	false	Specifies whether the custom choice input field should be rendered readonly. Only applicable when `create` is `true`.
`maxlength`	number	<optional>		Specifies the HTML `maxlength` attribute to set on the custom choice `<input>` element. Note that this a legacy property that exists for compatibility reasons. It is usually better to `maxlength(N)` validation expression. Only applicable when `create` is `true`.

Source: ui.js, line 962

Constructor

new Dropdown(valueopt, choices, optionsopt)

Extends

Methods

addChoices(values, labels)

clearChoices(reset_valueopt)

closeAllDropdowns()

getValidationError() → {string}

getValue() → {string|Array.<string>|null}

isChanged() → {boolean}

isValid() → {boolean}

registerEvents(targetNode, synevent, events)

render() → {Node}

setChangeEvents(targetNode, …events)

setPlaceholder(value)

setUpdateEvents(targetNode, …events)

setValue(value)

triggerValidation() → {boolean}

Type Definitions

InitOptions