Class: HiddenValue

- - - - -

- - new LuCI.form.HiddenValue(form, section, option, title, description) -

- - -

- form.js, line 4039 -

- -

- - -

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

Name	Type	Description
`form`	- - -LuCI.form.Map -\| - -LuCI.form.JSONMap - - - -	- - - - - - - The configuration form this section is added to. It is automatically passed -by `option()` or -`taboption()` when adding the -option to the section.
`section`	- - -LuCI.form.AbstractSection - - - -	- - - - - - - The configuration section this option is added to. It is automatically passed -by `option()` or -`taboption()` when adding the -option to the section.
`option`	- - -string - - - -	- - - - - - - The name of the UCI option to map.
`title`	- - -string - - - -	- - - optional - - - - - - The title caption of the option element.
`description`	- - -string - - - -	- - - optional - - - - - - The description text of the option element.

- - - -

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

- - -

Extends

- -

LuCI.form.Value

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

Members

- -

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

- -

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.

- - - -

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

- - - - - - - -