Class: ButtonValue

Extends

• LuCI.form.Value

Members

inputstylestring

Override the button style class.

By setting this property, a specific cbi-button-* CSS class can be selected to influence the style of the resulting button.

Suitable values which are implemented by most themes are positive, negative and primary.

The default is null, means a neutral button styling is used.

Default Value:

• null

inputtitlestring function

Override the rendered button caption.

By default, the option title - which is passed as fourth argument to the constructor - is used as caption for the button element. When setting this property to a string, it is used as String.format() pattern with the underlying UCI section name passed as first format argument. When set to a function, it is invoked passing the section ID as sole argument and the resulting return value is converted to a string before being used as button caption.

The default is null, means the option title is used as caption.

Default Value:

• null

onclickfunction

Override the button click action.

By default, the underlying UCI option (or default property) value is copied into a hidden field tied to the button element and the save action is triggered on the parent form element.

When this property is set to a function, it is invoked instead of performing the default actions. The handler function will receive the DOM click element as first and the underlying configuration section ID as second argument.

Default Value:

• null

datatypestring

Specifies a datatype constraint expression to validate input values against. Refer to LuCI.validation for details on the format.

If the user entered input does not match the datatype validation, the option element is marked as invalid.

Default Value:

• null

default*

Sets a default value to use when the underlying UCI option is not set.

Default Value:

• null

editableboolean

Mark grid section option element as editable.

Options which are displayed in the table portion of a GridSection instance are rendered as readonly text by default. By setting the editable property of a child option element to true, that element is rendered as full input widget within its cell instead of a text only preview.

This property has no effect on options that are not children of grid section elements.

Default Value:

• false

modalonlyboolean

Move grid section option element into the table, the modal popup or both.

If this property is null (the default), the option element is displayed in both the table preview area and the per-section instance modal popup of a grid section. When it is set to false the option is only shown in the table but not the modal popup. When set to true, the option is only visible in the modal popup but not the table.

This property has no effect on options that are not children of grid section elements.

Default Value:

• null

onchangefunction

Register a custom value change handler.

If this property is set to a function value, the function is invoked whenever the value of the underlying UI input element is changing.

The invoked handler function will receive the DOM click element as first and the underlying configuration section ID as well as the input value as second and third argument respectively.

Default Value:

• null

optionalboolean

If set to true, the underlying ui input widget is allowed to be empty, otherwise the option element is marked invalid when no value is entered or selected by the user.

Default Value:

• false

passwordboolean

If set to true, the field is rendered as password input, otherwise as plain text input.

Default Value:

• false

placeholderstring

Set a placeholder string to use when the input field is empty.

Default Value:

• null

readonlyboolean

Make option element readonly.

This property defaults to the readonly state of the parent form element. When set to true, the underlying widget is rendered in disabled state, means its contents cannot be changed and the widget cannot be interacted with.

Default Value:

• false

rmemptyboolean

If set to false, the underlying option value is retained upon saving the form when the option element is disabled due to unsatisfied dependency constraints.

Default Value:

• true

uciconfigstring

Override the UCI configuration name to read the option value from.

By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified.

The default is null, means inheriting from the parent form.

Default Value:

• null

ucioptionstring

Override the UCI option name to read the value from.

By default, the elements name, which is passed as third argument to the constructor, is used as UCI option name. By setting this property, a deviating UCI option may be specified.

The default is null, means using the option element name.

Default Value:

• null

ucisectionstring

Override the UCI section name to read the option value from.

By default, the section ID is inherited from the parent section element. By setting this property, a deviating section may be specified.

The default is null, means inheriting from the parent section.

Default Value:

• null

validatefunction

Specifies a custom validation function to test the user input for validity. The validation function must return true to accept the value. Any other return value type is converted to a string and displayed to the user as validation error message.

If the user entered input does not pass the validation function, the option element is marked as invalid.

Default Value:

• null

widthnumber string

Override the cell width of a table or grid section child option.

If the property is set to a numeric value, it is treated as pixel width which is set on the containing cell element of the option, essentially forcing a certain column width. When the property is set to a string value, it is applied as-is to the CSS width property.

This property has no effect on options that are not children of grid or table section elements.

Default Value:

• null

Methods

inherited append(element)

form.js, line 210

Add another form element as children to this element.

Name	Type	Description
element	AbstractElement	The form element to add.

inherited cbid(section_id){string}

form.js, line 1733

Obtain the internal ID ("cbid") of the element instance.

Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
string	Returns the element ID.

inherited cfgvalue(section_id){*}

form.js, line 1807

Query the underlying configuration value.

The default implementation of this method returns the cached return value of load(). It may be overwritten by user code to obtain the configuration value in a different way.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
*	Returns the configuration value.

inherited depends(optionname_or_depends, optionvalue|RegExp)

form.js, line 1615

Add a dependency contraint to the option.

Dependency constraints allow making the presence of option elements dependant on the current values of certain other options within the same form. An option element with unsatisfied dependencies will be hidden from the view and its current value is omitted when saving.

Multiple constraints (that is, multiple calls to depends()) are treated as alternatives, forming a logical "or" expression.

By passing an object of name => value pairs as first argument, it is possible to depend on multiple options simultaneously, allowing to form a logical "and" expression.

Option names may be given in "dot notation" which allows to reference option elements outside of the current form section. If a name without dot is specified, it refers to an option within the same configuration section. If specified as configname.sectionid.optionname, options anywhere within the same form may be specified.

The object notation also allows for a number of special keys which are not treated as option names but as modifiers to influence the dependency constraint evaluation. The associated value of these special "tag" keys is ignored. The recognized tags are:

• !reverse
  Invert the dependency, instead of requiring another option to be equal to the dependency value, that option should not be equal.
• !contains
  Instead of requiring an exact match, the dependency is considered satisfied when the dependency value is contained within the option value.
• !default
  The dependency is always satisfied

Examples:

• opt.depends("foo", "test")
  Require the value of `foo` to be `test`.
• opt.depends({ foo: "test" })
  Equivalent to the previous example.
• opt.depends({ foo: /test/ })
  Require the value of `foo` to match the regular expression `/test/`.
• opt.depends({ foo: "test", bar: "qrx" })
  Require the value of `foo` to be `test` and the value of `bar` to be `qrx`.
• opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })
  Require either foo to be set to test, or the bar option to be qrx.
• opt.depends("test.section1.foo", "bar")
  Require the "foo" form option within the "section1" section to be set to "bar".
• opt.depends({ foo: "test", "!contains": true })
  Require the "foo" option value to contain the substring "test".

Name	Type	Description
optionname_or_depends	string | Object.<string, (string|RegExp)>	The name of the option to depend on or an object describing multiple dependencies which must be satified (a logical "and" expression).
optionvalue|RegExp	string	When invoked with a plain option name as first argument, this parameter specifies the expected value. In case an object is passed as first argument, this parameter is ignored.

inherited formvalue(section_id){*}

form.js, line 1835

Query the current form input value.

The default implementation of this method returns the current input value of the underlying LuCI.ui widget. It may be overwritten by user code to handle input values differently.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
*	Returns the current input value.

inherited getUIElement(section_id){LuCI.ui.AbstractElement|null}

form.js, line 1784

Obtain the underlying LuCI.ui element instance.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
LuCI.ui.AbstractElement | null	Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.

inherited isActive(section_id){boolean}

form.js, line 1923

Test whether the option element is currently active.

An element is active when it is not hidden due to unsatisfied dependency constraints.

Name	Type	Description
section_id	string	The configuration section ID

Returns:

Type	Description
boolean	Returns true if the option element currently is active, otherwise it returns false.

inherited isValid(section_id){boolean}

form.js, line 1905

Test whether the input value is currently valid.

Name	Type	Description
section_id	string	The configuration section ID

Returns:

Type	Description
boolean	Returns true if the input value currently is valid, otherwise it returns false.

inherited load(section_id){*|Promise.<*>}

form.js, line 1761

Load the underlying configuration value.

The default implementation of this method reads and returns the underlying UCI option value (or the related JavaScript property for JSONMap instances). It may be overwritten by user code to load data from nonstandard sources.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
* | Promise.<*>	Returns the configuration value to initialize the option element with. The return value of this function is filtered through Promise.resolve() so it may return promises if overridden by user code.

inherited parse(section_id){Promise.<void>}

form.js, line 1964

Parse the option element input.

The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.

Name	Type	Description
section_id	string	The configuration section ID

Returns:

Type	Description
Promise.<void>	Returns a promise resolving once the input value has been read and validated or rejecting in case the input value does not meet the validation constraints.

inherited remove(section_id)

form.js, line 2034

Remove the corresponding value from the configuration.

This function is invoked upon saving the parent form when the option element has been hidden due to unsatisfied dependencies or when the user cleared the input value and the option is marked optional.

The default implementation simply removes the associated option from the UCI configuration (or the associated JavaScript object property in case of JSONMap forms). It may be overwritten by user code to implement alternative removal logic, e.g. to retain the original value.

Name	Type	Description
section_id	string	The configuration section ID

inherited stripTags(input){string}

form.js, line 286

Strip any HTML tags from the given input string.

Name	Type	Description
input	string	The input string to clean.

Returns:

Type	Description
string	The cleaned input string with HTML removes removed.

inherited textvalue(section_id){string}

form.js, line 1859

Obtain a textual input representation.

The default implementation of this method returns the HTML escaped current input value of the underlying LuCI.ui widget. User code or specific option element implementations may overwrite this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Name	Type	Description
section_id	string	The configuration section ID

Throws:

Throws a TypeError exception when no section_id was specified.

Type

TypeError

Returns:

Type	Description
string	Returns the text representation of the current input value.

inherited titleFn(property, fmt_args){string|null}

form.js, line 320

Format the given named property as title string.

This function looks up the given named property and formats its value suitable for use as element caption or description string. It also strips any HTML tags from the result.

If the property value is a string, it is passed to String.format() along with any additional parameters passed to titleFn().

If the property value is a function, it is invoked with any additional titleFn() parameters as arguments and the obtained return value is converted to a string.

In all other cases, null is returned.

Name	Type	Description
property	string	The name of the element property to use.
fmt_args	*	repeatable Extra values to format the title string with.

Returns:

Type	Description
string | null	The formatted title string or null if the property did not exist or was neither a string nor a function.

inherited value(key, value)

form.js, line 3255

Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.

Name	Type	Description
key	string	The choice value to add.
value	Node | string	The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the key value is used as caption.

inherited write(section_id, formvalue)

form.js, line 2011

Write the current input value into the configuration.

This function is invoked upon saving the parent form when the option element is valid and when its input value has been changed compared to the initial value returned by cfgvalue().

The default implementation simply sets the given input value in the UCI configuration (or the associated JavaScript object property in case of JSONMap forms). It may be overwritten by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Name	Type	Description
section_id	string	The configuration section ID
formvalue	string | Array.<string>	The input value to write.