diff --git a/jsapi/LuCI.dom.html b/jsapi/LuCI.dom.html index 69a5788965..97367efcf2 100644 --- a/jsapi/LuCI.dom.html +++ b/jsapi/LuCI.dom.html @@ -1,3 +1,3 @@ Class: dom
On this page

LuCI. dom

The dom class provides a convenience method for creating and manipulating DOM elements.

To import the class in views, use 'require dom', to import it in external JavaScript, use L.require("dom").then(...).

Source

Methods

append(node, childrenopt) → {Node|null}

Appends the given children data to the given node.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to append the children to.

children*<optional>

The children to append to the given node.

When children is an array, then each item of the array will be either appended as a child element or text node, depending on whether the item is a DOM Node instance or some other non-null value. Non-Node, non-null values will be converted to strings first before being passed as argument to createTextNode().

When children is a function, it will be invoked with the passed node argument as the sole parameter and the append function will be invoked again, with the given node argument as first and the return value of the children function as the second parameter.

When children is a DOM Node instance, it will be appended to the given node.

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.

Source
Returns:

Returns the last children Node appended to the node or null if either the node argument was no valid DOM node or if the children was null or didn't result in further DOM nodes.

Type: 
Node | null

attr(node, key, valopt) → {null}

Sets attributes or registers event listeners on element nodes.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to set the attributes or add the event listeners for. When the given node value is not a valid DOM Node, the function returns and does nothing.

keystring | Object.<string, *>

Specifies either the attribute or event handler name to use, or an object containing multiple key, value pairs which are each added to the node as either attribute or event handler, depending on the respective value.

val*<optional>

Specifies the attribute value or event handler function to add. If the key parameter is an Object, this parameter will be ignored.

When val is of type function, it will be registered as an event handler on the given node with the key parameter being the event name.

When val is of type object, it will be serialized as JSON and added as an attribute to the given node, using the given key as an attribute name.

When val is of any other type, it will be added as an attribute to the given node as-is, with the underlying setAttribute() call implicitly turning it into a string.

Source
Returns:
Type: 
null

bindClassInstance(node, inst) → {Class}

Binds the given class instance to the specified DOM Node.

This function uses the dom.data() facility to attach the passed instance of a Class to a node. This is needed for complex widget elements or similar where the corresponding class instance responsible for the element must be retrieved from DOM nodes obtained by querySelector() or similar means.

Parameters:
NameTypeDescription
nodeNode

The DOM Node instance to bind the class to.

instClass

The Class instance to bind to the node.

Source
Throws:

Throws a TypeError when the given instance argument isn't a valid Class instance.

Type
TypeError
Returns:

Returns the bound class instance.

Type: 
Class

callClassMethod(node, method, …args) → {*|null}

Finds a bound class instance on the given node itself or the first bound instance on its closest parent node and invokes the specified method name on the found class instance.

Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to start from.

methodstring

The name of the method to invoke on the found class instance.

args*<repeatable>

Additional arguments to pass to the invoked method as-is.

Source
Returns:

Returns the return value of the invoked method if a class instance and method has been found. Returns null if either no bound class instance could be found, or if the found instance didn't have the requested method.

Type: 
* | null

content(node, childrenopt) → {Node|null}

Replaces the content of the given node with the given children.

This function first removes any children of the given DOM Node and then adds the given children following the rules outlined below.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to replace the children of.

children*<optional>

The children to replace into the given node.

When children is an array, then each item of the array will be either appended as a child element or text node, depending on whether the item is a DOM Node instance or some other non-null value. Non-Node, non-null values will be converted to strings first before being passed as argument to createTextNode().

When children is a function, it will be invoked with the passed node argument as the sole parameter and the append function will be invoked again, with the given node argument as first and the return value of the children function as the second parameter.

When children is a DOM Node instance, it will be appended to the given node.

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.

Source
Returns:

Returns the last children Node appended to the node or null if either the node argument was no valid DOM node or if the children was null or didn't result in further DOM nodes.

Type: 
Node | null

create(html, attropt, dataopt) → {Node}

Creates a new DOM Node from the given html, attr and data parameters.

This function has multiple signatures, it can be either invoked in the form create(html[, attr[, data]]) or in the form create(html[, data]). The used variant is determined from the type of the second argument.

Parameters:
NameTypeAttributesDescription
htmlstring

Describes the node to create.

When the value of html is of type array, a DocumentFragment node is created and each item of the array is first converted to a DOM Node by passing it through create() and then added as a child to the fragment.

When the value of html is a DOM Node instance, no new element will be created, but the node will be used as-is.

When the value of html is a string starting with <, it will be passed to dom.parse() and the resulting value is used.

When the value of html is any other string, it will be passed to document.createElement() for creating a new DOM Node of the given name.

attrObject.<string, *><optional>

Specifies an Object of key, value pairs to set as attributes or event handlers on the created node. Refer to dom.attr() for details.

data*<optional>

Specifies children to append to the newly created element. Refer to dom.append() for details.

Source
Throws:

Throws an InvalidCharacterError when the given html argument contained malformed markup (such as not escaped & characters in XHTML mode) or when the given node name in html contains characters which are not legal in DOM element names, such as spaces.

Type
InvalidCharacterError
Returns:

Returns the newly created Node.

Type: 
Node

data(node, keyopt, valopt) → {*}

Attaches or detaches arbitrary data to and from a DOM Node.

This function is useful to attach non-string values or runtime data that is not serializable to DOM nodes. To decouple data from the DOM, values are not added directly to nodes, but inserted into a registry instead which is then referenced by a string key stored as data-idref attribute in the node.

This function has multiple signatures and is sensitive to the number of arguments passed to it.

  • dom.data(node) - Fetches all data associated with the given node.
  • dom.data(node, key) - Fetches a specific key associated with the given node.
  • dom.data(node, key, val) - Sets a specific key to the given value associated with the given node.
  • dom.data(node, null) - Clears any data associated with the node.
  • dom.data(node, key, null) - Clears the given key associated with the node.
Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to set or retrieve the data for.

keystring | null<optional>

This is either a string specifying the key to retrieve, or null to unset the entire node data.

val* | null<optional>

This is either a non-null value to set for a given key or null to remove the given key from the specified node.

Source
Returns:

Returns the get or set value, or null when no value could be found.

Type: 
*

elem(e) → {boolean}

Tests whether the given argument is a valid DOM Node.

Parameters:
NameTypeDescription
e*

The value to test.

Source
Returns:

Returns true if the value is a DOM Node, else false.

Type: 
boolean

findClassInstance(node) → {Class|null}

Finds a bound class instance on the given node itself or the first bound instance on its closest parent node.

Parameters:
NameTypeDescription
nodeNode

The DOM Node instance to start from.

Source
Returns:

Returns the founds class instance if any or null if no bound class could be found on the node itself or any of its parents.

Type: 
Class | null

isEmpty(node, ignoreFnopt) → {boolean}

Tests whether a given DOM Node instance is empty or appears empty.

Any element child nodes which have the CSS class hidden set or for which the optionally passed ignoreFn callback function returns false are ignored.

Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to test.

ignoreFnLuCI.dom.ignoreCallbackFn<optional>

Specifies an optional function which is invoked for each child node to decide whether the child node should be ignored or not.

Source
Returns:

Returns true if the node does not have any children or if any children node either has a hidden CSS class or a false result when testing it using the given ignoreFn.

Type: 
boolean

matches(node, selectoropt) → {boolean}

Tests whether a given Node matches the given query selector.

This function is a convenience wrapper around the standard Node.matches("selector") function with the added benefit that the node argument may be a non-Node value, in which case this function simply returns false.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to test the selector against.

selectorstring<optional>

The query selector expression to test against the given node.

Source
Returns:

Returns true if the given node matches the specified selector or false when the node argument is no valid DOM Node or the selector didn't match.

Type: 
boolean

parent(node, selectoropt) → {Node|null}

Returns the closest parent node that matches the given query selector expression.

This function is a convenience wrapper around the standard Node.closest("selector") function with the added benefit that the node argument may be a non-Node value, in which case this function simply returns null.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to find the closest parent for.

selectorstring<optional>

The query selector expression to test against each parent.

Source
Returns:

Returns the closest parent node matching the selector or null when the node argument is no valid DOM Node or the selector didn't match any parent.

Type: 
Node | null

parse(s) → {Node}

Parses a given string as HTML and returns the first child node.

Parameters:
NameTypeDescription
sstring

A string containing an HTML fragment to parse. Note that only the first result of the resulting structure is returned, so an input value of <div>foo</div> <div>bar</div> will only return the first div element node.

Source
Returns:

Returns the first DOM Node extracted from the HTML fragment or null on parsing failures or if no element could be found.

Type: 
Node

Type Definitions

ignoreCallbackFn(node) → {boolean}

The ignore callback function is invoked by isEmpty() for each child node to decide whether to ignore a child node or not.

When this function returns false, the node passed to it is ignored, else not.

Parameters:
NameTypeDescription
nodeNode

The child node to test.

Source
Returns:

Boolean indicating whether to ignore the node or not.

Type: 
boolean
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI. dom

The dom class provides a convenience method for creating and manipulating DOM elements.

To import the class in views, use 'require dom', to import it in external JavaScript, use L.require("dom").then(...).

Source

Methods

append(node, childrenopt) → {Node|null}

Appends the given children data to the given node.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to append the children to.

children*<optional>

The children to append to the given node.

When children is an array, then each item of the array will be either appended as a child element or text node, depending on whether the item is a DOM Node instance or some other non-null value. Non-Node, non-null values will be converted to strings first before being passed as argument to createTextNode().

When children is a function, it will be invoked with the passed node argument as the sole parameter and the append function will be invoked again, with the given node argument as first and the return value of the children function as the second parameter.

When children is a DOM Node instance, it will be appended to the given node.

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.

Source
Returns:

Returns the last children Node appended to the node or null if either the node argument was no valid DOM node or if the children was null or didn't result in further DOM nodes.

Type: 
Node | null

attr(node, key, valopt) → {null}

Sets attributes or registers event listeners on element nodes.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to set the attributes or add the event listeners for. When the given node value is not a valid DOM Node, the function returns and does nothing.

keystring | Object.<string, *>

Specifies either the attribute or event handler name to use, or an object containing multiple key, value pairs which are each added to the node as either attribute or event handler, depending on the respective value.

val*<optional>

Specifies the attribute value or event handler function to add. If the key parameter is an Object, this parameter will be ignored.

When val is of type function, it will be registered as an event handler on the given node with the key parameter being the event name.

When val is of type object, it will be serialized as JSON and added as an attribute to the given node, using the given key as an attribute name.

When val is of any other type, it will be added as an attribute to the given node as-is, with the underlying setAttribute() call implicitly turning it into a string.

Source
Returns:
Type: 
null

bindClassInstance(node, inst) → {Class}

Binds the given class instance to the specified DOM Node.

This function uses the dom.data() facility to attach the passed instance of a Class to a node. This is needed for complex widget elements or similar where the corresponding class instance responsible for the element must be retrieved from DOM nodes obtained by querySelector() or similar means.

Parameters:
NameTypeDescription
nodeNode

The DOM Node instance to bind the class to.

instClass

The Class instance to bind to the node.

Source
Throws:

Throws a TypeError when the given instance argument isn't a valid Class instance.

Type
TypeError
Returns:

Returns the bound class instance.

Type: 
Class

callClassMethod(node, method, …args) → {*|null}

Finds a bound class instance on the given node itself or the first bound instance on its closest parent node and invokes the specified method name on the found class instance.

Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to start from.

methodstring

The name of the method to invoke on the found class instance.

args*<repeatable>

Additional arguments to pass to the invoked method as-is.

Source
Returns:

Returns the return value of the invoked method if a class instance and method has been found. Returns null if either no bound class instance could be found, or if the found instance didn't have the requested method.

Type: 
* | null

content(node, childrenopt) → {Node|null}

Replaces the content of the given node with the given children.

This function first removes any children of the given DOM Node and then adds the given children following the rules outlined below.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to replace the children of.

children*<optional>

The children to replace into the given node.

When children is an array, then each item of the array will be either appended as a child element or text node, depending on whether the item is a DOM Node instance or some other non-null value. Non-Node, non-null values will be converted to strings first before being passed as argument to createTextNode().

When children is a function, it will be invoked with the passed node argument as the sole parameter and the append function will be invoked again, with the given node argument as first and the return value of the children function as the second parameter.

When children is a DOM Node instance, it will be appended to the given node.

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.

Source
Returns:

Returns the last children Node appended to the node or null if either the node argument was no valid DOM node or if the children was null or didn't result in further DOM nodes.

Type: 
Node | null

create(html, attropt, dataopt) → {Node}

Creates a new DOM Node from the given html, attr and data parameters.

This function has multiple signatures, it can be either invoked in the form create(html[, attr[, data]]) or in the form create(html[, data]). The used variant is determined from the type of the second argument.

Parameters:
NameTypeAttributesDescription
htmlstring

Describes the node to create.

When the value of html is of type array, a DocumentFragment node is created and each item of the array is first converted to a DOM Node by passing it through create() and then added as a child to the fragment.

When the value of html is a DOM Node instance, no new element will be created, but the node will be used as-is.

When the value of html is a string starting with <, it will be passed to dom.parse() and the resulting value is used.

When the value of html is any other string, it will be passed to document.createElement() for creating a new DOM Node of the given name.

attrObject.<string, *><optional>

Specifies an Object of key, value pairs to set as attributes or event handlers on the created node. Refer to dom.attr() for details.

data*<optional>

Specifies children to append to the newly created element. Refer to dom.append() for details.

Source
Throws:

Throws an InvalidCharacterError when the given html argument contained malformed markup (such as not escaped & characters in XHTML mode) or when the given node name in html contains characters which are not legal in DOM element names, such as spaces.

Type
InvalidCharacterError
Returns:

Returns the newly created Node.

Type: 
Node

data(node, keyopt, valopt) → {*}

Attaches or detaches arbitrary data to and from a DOM Node.

This function is useful to attach non-string values or runtime data that is not serializable to DOM nodes. To decouple data from the DOM, values are not added directly to nodes, but inserted into a registry instead which is then referenced by a string key stored as data-idref attribute in the node.

This function has multiple signatures and is sensitive to the number of arguments passed to it.

  • dom.data(node) - Fetches all data associated with the given node.
  • dom.data(node, key) - Fetches a specific key associated with the given node.
  • dom.data(node, key, val) - Sets a specific key to the given value associated with the given node.
  • dom.data(node, null) - Clears any data associated with the node.
  • dom.data(node, key, null) - Clears the given key associated with the node.
Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to set or retrieve the data for.

keystring | null<optional>

This is either a string specifying the key to retrieve, or null to unset the entire node data.

val* | null<optional>

This is either a non-null value to set for a given key or null to remove the given key from the specified node.

Source
Returns:

Returns the get or set value, or null when no value could be found.

Type: 
*

elem(e) → {boolean}

Tests whether the given argument is a valid DOM Node.

Parameters:
NameTypeDescription
e*

The value to test.

Source
Returns:

Returns true if the value is a DOM Node, else false.

Type: 
boolean

findClassInstance(node) → {Class|null}

Finds a bound class instance on the given node itself or the first bound instance on its closest parent node.

Parameters:
NameTypeDescription
nodeNode

The DOM Node instance to start from.

Source
Returns:

Returns the founds class instance if any or null if no bound class could be found on the node itself or any of its parents.

Type: 
Class | null

isEmpty(node, ignoreFnopt) → {boolean}

Tests whether a given DOM Node instance is empty or appears empty.

Any element child nodes which have the CSS class hidden set or for which the optionally passed ignoreFn callback function returns false are ignored.

Parameters:
NameTypeAttributesDescription
nodeNode

The DOM Node instance to test.

ignoreFnLuCI.dom.ignoreCallbackFn<optional>

Specifies an optional function which is invoked for each child node to decide whether the child node should be ignored or not.

Source
Returns:

Returns true if the node does not have any children or if any children node either has a hidden CSS class or a false result when testing it using the given ignoreFn.

Type: 
boolean

matches(node, selectoropt) → {boolean}

Tests whether a given Node matches the given query selector.

This function is a convenience wrapper around the standard Node.matches("selector") function with the added benefit that the node argument may be a non-Node value, in which case this function simply returns false.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to test the selector against.

selectorstring<optional>

The query selector expression to test against the given node.

Source
Returns:

Returns true if the given node matches the specified selector or false when the node argument is no valid DOM Node or the selector didn't match.

Type: 
boolean

parent(node, selectoropt) → {Node|null}

Returns the closest parent node that matches the given query selector expression.

This function is a convenience wrapper around the standard Node.closest("selector") function with the added benefit that the node argument may be a non-Node value, in which case this function simply returns null.

Parameters:
NameTypeAttributesDescription
node*

The Node argument to find the closest parent for.

selectorstring<optional>

The query selector expression to test against each parent.

Source
Returns:

Returns the closest parent node matching the selector or null when the node argument is no valid DOM Node or the selector didn't match any parent.

Type: 
Node | null

parse(s) → {Node}

Parses a given string as HTML and returns the first child node.

Parameters:
NameTypeDescription
sstring

A string containing an HTML fragment to parse. Note that only the first result of the resulting structure is returned, so an input value of <div>foo</div> <div>bar</div> will only return the first div element node.

Source
Returns:

Returns the first DOM Node extracted from the HTML fragment or null on parsing failures or if no element could be found.

Type: 
Node

Type Definitions

ignoreCallbackFn(node) → {boolean}

The ignore callback function is invoked by isEmpty() for each child node to decide whether to ignore a child node or not.

When this function returns false, the node passed to it is ignored, else not.

Parameters:
NameTypeDescription
nodeNode

The child node to test.

Source
Returns:

Boolean indicating whether to ignore the node or not.

Type: 
boolean
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.AbstractSection.html b/jsapi/LuCI.form.AbstractSection.html index 3b6e7669e6..57d8dbba66 100644 --- a/jsapi/LuCI.form.AbstractSection.html +++ b/jsapi/LuCI.form.AbstractSection.html @@ -1,3 +1,3 @@ Class: AbstractSection
On this page

LuCI.form. AbstractSection

The AbstractSection class serves as an abstract base for the different form section styles implemented by LuCI.form. It provides the common logic for enumerating underlying configuration section instances, for registering form options and for handling tabs in order to segment child options.

This class is private and not directly accessible by user code.

Source

Extends

Members

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

(abstract) cfgsections() → {Array.<string>}

Enumerate the UCI section IDs covered by this form section element.

Source
Throws:

Throws an InternalError exception if the function is not implemented.

Type
InternalError
Returns:

Returns an array of UCI section IDs covered by this form element. The sections will be rendered in the same order as the returned array.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Overrides
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

(abstract) render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Inherited From
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. AbstractSection

The AbstractSection class serves as an abstract base for the different form section styles implemented by LuCI.form. It provides the common logic for enumerating underlying configuration section instances, for registering form options and for handling tabs in order to segment child options.

This class is private and not directly accessible by user code.

Source

Extends

Members

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

(abstract) cfgsections() → {Array.<string>}

Enumerate the UCI section IDs covered by this form section element.

Source
Throws:

Throws an InternalError exception if the function is not implemented.

Type
InternalError
Returns:

Returns an array of UCI section IDs covered by this form element. The sections will be rendered in the same order as the returned array.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Overrides
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

(abstract) render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Inherited From
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.AbstractValue.html b/jsapi/LuCI.form.AbstractValue.html index 663ed0ddaa..a8c18d1a09 100644 --- a/jsapi/LuCI.form.AbstractValue.html +++ b/jsapi/LuCI.form.AbstractValue.html @@ -1,3 +1,3 @@ Class: AbstractValue
On this page

LuCI.form. AbstractValue

The AbstractValue class serves as an abstract base for the different form option styles implemented by LuCI.form. It provides the common logic for handling option input values, for dependencies among options and for validation constraints that should be applied to entered values.

This class is private and not directly accessible by user code.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Default Value
  • null
Source

default :*

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

Type:
  • *
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Default Value
  • false
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source

(abstract) render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Inherited From
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

(abstract) validate(section_id, value) → {*}

Apply custom validation logic.

This method is invoked whenever incremental validation is performed on the user input, e.g. on keyup or blur events.

The default implementation of this method does nothing and always returns true. User code may override this method to provide additional validation logic which is not covered by data type constraints.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

value*

The value to validate

Source
Returns:

The method shall return true to accept the given value. Any other return value is treated as a failure, converted to a string and displayed as an error message to the user.

Type: 
*

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. AbstractValue

The AbstractValue class serves as an abstract base for the different form option styles implemented by LuCI.form. It provides the common logic for handling option input values, for dependencies among options and for validation constraints that should be applied to entered values.

This class is private and not directly accessible by user code.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Default Value
  • null
Source

default :*

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

Type:
  • *
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Default Value
  • false
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source

(abstract) render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Inherited From
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

(abstract) validate(section_id, value) → {*}

Apply custom validation logic.

This method is invoked whenever incremental validation is performed on the user input, e.g. on keyup or blur events.

The default implementation of this method does nothing and always returns true. User code may override this method to provide additional validation logic which is not covered by data type constraints.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

value*

The value to validate

Source
Returns:

The method shall return true to accept the given value. Any other return value is treated as a failure, converted to a string and displayed as an error message to the user.

Type: 
*

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.Button.html b/jsapi/LuCI.form.Button.html index d2967a4256..99aa6d23c7 100644 --- a/jsapi/LuCI.form.Button.html +++ b/jsapi/LuCI.form.Button.html @@ -1,3 +1,3 @@ Class: Button
On this page

LuCI.form. Button

The Button element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

inputstyle :string

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 of null means a neutral button styling is used.

Type:
  • string
Default Value
  • null
Source

inputtitle :string|function

Override the rendered button caption.

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

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

Type:
  • string | function
Default Value
  • null
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

onclick :function

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 the first and the underlying configuration section ID as the second argument.

Type:
  • function
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. Button

The Button element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

inputstyle :string

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 of null means a neutral button styling is used.

Type:
  • string
Default Value
  • null
Source

inputtitle :string|function

Override the rendered button caption.

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

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

Type:
  • string | function
Default Value
  • null
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

onclick :function

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 the first and the underlying configuration section ID as the second argument.

Type:
  • function
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.DirectoryPicker.html b/jsapi/LuCI.form.DirectoryPicker.html index e11f27fab2..63006d0454 100644 --- a/jsapi/LuCI.form.DirectoryPicker.html +++ b/jsapi/LuCI.form.DirectoryPicker.html @@ -1,3 +1,3 @@ Class: DirectoryPicker
On this page

LuCI.form. DirectoryPicker

The DirectoryPicker element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, create, delete and select remote directories.

Source

Extends

Members

browser :boolean

Render the widget in browser mode initially instead of a button to 'Select Directory...'.

Type:
  • boolean
Default Value
  • false
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

directory_create :boolean

Toggle remote directory create functionality.

When set to true, the underlying widget provides a button which lets the user create directories. Note that this is merely a cosmetic feature: remote create permissions are controlled by the session ACL rules.

The default of false means the directory create button is hidden.

Type:
  • boolean
Default Value
  • false
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enable_download :boolean

Toggle download file functionality.

Type:
  • boolean
Default Value
  • false
Source

enable_remove :boolean

Toggle remote file delete functionality.

When set to true, the underlying widget provides buttons which let the user delete files from remote directories. Note that this is merely a cosmetic feature: remote delete permissions are controlled by the session ACL rules.

The default is false, means file removal buttons are not displayed.

Type:
  • boolean
Default Value
  • false
Source

enable_upload :boolean

Toggle file upload functionality.

When set to true, the underlying widget provides a button which lets the user select and upload local files to the remote system. Note that this is merely a cosmetic feature: remote upload access is controlled by the session ACL rules.

The default of false means file upload functionality is disabled.

Type:
  • boolean
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

root_directory :string

Specify the root directory for file browsing.

This property defines the topmost directory the file browser widget may navigate to. The UI will not allow browsing directories outside this prefix. Note that this is merely a cosmetic feature: remote file access and directory listing permissions are controlled by the session ACL rules.

The default is /tmp.

Type:
  • string
Default Value
  • /tmp
Source

show_hidden :boolean

Toggle display of hidden files.

Display hidden files when rendering the remote directory listing. Note that this is merely a cosmetic feature: hidden files are always included in received remote file listings.

The default of true means hidden files are displayed.

Type:
  • boolean
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. DirectoryPicker

The DirectoryPicker element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, create, delete and select remote directories.

Source

Extends

Members

browser :boolean

Render the widget in browser mode initially instead of a button to 'Select Directory...'.

Type:
  • boolean
Default Value
  • false
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

directory_create :boolean

Toggle remote directory create functionality.

When set to true, the underlying widget provides a button which lets the user create directories. Note that this is merely a cosmetic feature: remote create permissions are controlled by the session ACL rules.

The default of false means the directory create button is hidden.

Type:
  • boolean
Default Value
  • false
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enable_download :boolean

Toggle download file functionality.

Type:
  • boolean
Default Value
  • false
Source

enable_remove :boolean

Toggle remote file delete functionality.

When set to true, the underlying widget provides buttons which let the user delete files from remote directories. Note that this is merely a cosmetic feature: remote delete permissions are controlled by the session ACL rules.

The default is false, means file removal buttons are not displayed.

Type:
  • boolean
Default Value
  • false
Source

enable_upload :boolean

Toggle file upload functionality.

When set to true, the underlying widget provides a button which lets the user select and upload local files to the remote system. Note that this is merely a cosmetic feature: remote upload access is controlled by the session ACL rules.

The default of false means file upload functionality is disabled.

Type:
  • boolean
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

root_directory :string

Specify the root directory for file browsing.

This property defines the topmost directory the file browser widget may navigate to. The UI will not allow browsing directories outside this prefix. Note that this is merely a cosmetic feature: remote file access and directory listing permissions are controlled by the session ACL rules.

The default is /tmp.

Type:
  • string
Default Value
  • /tmp
Source

show_hidden :boolean

Toggle display of hidden files.

Display hidden files when rendering the remote directory listing. Note that this is merely a cosmetic feature: hidden files are always included in received remote file listings.

The default of true means hidden files are displayed.

Type:
  • boolean
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.DummyValue.html b/jsapi/LuCI.form.DummyValue.html index f07641aff6..e90f0b1118 100644 --- a/jsapi/LuCI.form.DummyValue.html +++ b/jsapi/LuCI.form.DummyValue.html @@ -1,3 +1,3 @@ Class: DummyValue
On this page

LuCI.form. DummyValue

The DummyValue element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

hidden :boolean

Render the UCI option value as hidden using the HTML 'display: none' style property.

By default, the value is displayed.

Type:
  • boolean
Default Value
  • null
Source

href :string

Set a URL which is opened when clicking on the dummy value text.

By setting this property, the dummy value text is wrapped in an <a> element with the property value used as href attribute.

Type:
  • string
Default Value
  • null
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

rawhtml :boolean

Treat the UCI option value (or the default property value) as HTML.

By default, the value text is HTML escaped before being rendered as text. In some cases, HTML content may need to be interpreted and rendered as-is. When set to true, HTML escaping is disabled.

Type:
  • boolean
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Overrides
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. DummyValue

The DummyValue element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

hidden :boolean

Render the UCI option value as hidden using the HTML 'display: none' style property.

By default, the value is displayed.

Type:
  • boolean
Default Value
  • null
Source

href :string

Set a URL which is opened when clicking on the dummy value text.

By setting this property, the dummy value text is wrapped in an <a> element with the property value used as href attribute.

Type:
  • string
Default Value
  • null
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

rawhtml :boolean

Treat the UCI option value (or the default property value) as HTML.

By default, the value text is HTML escaped before being rendered as text. In some cases, HTML content may need to be interpreted and rendered as-is. When set to true, HTML escaping is disabled.

Type:
  • boolean
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Overrides
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.DynamicList.html b/jsapi/LuCI.form.DynamicList.html index 99b222634e..30eccdbd60 100644 --- a/jsapi/LuCI.form.DynamicList.html +++ b/jsapi/LuCI.form.DynamicList.html @@ -1,3 +1,3 @@ Class: DynamicList
On this page

LuCI.form. DynamicList

The DynamicList class represents a multi-value widget allowing the user to enter multiple unique values, optionally selected from a set of predefined choices. It builds upon the LuCI.ui.DynamicList widget.

Source

Extends

Members

allowduplicates :boolean

Allows the underlying form controls to have multiple identical values.

Default is null. If true, the underlying form value will not be checked for duplication.

Type:
  • boolean
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. DynamicList

The DynamicList class represents a multi-value widget allowing the user to enter multiple unique values, optionally selected from a set of predefined choices. It builds upon the LuCI.ui.DynamicList widget.

Source

Extends

Members

allowduplicates :boolean

Allows the underlying form controls to have multiple identical values.

Default is null. If true, the underlying form value will not be checked for duplication.

Type:
  • boolean
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.FileUpload.html b/jsapi/LuCI.form.FileUpload.html index e0e6376b75..ad07200bd0 100644 --- a/jsapi/LuCI.form.FileUpload.html +++ b/jsapi/LuCI.form.FileUpload.html @@ -1,3 +1,3 @@ Class: FileUpload
On this page

LuCI.form. FileUpload

The FileUpload element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, upload and select remote files.

Source

Extends

Members

browser :boolean

Render the widget in browser mode initially instead of a button to 'Select File...'.

Type:
  • boolean
Default Value
  • false
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

directory_create :boolean

Toggle remote directory create functionality.

When set to true, the underlying widget provides a button which lets the user create directories. Note that this is merely a cosmetic feature: remote create permissions are controlled by the session ACL rules.

The default of false means the directory create button is hidden.

Type:
  • boolean
Default Value
  • false
Source

directory_select :boolean

Toggle remote directory select functionality.

When set to true, the underlying widget changes behaviour to select directories instead of files, in effect, becoming a directory picker.

The default is false.

Type:
  • boolean
Default Value
  • false
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enable_download :boolean

Toggle download file functionality.

Type:
  • boolean
Default Value
  • false
Source

enable_remove :boolean

Toggle remote file delete functionality.

When set to true, the underlying widget provides buttons which let the user delete files from remote directories. Note that this is merely a cosmetic feature: remote delete permissions are controlled by the session ACL rules.

The default is true, means file removal buttons are displayed.

Type:
  • boolean
Default Value
  • true
Source

enable_upload :boolean

Toggle file upload functionality.

When set to true, the underlying widget provides a button which lets the user select and upload local files to the remote system. Note that this is merely a cosmetic feature: remote upload access is controlled by the session ACL rules.

The default of true means file upload functionality is displayed.

Type:
  • boolean
Default Value
  • true
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

root_directory :string

Specify the root directory for file browsing.

This property defines the topmost directory the file browser widget may navigate to. The UI will not allow browsing directories outside this prefix. Note that this is merely a cosmetic feature: remote file access and directory listing permissions are controlled by the session ACL rules.

The default is /etc/luci-uploads.

Type:
  • string
Default Value
  • /etc/luci-uploads
Source

show_hidden :boolean

Toggle display of hidden files.

Display hidden files when rendering the remote directory listing. Note that this is merely a cosmetic feature: hidden files are always included in received remote file listings.

The default of false means hidden files are not displayed.

Type:
  • boolean
Default Value
  • false
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. FileUpload

The FileUpload element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, upload and select remote files.

Source

Extends

Members

browser :boolean

Render the widget in browser mode initially instead of a button to 'Select File...'.

Type:
  • boolean
Default Value
  • false
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

directory_create :boolean

Toggle remote directory create functionality.

When set to true, the underlying widget provides a button which lets the user create directories. Note that this is merely a cosmetic feature: remote create permissions are controlled by the session ACL rules.

The default of false means the directory create button is hidden.

Type:
  • boolean
Default Value
  • false
Source

directory_select :boolean

Toggle remote directory select functionality.

When set to true, the underlying widget changes behaviour to select directories instead of files, in effect, becoming a directory picker.

The default is false.

Type:
  • boolean
Default Value
  • false
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enable_download :boolean

Toggle download file functionality.

Type:
  • boolean
Default Value
  • false
Source

enable_remove :boolean

Toggle remote file delete functionality.

When set to true, the underlying widget provides buttons which let the user delete files from remote directories. Note that this is merely a cosmetic feature: remote delete permissions are controlled by the session ACL rules.

The default is true, means file removal buttons are displayed.

Type:
  • boolean
Default Value
  • true
Source

enable_upload :boolean

Toggle file upload functionality.

When set to true, the underlying widget provides a button which lets the user select and upload local files to the remote system. Note that this is merely a cosmetic feature: remote upload access is controlled by the session ACL rules.

The default of true means file upload functionality is displayed.

Type:
  • boolean
Default Value
  • true
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

root_directory :string

Specify the root directory for file browsing.

This property defines the topmost directory the file browser widget may navigate to. The UI will not allow browsing directories outside this prefix. Note that this is merely a cosmetic feature: remote file access and directory listing permissions are controlled by the session ACL rules.

The default is /etc/luci-uploads.

Type:
  • string
Default Value
  • /etc/luci-uploads
Source

show_hidden :boolean

Toggle display of hidden files.

Display hidden files when rendering the remote directory listing. Note that this is merely a cosmetic feature: hidden files are always included in received remote file listings.

The default of false means hidden files are not displayed.

Type:
  • boolean
Default Value
  • false
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.Flag.html b/jsapi/LuCI.form.Flag.html index 243c7fe5bf..84c8456ca7 100644 --- a/jsapi/LuCI.form.Flag.html +++ b/jsapi/LuCI.form.Flag.html @@ -1,3 +1,3 @@ Class: Flag
On this page

LuCI.form. Flag

The Flag element builds upon the LuCI.ui.Checkbox widget to implement a simple checkbox element.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

disabled :string

Sets the input value to use for the checkbox unchecked state.

Type:
  • string
Default Value
  • 0
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enabled :string

Sets the input value to use for the checkbox checked state.

Type:
  • string
Default Value
  • 1
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

tooltip :string|function

Set a tooltip for the flag option.

Set to a string, it will be used as-is as a tooltip.

Set to a function, the function will be invoked and the return value will be shown as a tooltip. If the return value of the function is null no tooltip will be set.

Type:
  • string | function
Default Value
  • null
Source

tooltipicon :string

Set a tooltip icon for the flag option.

If set, this icon will be shown for the default one. This could also be a png icon from the resources directory.

Type:
  • string
Default Value
  • 'ℹ️';
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

Query the checked state of the underlying checkbox widget and return either the enabled or the disabled property value, depending on the checked state.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

Query the checked state of the underlying checkbox widget and return either a localized Yes or No string, depending on the checked state.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. Flag

The Flag element builds upon the LuCI.ui.Checkbox widget to implement a simple checkbox element.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

disabled :string

Sets the input value to use for the checkbox unchecked state.

Type:
  • string
Default Value
  • 0
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

enabled :string

Sets the input value to use for the checkbox checked state.

Type:
  • string
Default Value
  • 1
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

tooltip :string|function

Set a tooltip for the flag option.

Set to a string, it will be used as-is as a tooltip.

Set to a function, the function will be invoked and the return value will be shown as a tooltip. If the return value of the function is null no tooltip will be set.

Type:
  • string | function
Default Value
  • null
Source

tooltipicon :string

Set a tooltip icon for the flag option.

If set, this icon will be shown for the default one. This could also be a png icon from the resources directory.

Type:
  • string
Default Value
  • 'ℹ️';
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

Query the checked state of the underlying checkbox widget and return either the enabled or the disabled property value, depending on the checked state.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

Query the checked state of the underlying checkbox widget and return either a localized Yes or No string, depending on the checked state.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.GridSection.html b/jsapi/LuCI.form.GridSection.html index 089ed3a3fa..c8449b52c4 100644 --- a/jsapi/LuCI.form.GridSection.html +++ b/jsapi/LuCI.form.GridSection.html @@ -1,3 +1,3 @@ Class: GridSection
On this page

LuCI.form. GridSection

The GridSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

A grid section functions similar to a LuCI.form.TableSection but supports tabbing in the modal overlay. Option elements added with option() are shown in the table while elements added with taboption() are displayed in the modal popup.

Another important difference is that the table cells show a readonly text preview of the corresponding option elements by default, unless the child option element is explicitly made writeable by setting the editable property to true.

Additionally, the grid section honours a modalonly property of child option elements. Refer to the AbstractValue documentation for details.

Layout wise, a grid section looks mostly identical to table sections.

Source

Extends

Members

actionstitle :string|function

Set a custom text for the actions column header row when actions buttons are present.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

cloneable :boolean

Set to true, a clone button is added to the button column, allowing the user to clone section instances mapped by the section form element. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

clonebtntitle :string|function

Override the caption used for the section clone button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Clone.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

extedit :string|function

Enables a per-section instance row Edit button which triggers a certain action when clicked. Set to a string, the string value is used as a String.format() pattern with the name of the underlying UCI section as the first format argument. The result is then interpreted as a URL which LuCI will navigate to when the user clicks the edit button.

If set to a function, this function will be registered as a click event handler on the rendered edit button, receiving the section instance name as the first and the DOM click event as the second argument.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

filterrow :boolean

Optional table filtering for table sections.

Set filterrow to true to display a filter header row in the generated table with per-column text fields to search for string matches in the column. The filter row appears after the titles row.

The filters work cumulatively: text in each field shall match an entry for the row to be displayed. The results are filtered live. Matching is case-sensitive, and partial, i.e. part or all of the result includes the search string.

The filter fields assume the placeholder text Filter suffixed with the column name, to ease correlation of filter fields to their corresponding column entries on narrow displays which might fold the columns over multiple lines.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

Optional footer row for table sections.

Set footer to one of:

  • a function that returns a table row (tr) or node E('...')
  • an array of string cell contents (first entry maps to the name column if present).

This is useful for providing sum totals, extra function buttons or extra space.

The default implementation returns an empty node.

Type:
  • Array.<string> | function
Inherited From
Default Value
  • `E([])`
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max_cols :number

Specify a maximum amount of columns to display. By default, one table column is rendered for each child option of the form section element. When this option is set to a positive number, then no more columns than the given amount are rendered. When the number of child options exceeds the specified amount, a More… button is rendered in the last column, opening a modal dialog presenting all options elements in NamedSection style when clicked.

Type:
  • number
Inherited From
Default Value
  • null
Source

modaltitle :string|function

Override the per-section instance modal popup title caption shown when clicking the More… button in a section specifying max_cols. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument, and its return value is used as a caption after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

nodescriptions :boolean

Set to true, the header row with the descriptions of options will not be displayed. By default, the row of descriptions is automatically displayed when at least one option has a description.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

rowcolors :boolean

Set to true, alternating cbi-rowstyle-1 and cbi-rowstyle-2 CSS classes are added to the table row elements. Not all LuCI themes implement these row style classes. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

sectiontitle :string|function

Override the per-section instance title caption shown in the first column of the table unless anonymous is set to true. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument and its return value used as a caption, after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

sortable :boolean

Set to true, a sort button is added to the last column, allowing the user to reorder the section instances mapped by the section form element.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

Methods

(abstract) addModalOptions(modalSection, section_id, ev) → {*|Promise.<*>}

Add further options to the per-section instanced modal popup.

This function may be overridden by user code to perform additional setup steps before displaying the more options modal which is useful to e.g. query additional data or to inject further option elements.

The default implementation of this function does nothing.

Parameters:
NameTypeDescription
modalSectionLuCI.form.NamedSection

The NamedSection instance about to be rendered in the modal popup.

section_idstring

The ID of the underlying UCI section the modal popup belongs to.

evEvent

The DOM event emitted by clicking the More… button.

Inherited From
Source
Returns:

Return values of this function are ignored but if a promise is returned, it is run to completion before the rendering is continued, allowing custom logic to perform asynchronous work before the modal dialog is shown.

Type: 
* | Promise.<*>

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Overrides
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The modal option elements of a grid section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that tabs are only effective in modal popups. Options added with option() will not be assigned to a specific tab and are rendered in the table view only.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Overrides
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. GridSection

The GridSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

A grid section functions similar to a LuCI.form.TableSection but supports tabbing in the modal overlay. Option elements added with option() are shown in the table while elements added with taboption() are displayed in the modal popup.

Another important difference is that the table cells show a readonly text preview of the corresponding option elements by default, unless the child option element is explicitly made writeable by setting the editable property to true.

Additionally, the grid section honours a modalonly property of child option elements. Refer to the AbstractValue documentation for details.

Layout wise, a grid section looks mostly identical to table sections.

Source

Extends

Members

actionstitle :string|function

Set a custom text for the actions column header row when actions buttons are present.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

cloneable :boolean

Set to true, a clone button is added to the button column, allowing the user to clone section instances mapped by the section form element. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

clonebtntitle :string|function

Override the caption used for the section clone button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Clone.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

extedit :string|function

Enables a per-section instance row Edit button which triggers a certain action when clicked. Set to a string, the string value is used as a String.format() pattern with the name of the underlying UCI section as the first format argument. The result is then interpreted as a URL which LuCI will navigate to when the user clicks the edit button.

If set to a function, this function will be registered as a click event handler on the rendered edit button, receiving the section instance name as the first and the DOM click event as the second argument.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

filterrow :boolean

Optional table filtering for table sections.

Set filterrow to true to display a filter header row in the generated table with per-column text fields to search for string matches in the column. The filter row appears after the titles row.

The filters work cumulatively: text in each field shall match an entry for the row to be displayed. The results are filtered live. Matching is case-sensitive, and partial, i.e. part or all of the result includes the search string.

The filter fields assume the placeholder text Filter suffixed with the column name, to ease correlation of filter fields to their corresponding column entries on narrow displays which might fold the columns over multiple lines.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

Optional footer row for table sections.

Set footer to one of:

  • a function that returns a table row (tr) or node E('...')
  • an array of string cell contents (first entry maps to the name column if present).

This is useful for providing sum totals, extra function buttons or extra space.

The default implementation returns an empty node.

Type:
  • Array.<string> | function
Inherited From
Default Value
  • `E([])`
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max_cols :number

Specify a maximum amount of columns to display. By default, one table column is rendered for each child option of the form section element. When this option is set to a positive number, then no more columns than the given amount are rendered. When the number of child options exceeds the specified amount, a More… button is rendered in the last column, opening a modal dialog presenting all options elements in NamedSection style when clicked.

Type:
  • number
Inherited From
Default Value
  • null
Source

modaltitle :string|function

Override the per-section instance modal popup title caption shown when clicking the More… button in a section specifying max_cols. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument, and its return value is used as a caption after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

nodescriptions :boolean

Set to true, the header row with the descriptions of options will not be displayed. By default, the row of descriptions is automatically displayed when at least one option has a description.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

rowcolors :boolean

Set to true, alternating cbi-rowstyle-1 and cbi-rowstyle-2 CSS classes are added to the table row elements. Not all LuCI themes implement these row style classes. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

sectiontitle :string|function

Override the per-section instance title caption shown in the first column of the table unless anonymous is set to true. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument and its return value used as a caption, after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

sortable :boolean

Set to true, a sort button is added to the last column, allowing the user to reorder the section instances mapped by the section form element.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

Methods

(abstract) addModalOptions(modalSection, section_id, ev) → {*|Promise.<*>}

Add further options to the per-section instanced modal popup.

This function may be overridden by user code to perform additional setup steps before displaying the more options modal which is useful to e.g. query additional data or to inject further option elements.

The default implementation of this function does nothing.

Parameters:
NameTypeDescription
modalSectionLuCI.form.NamedSection

The NamedSection instance about to be rendered in the modal popup.

section_idstring

The ID of the underlying UCI section the modal popup belongs to.

evEvent

The DOM event emitted by clicking the More… button.

Inherited From
Source
Returns:

Return values of this function are ignored but if a promise is returned, it is run to completion before the rendering is continued, allowing custom logic to perform asynchronous work before the modal dialog is shown.

Type: 
* | Promise.<*>

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Overrides
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The modal option elements of a grid section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that tabs are only effective in modal popups. Options added with option() will not be assigned to a specific tab and are rendered in the table view only.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Overrides
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.HiddenValue.html b/jsapi/LuCI.form.HiddenValue.html index bbce495c4f..81cf68fcd0 100644 --- a/jsapi/LuCI.form.HiddenValue.html +++ b/jsapi/LuCI.form.HiddenValue.html @@ -1,3 +1,3 @@ Class: HiddenValue
On this page

LuCI.form. HiddenValue

The HiddenValue element wraps a LuCI.ui.Hiddenfield widget.

Hidden value widgets used to be necessary in legacy code which actually submitted the underlying HTML form the server. With client side handling of forms, there are more efficient ways to store hidden state data.

Since this widget has no visible content, the title and description values of this form element should be set to null as well to avoid a broken or distorted form layout when rendering the option element.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. HiddenValue

The HiddenValue element wraps a LuCI.ui.Hiddenfield widget.

Hidden value widgets used to be necessary in legacy code which actually submitted the underlying HTML form the server. With client side handling of forms, there are more efficient ways to store hidden state data.

Since this widget has no visible content, the title and description values of this form element should be set to null as well to avoid a broken or distorted form layout when rendering the option element.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.JSONMap.html b/jsapi/LuCI.form.JSONMap.html index 31f07bc502..c910614e10 100644 --- a/jsapi/LuCI.form.JSONMap.html +++ b/jsapi/LuCI.form.JSONMap.html @@ -1,3 +1,3 @@ Class: JSONMap
On this page

LuCI.form. JSONMap

A JSONMap class functions similar to LuCI.form.Map but uses a multidimensional JavaScript object instead of UCI configuration as a data source.

Constructor

new JSONMap(data, titleopt, descriptionopt)

Parameters:
NameTypeAttributesDescription
dataObject.<string, (Object.<string, *>|Array.<Object.<string, *>>)>

The JavaScript object to use as a data source. Internally, the object is converted into an UCI-like format. Its top-level keys are treated like UCI section types while the object or array-of-object values are treated as section contents.

titlestring<optional>

The title caption of the form. A form title is usually rendered as a separate headline element before the actual form contents. If omitted, the corresponding headline element will not be rendered.

descriptionstring<optional>

The description text of the form which is usually rendered as a text paragraph below the form title and before the actual form contents. If omitted, the corresponding paragraph element will not be rendered.

Source

Extends

Members

readonly :boolean

Toggle readonly state of the form.

If set to true, the Map instance is marked readonly and any form option elements added to it will inherit the readonly state.

If left unset, the Map will test the access permission of the primary uci configuration upon loading and mark the form readonly if no write permissions are granted.

Type:
  • boolean
Inherited From
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

chain(config)

Tie another UCI configuration to the map.

By default, a map instance will only load the UCI configuration file specified in the constructor, but sometimes access to values from further configuration files is required. This function allows for such use cases by registering further UCI configuration files which are needed by the map.

Parameters:
NameTypeDescription
configstring

The additional UCI configuration file to tie to the map. If the given config is in the list of required files already, it will be ignored.

Inherited From
Source

findElement(…args, selector_or_attrname, attrvalueopt) → {Node|null}

Return the first DOM node within this Map which matches the given search parameters. This function is essentially a convenience wrapper around findElements() which only returns the first found node.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, it is used as selector-expression as-is. When two arguments are passed, the first argument is treated as an attribute name, the second one as an attribute value to match.

As an example, map.findElement('input') would find the first <input> node while map.findElement('type', 'text') would find the first DOM node with a type="text" attribute.

Parameters:
NameTypeAttributesDescription
args*<repeatable>

argument array

selector_or_attrnamestring

If invoked with only one parameter, this argument is a querySelector() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.

attrvaluestring<optional>

In case the function is invoked with two parameters, this argument specifies the attribute value to match.

Inherited From
Source
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:

Returns the first found DOM node or null if no element matched.

Type: 
Node | null

findElements(…args, selector_or_attrname, attrvalueopt) → {NodeList}

Return all DOM nodes within this Map which match the given search parameters. This function is essentially a convenience wrapper around querySelectorAll().

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, it is used as selector-expression as-is. When two arguments are passed, the first argument is treated as an attribute name, the second one as an attribute value to match.

As an example, map.findElements('input') would find all <input> nodes while map.findElements('type', 'text') would find any DOM node with a type="text" attribute.

Parameters:
NameTypeAttributesDescription
args*<repeatable>

argument array

selector_or_attrnamestring

If invoked with only one parameter, this argument is a querySelectorAll() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.

attrvaluestring<optional>

In case the function is invoked with two parameters, this argument specifies the attribute value to match.

Inherited From
Source
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:

Returns a (possibly empty) DOM NodeList containing the found DOM nodes.

Type: 
NodeList

load() → {Promise.<void>}

Load the configuration covered by this map.

The load() function first loads all referenced UCI configurations, then it recursively walks the form element tree and invokes the load function of each child element.

Inherited From
Source
Returns:

Returns a promise resolving once the entire form completed loading all data. The promise may reject with an error if any configuration failed to load or if any of the child elements' load functions reject with an error.

Type: 
Promise.<void>

lookupOption(name, section_idopt, config_nameopt) → {Array.<LuCI.form.AbstractValue, string>|null}

Find a form option element instance.

Parameters:
NameTypeAttributesDescription
namestring

The name or the full ID of the option element to look up.

section_idstring<optional>

The ID of the UCI section that contains the option to look up. May be omitted if a full ID is passed as the first argument.

config_namestring<optional>

The name of the UCI configuration the option instance belongs to. Defaults to the main UCI configuration of the map if omitted.

Inherited From
Source
Returns:

Returns a two-element array containing the form option instance as the first item and the corresponding UCI section ID as the second item. Returns null if the option could not be found.

Type: 
Array.<LuCI.form.AbstractValue, string> | null

parse() → {Promise.<void>}

Parse the form input values.

The parse() function recursively walks the form element tree and triggers input value reading and validation for each child element.

Elements which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the entire form completed parsing all input values. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Promise.<Node>}

Render the form markup.

Inherited From
Source
Returns:

Returns a promise resolving to the top-level form DOM node once the rendering is complete.

Type: 
Promise.<Node>

reset() → {Promise.<Node>}

Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.

Inherited From
Source
Returns:

Returns a promise resolving to the top-level form DOM node once the re-rendering is complete.

Type: 
Promise.<Node>

save(cbopt, silentopt) → {Promise.<void>}

Save the form input values.

This function parses the current form, saves the resulting UCI changes, reloads the UCI configuration data and redraws the form elements.

Parameters:
NameTypeAttributesDefaultDescription
cbfunction<optional>

An optional callback function that is invoked after the form is parsed but before the changed UCI data is saved. This is useful to perform additional data manipulation steps before saving the changes.

silentboolean<optional>
false

If set to true, trigger an alert message to the user in case saving the form data fails. Otherwise fail silently.

Inherited From
Source
Returns:

Returns a promise resolving once the entire save operation is complete. The returned promise is rejected if any step of the save operation failed.

Type: 
Promise.<void>

section(cbiClass, …args) → {LuCI.form.AbstractSection}

Add a configuration section to the map.

LuCI forms follow the structure of the underlying UCI configurations. This means that a map, which represents a single UCI configuration, is divided into multiple sections which in turn contain an arbitrary number of options.

While UCI itself only knows two kinds of sections - named and anonymous ones - the form class offers various flavors of form section elements to present configuration sections in different ways. Refer to the documentation of the different section classes for details.

Parameters:
NameTypeAttributesDescription
cbiClassLuCI.form.AbstractSection

(sectionclass) The section class to use for rendering the configuration section. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

argsstring<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given section class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Returns:

Returns the instantiated section class instance.

Type: 
LuCI.form.AbstractSection

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. JSONMap

A JSONMap class functions similar to LuCI.form.Map but uses a multidimensional JavaScript object instead of UCI configuration as a data source.

Constructor

new JSONMap(data, titleopt, descriptionopt)

Parameters:
NameTypeAttributesDescription
dataObject.<string, (Object.<string, *>|Array.<Object.<string, *>>)>

The JavaScript object to use as a data source. Internally, the object is converted into an UCI-like format. Its top-level keys are treated like UCI section types while the object or array-of-object values are treated as section contents.

titlestring<optional>

The title caption of the form. A form title is usually rendered as a separate headline element before the actual form contents. If omitted, the corresponding headline element will not be rendered.

descriptionstring<optional>

The description text of the form which is usually rendered as a text paragraph below the form title and before the actual form contents. If omitted, the corresponding paragraph element will not be rendered.

Source

Extends

Members

readonly :boolean

Toggle readonly state of the form.

If set to true, the Map instance is marked readonly and any form option elements added to it will inherit the readonly state.

If left unset, the Map will test the access permission of the primary uci configuration upon loading and mark the form readonly if no write permissions are granted.

Type:
  • boolean
Inherited From
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

chain(config)

Tie another UCI configuration to the map.

By default, a map instance will only load the UCI configuration file specified in the constructor, but sometimes access to values from further configuration files is required. This function allows for such use cases by registering further UCI configuration files which are needed by the map.

Parameters:
NameTypeDescription
configstring

The additional UCI configuration file to tie to the map. If the given config is in the list of required files already, it will be ignored.

Inherited From
Source

findElement(…args, selector_or_attrname, attrvalueopt) → {Node|null}

Return the first DOM node within this Map which matches the given search parameters. This function is essentially a convenience wrapper around findElements() which only returns the first found node.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, it is used as selector-expression as-is. When two arguments are passed, the first argument is treated as an attribute name, the second one as an attribute value to match.

As an example, map.findElement('input') would find the first <input> node while map.findElement('type', 'text') would find the first DOM node with a type="text" attribute.

Parameters:
NameTypeAttributesDescription
args*<repeatable>

argument array

selector_or_attrnamestring

If invoked with only one parameter, this argument is a querySelector() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.

attrvaluestring<optional>

In case the function is invoked with two parameters, this argument specifies the attribute value to match.

Inherited From
Source
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:

Returns the first found DOM node or null if no element matched.

Type: 
Node | null

findElements(…args, selector_or_attrname, attrvalueopt) → {NodeList}

Return all DOM nodes within this Map which match the given search parameters. This function is essentially a convenience wrapper around querySelectorAll().

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, it is used as selector-expression as-is. When two arguments are passed, the first argument is treated as an attribute name, the second one as an attribute value to match.

As an example, map.findElements('input') would find all <input> nodes while map.findElements('type', 'text') would find any DOM node with a type="text" attribute.

Parameters:
NameTypeAttributesDescription
args*<repeatable>

argument array

selector_or_attrnamestring

If invoked with only one parameter, this argument is a querySelectorAll() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.

attrvaluestring<optional>

In case the function is invoked with two parameters, this argument specifies the attribute value to match.

Inherited From
Source
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:

Returns a (possibly empty) DOM NodeList containing the found DOM nodes.

Type: 
NodeList

load() → {Promise.<void>}

Load the configuration covered by this map.

The load() function first loads all referenced UCI configurations, then it recursively walks the form element tree and invokes the load function of each child element.

Inherited From
Source
Returns:

Returns a promise resolving once the entire form completed loading all data. The promise may reject with an error if any configuration failed to load or if any of the child elements' load functions reject with an error.

Type: 
Promise.<void>

lookupOption(name, section_idopt, config_nameopt) → {Array.<LuCI.form.AbstractValue, string>|null}

Find a form option element instance.

Parameters:
NameTypeAttributesDescription
namestring

The name or the full ID of the option element to look up.

section_idstring<optional>

The ID of the UCI section that contains the option to look up. May be omitted if a full ID is passed as the first argument.

config_namestring<optional>

The name of the UCI configuration the option instance belongs to. Defaults to the main UCI configuration of the map if omitted.

Inherited From
Source
Returns:

Returns a two-element array containing the form option instance as the first item and the corresponding UCI section ID as the second item. Returns null if the option could not be found.

Type: 
Array.<LuCI.form.AbstractValue, string> | null

parse() → {Promise.<void>}

Parse the form input values.

The parse() function recursively walks the form element tree and triggers input value reading and validation for each child element.

Elements which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the entire form completed parsing all input values. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Promise.<Node>}

Render the form markup.

Inherited From
Source
Returns:

Returns a promise resolving to the top-level form DOM node once the rendering is complete.

Type: 
Promise.<Node>

reset() → {Promise.<Node>}

Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.

Inherited From
Source
Returns:

Returns a promise resolving to the top-level form DOM node once the re-rendering is complete.

Type: 
Promise.<Node>

save(cbopt, silentopt) → {Promise.<void>}

Save the form input values.

This function parses the current form, saves the resulting UCI changes, reloads the UCI configuration data and redraws the form elements.

Parameters:
NameTypeAttributesDefaultDescription
cbfunction<optional>

An optional callback function that is invoked after the form is parsed but before the changed UCI data is saved. This is useful to perform additional data manipulation steps before saving the changes.

silentboolean<optional>
false

If set to true, trigger an alert message to the user in case saving the form data fails. Otherwise fail silently.

Inherited From
Source
Returns:

Returns a promise resolving once the entire save operation is complete. The returned promise is rejected if any step of the save operation failed.

Type: 
Promise.<void>

section(cbiClass, …args) → {LuCI.form.AbstractSection}

Add a configuration section to the map.

LuCI forms follow the structure of the underlying UCI configurations. This means that a map, which represents a single UCI configuration, is divided into multiple sections which in turn contain an arbitrary number of options.

While UCI itself only knows two kinds of sections - named and anonymous ones - the form class offers various flavors of form section elements to present configuration sections in different ways. Refer to the documentation of the different section classes for details.

Parameters:
NameTypeAttributesDescription
cbiClassLuCI.form.AbstractSection

(sectionclass) The section class to use for rendering the configuration section. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

argsstring<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given section class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Returns:

Returns the instantiated section class instance.

Type: 
LuCI.form.AbstractSection

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.ListValue.html b/jsapi/LuCI.form.ListValue.html index e9d020d241..713d0972af 100644 --- a/jsapi/LuCI.form.ListValue.html +++ b/jsapi/LuCI.form.ListValue.html @@ -1,3 +1,3 @@ Class: ListValue
On this page

LuCI.form. ListValue

The ListValue class implements a simple static HTML select element allowing the user to choose a single value from a set of predefined choices. It builds upon the LuCI.ui.Select widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

orientation :string

Set the orientation of the underlying radio or checkbox elements.

May be one of horizontal or vertical. Only applies to non-select widget types.

Type:
  • string
Default Value
  • horizontal
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

size :number

Set the size attribute of the underlying HTML select element.

Type:
  • number
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

widget :string

Set the type of the underlying form controls.

May be one of select or radio. If set to select, an HTML select element is rendered, otherwise a collection of radio elements is used.

Type:
  • string
Default Value
  • select
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. ListValue

The ListValue class implements a simple static HTML select element allowing the user to choose a single value from a set of predefined choices. It builds upon the LuCI.ui.Select widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

orientation :string

Set the orientation of the underlying radio or checkbox elements.

May be one of horizontal or vertical. Only applies to non-select widget types.

Type:
  • string
Default Value
  • horizontal
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

size :number

Set the size attribute of the underlying HTML select element.

Type:
  • number
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

widget :string

Set the type of the underlying form controls.

May be one of select or radio. If set to select, an HTML select element is rendered, otherwise a collection of radio elements is used.

Type:
  • string
Default Value
  • select
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.MultiValue.html b/jsapi/LuCI.form.MultiValue.html index 71ed0f9ccd..57a129dc1a 100644 --- a/jsapi/LuCI.form.MultiValue.html +++ b/jsapi/LuCI.form.MultiValue.html @@ -1,3 +1,3 @@ Class: MultiValue
On this page

LuCI.form. MultiValue

The MultiValue class is a modified variant of the DynamicList element which leverages the LuCI.ui.Dropdown widget to implement a multi select dropdown element.

Source

Extends

Members

allowduplicates :boolean

Allows the underlying form controls to have multiple identical values.

Default is null. If true, the underlying form value will not be checked for duplication.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

create :boolean

Allows custom value entry in addition to those already specified.

Type:
  • boolean
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

display_size :number

Allows specifying the display_items property of the underlying dropdown widget. If omitted, the value of the size property is used or 3 when size is also unspecified.

Type:
  • number
Default Value
  • null
Source

Allows specifying the dropdown_items property of the underlying dropdown widget. If omitted, the value of the size property is used or -1 when size is also unspecified.

Type:
  • number
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. MultiValue

The MultiValue class is a modified variant of the DynamicList element which leverages the LuCI.ui.Dropdown widget to implement a multi select dropdown element.

Source

Extends

Members

allowduplicates :boolean

Allows the underlying form controls to have multiple identical values.

Default is null. If true, the underlying form value will not be checked for duplication.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

create :boolean

Allows custom value entry in addition to those already specified.

Type:
  • boolean
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

display_size :number

Allows specifying the display_items property of the underlying dropdown widget. If omitted, the value of the size property is used or 3 when size is also unspecified.

Type:
  • number
Default Value
  • null
Source

Allows specifying the dropdown_items property of the underlying dropdown widget. If omitted, the value of the size property is used or -1 when size is also unspecified.

Type:
  • number
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.NamedSection.html b/jsapi/LuCI.form.NamedSection.html index 3bd3a68b68..395ef9e59b 100644 --- a/jsapi/LuCI.form.NamedSection.html +++ b/jsapi/LuCI.form.NamedSection.html @@ -1,3 +1,3 @@ Class: NamedSection
On this page

LuCI.form. NamedSection

The NamedSection class maps exactly one UCI section instance which is specified when constructing the class instance.

Layout and functionality wise, a named section is essentially a TypedSection which allows exactly one section node.

Source

Extends

Members

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

(static) addremove :boolean

Set to true, the user may remove or recreate the sole mapped configuration instance from the form section widget, otherwise only a pre-existing section may be edited. The default is false.

Type:
  • boolean
Default Value
  • false
Source

(static) hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Default Value
  • false
Source

(static) uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgsections() → {Array.<string>}

The NamedSection class overrides the generic cfgsections() implementation to return a one-element array containing the mapped section ID as a sole element. User code should not normally change this.

Overrides
Source
Returns:

Returns a one-element array containing the mapped section ID.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Inherited From
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. NamedSection

The NamedSection class maps exactly one UCI section instance which is specified when constructing the class instance.

Layout and functionality wise, a named section is essentially a TypedSection which allows exactly one section node.

Source

Extends

Members

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

(static) addremove :boolean

Set to true, the user may remove or recreate the sole mapped configuration instance from the form section widget, otherwise only a pre-existing section may be edited. The default is false.

Type:
  • boolean
Default Value
  • false
Source

(static) hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Default Value
  • false
Source

(static) uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgsections() → {Array.<string>}

The NamedSection class overrides the generic cfgsections() implementation to return a one-element array containing the mapped section ID as a sole element. User code should not normally change this.

Overrides
Source
Returns:

Returns a one-element array containing the mapped section ID.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Inherited From
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.RangeSliderValue.html b/jsapi/LuCI.form.RangeSliderValue.html index e249d50a30..8f9b489f23 100644 --- a/jsapi/LuCI.form.RangeSliderValue.html +++ b/jsapi/LuCI.form.RangeSliderValue.html @@ -1,3 +1,3 @@ Class: RangeSliderValue
On this page

LuCI.form. RangeSliderValue

The RangeSliderValue class implements a range slider input using LuCI.ui.RangeSlider. It is useful in cases where a value shall fall within a predetermined range. This helps omit various error checks for such values. The currently chosen value is displayed to the side of the slider.

Source

Extends

Members

calculate :function

Override the calculate action.

When this property is set to a function, it is invoked when the slider is adjusted. This might be useful to calculate and display a result which is more meaningful than the currently chosen value. The calculated value is displayed below the slider.

Type:
  • function
Default Value
  • null
Source

calcunits :string

Define the units of the calculated value.

Suffix a unit string to the calculated value, e.g. 'seconds' or 'dBm'.

Type:
  • string
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :string

Set the default value for the slider. The default value is elided during save: meaning, a currently chosen value which matches the default is not saved.

Type:
  • string
Overrides
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max :number

Maximum value the slider can represent.

Type:
  • number
Default Value
  • 100
Source

min :number

Minimum value the slider can represent.

Type:
  • number
Default Value
  • 0
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

step :string

Step size for each tick of the slider, or the special value "any" when handling arbitrary precision floating point numbers.

Type:
  • string
Default Value
  • 1
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

Query the current form input value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

Returns the currently selected value if it does not match the default. If the currently selected value matches the default value, returns null.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. RangeSliderValue

The RangeSliderValue class implements a range slider input using LuCI.ui.RangeSlider. It is useful in cases where a value shall fall within a predetermined range. This helps omit various error checks for such values. The currently chosen value is displayed to the side of the slider.

Source

Extends

Members

calculate :function

Override the calculate action.

When this property is set to a function, it is invoked when the slider is adjusted. This might be useful to calculate and display a result which is more meaningful than the currently chosen value. The calculated value is displayed below the slider.

Type:
  • function
Default Value
  • null
Source

calcunits :string

Define the units of the calculated value.

Suffix a unit string to the calculated value, e.g. 'seconds' or 'dBm'.

Type:
  • string
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :string

Set the default value for the slider. The default value is elided during save: meaning, a currently chosen value which matches the default is not saved.

Type:
  • string
Overrides
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max :number

Maximum value the slider can represent.

Type:
  • number
Default Value
  • 100
Source

min :number

Minimum value the slider can represent.

Type:
  • number
Default Value
  • 0
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

step :string

Step size for each tick of the slider, or the special value "any" when handling arbitrary precision floating point numbers.

Type:
  • string
Default Value
  • 1
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

Query the current form input value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

Returns the currently selected value if it does not match the default. If the currently selected value matches the default value, returns null.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Inherited From
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.RichListValue.html b/jsapi/LuCI.form.RichListValue.html index 3aa16c3fc2..c51f881203 100644 --- a/jsapi/LuCI.form.RichListValue.html +++ b/jsapi/LuCI.form.RichListValue.html @@ -1,3 +1,3 @@ Class: RichListValue
On this page

LuCI.form. RichListValue

The RichListValue class implements a simple static HTML select element allowing the user to choose a single value from a set of predefined choices. Each choice may contain a tertiary, more elaborate description. It builds upon the LuCI.form.ListValue widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

orientation :string

Set the orientation of the underlying radio or checkbox elements.

May be one of horizontal or vertical. Only applies to non-select widget types.

Type:
  • string
Overrides
Default Value
  • horizontal
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

size :number

Set the size attribute of the underlying HTML select element.

Type:
  • number
Overrides
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

widget :string

Set the type of the underlying form controls.

May be one of select or radio. If set to select, an HTML select element is rendered, otherwise a collection of radio elements is used.

Type:
  • string
Overrides
Default Value
  • select
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(value, title, description)

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.

Parameters:
NameTypeDescription
valuestring

The choice value to add.

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

descriptionNode | string

The description text of the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the value element is implemented as a simple ListValue entry.

Overrides
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. RichListValue

The RichListValue class implements a simple static HTML select element allowing the user to choose a single value from a set of predefined choices. Each choice may contain a tertiary, more elaborate description. It builds upon the LuCI.form.ListValue widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

orientation :string

Set the orientation of the underlying radio or checkbox elements.

May be one of horizontal or vertical. Only applies to non-select widget types.

Type:
  • string
Overrides
Default Value
  • horizontal
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

size :number

Set the size attribute of the underlying HTML select element.

Type:
  • number
Overrides
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

widget :string

Set the type of the underlying form controls.

May be one of select or radio. If set to select, an HTML select element is rendered, otherwise a collection of radio elements is used.

Type:
  • string
Overrides
Default Value
  • select
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(value, title, description)

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.

Parameters:
NameTypeDescription
valuestring

The choice value to add.

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

descriptionNode | string

The description text of the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the value element is implemented as a simple ListValue entry.

Overrides
Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.SectionValue.html b/jsapi/LuCI.form.SectionValue.html index 359d5e9dd2..da5d73a8e1 100644 --- a/jsapi/LuCI.form.SectionValue.html +++ b/jsapi/LuCI.form.SectionValue.html @@ -1,3 +1,3 @@ Class: SectionValue
On this page

LuCI.form. SectionValue

The SectionValue widget embeds a form section element within an option element container, allowing to nest form sections into other sections.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

(static, readonly) subsection :LuCI.form.AbstractSection

Access the embedded section instance.

This property holds a reference to the instantiated nested section.

Type:
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {null}

Since the section container is not tied to any UCI configuration, its cfgvalue() implementation will always return null.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:
Type: 
null

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {null}

Since the section container is not tied to any UCI configuration, its formvalue() implementation will always return null.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:
Type: 
null

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

Since the section container is not tied to any UCI configuration, its remove() implementation is a no-op.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

Since the section container is not rendering an own widget, its value() implementation is a no-op.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Overrides
Source

write(section_id, formvalue) → {null}

Since the section container is not tied to any UCI configuration, its write() implementation is a no-op.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Overrides
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. SectionValue

The SectionValue widget embeds a form section element within an option element container, allowing to nest form sections into other sections.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

(static, readonly) subsection :LuCI.form.AbstractSection

Access the embedded section instance.

This property holds a reference to the instantiated nested section.

Type:
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {null}

Since the section container is not tied to any UCI configuration, its cfgvalue() implementation will always return null.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:
Type: 
null

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {null}

Since the section container is not tied to any UCI configuration, its formvalue() implementation will always return null.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:
Type: 
null

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

Since the section container is not tied to any UCI configuration, its remove() implementation is a no-op.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Overrides
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

Since the section container is not rendering an own widget, its value() implementation is a no-op.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Overrides
Source

write(section_id, formvalue) → {null}

Since the section container is not tied to any UCI configuration, its write() implementation is a no-op.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Overrides
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.TableSection.html b/jsapi/LuCI.form.TableSection.html index 95bfd2e169..24a03eb910 100644 --- a/jsapi/LuCI.form.TableSection.html +++ b/jsapi/LuCI.form.TableSection.html @@ -1,3 +1,3 @@ Class: TableSection
On this page

LuCI.form. TableSection

The TableSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

Layout wise, the configuration section instances mapped by the section element (sometimes referred to as "section nodes") are rendered as rows within an HTML table element, with an optional section remove button in the last column and a section add button below the table, depending on the value of the addremove property.

Source

Extends

Members

actionstitle :string|function

Set a custom text for the actions column header row when actions buttons are present.

Type:
  • string | function
Default Value
  • null
Source

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

cloneable :boolean

Set to true, a clone button is added to the button column, allowing the user to clone section instances mapped by the section form element. The default is false.

Type:
  • boolean
Default Value
  • false
Source

clonebtntitle :string|function

Override the caption used for the section clone button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Clone.

Type:
  • string | function
Default Value
  • null
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

extedit :string|function

Enables a per-section instance row Edit button which triggers a certain action when clicked. Set to a string, the string value is used as a String.format() pattern with the name of the underlying UCI section as the first format argument. The result is then interpreted as a URL which LuCI will navigate to when the user clicks the edit button.

If set to a function, this function will be registered as a click event handler on the rendered edit button, receiving the section instance name as the first and the DOM click event as the second argument.

Type:
  • string | function
Default Value
  • null
Source

filterrow :boolean

Optional table filtering for table sections.

Set filterrow to true to display a filter header row in the generated table with per-column text fields to search for string matches in the column. The filter row appears after the titles row.

The filters work cumulatively: text in each field shall match an entry for the row to be displayed. The results are filtered live. Matching is case-sensitive, and partial, i.e. part or all of the result includes the search string.

The filter fields assume the placeholder text Filter suffixed with the column name, to ease correlation of filter fields to their corresponding column entries on narrow displays which might fold the columns over multiple lines.

Type:
  • boolean
Default Value
  • null
Source

Optional footer row for table sections.

Set footer to one of:

  • a function that returns a table row (tr) or node E('...')
  • an array of string cell contents (first entry maps to the name column if present).

This is useful for providing sum totals, extra function buttons or extra space.

The default implementation returns an empty node.

Type:
  • Array.<string> | function
Default Value
  • `E([])`
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max_cols :number

Specify a maximum amount of columns to display. By default, one table column is rendered for each child option of the form section element. When this option is set to a positive number, then no more columns than the given amount are rendered. When the number of child options exceeds the specified amount, a More… button is rendered in the last column, opening a modal dialog presenting all options elements in NamedSection style when clicked.

Type:
  • number
Default Value
  • null
Source

modaltitle :string|function

Override the per-section instance modal popup title caption shown when clicking the More… button in a section specifying max_cols. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument, and its return value is used as a caption after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Default Value
  • null
Source

nodescriptions :boolean

Set to true, the header row with the descriptions of options will not be displayed. By default, the row of descriptions is automatically displayed when at least one option has a description.

Type:
  • boolean
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

rowcolors :boolean

Set to true, alternating cbi-rowstyle-1 and cbi-rowstyle-2 CSS classes are added to the table row elements. Not all LuCI themes implement these row style classes. The default is false.

Type:
  • boolean
Default Value
  • false
Source

sectiontitle :string|function

Override the per-section instance title caption shown in the first column of the table unless anonymous is set to true. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument and its return value used as a caption, after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Default Value
  • null
Source

sortable :boolean

Set to true, a sort button is added to the last column, allowing the user to reorder the section instances mapped by the section form element.

Type:
  • boolean
Default Value
  • false
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

Methods

(abstract) addModalOptions(modalSection, section_id, ev) → {*|Promise.<*>}

Add further options to the per-section instanced modal popup.

This function may be overridden by user code to perform additional setup steps before displaying the more options modal which is useful to e.g. query additional data or to inject further option elements.

The default implementation of this function does nothing.

Parameters:
NameTypeDescription
modalSectionLuCI.form.NamedSection

The NamedSection instance about to be rendered in the modal popup.

section_idstring

The ID of the underlying UCI section the modal popup belongs to.

evEvent

The DOM event emitted by clicking the More… button.

Source
Returns:

Return values of this function are ignored but if a promise is returned, it is run to completion before the rendering is continued, allowing custom logic to perform asynchronous work before the modal dialog is shown.

Type: 
* | Promise.<*>

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

The TableSection implementation does not support option tabbing, so its implementation of tab() will always throw an exception when invoked.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Overrides
Source
Throws:

Throws an exception when invoked.

Type
string

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. TableSection

The TableSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

Layout wise, the configuration section instances mapped by the section element (sometimes referred to as "section nodes") are rendered as rows within an HTML table element, with an optional section remove button in the last column and a section add button below the table, depending on the value of the addremove property.

Source

Extends

Members

actionstitle :string|function

Set a custom text for the actions column header row when actions buttons are present.

Type:
  • string | function
Default Value
  • null
Source

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

cloneable :boolean

Set to true, a clone button is added to the button column, allowing the user to clone section instances mapped by the section form element. The default is false.

Type:
  • boolean
Default Value
  • false
Source

clonebtntitle :string|function

Override the caption used for the section clone button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Clone.

Type:
  • string | function
Default Value
  • null
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Inherited From
Default Value
  • null
Source

extedit :string|function

Enables a per-section instance row Edit button which triggers a certain action when clicked. Set to a string, the string value is used as a String.format() pattern with the name of the underlying UCI section as the first format argument. The result is then interpreted as a URL which LuCI will navigate to when the user clicks the edit button.

If set to a function, this function will be registered as a click event handler on the rendered edit button, receiving the section instance name as the first and the DOM click event as the second argument.

Type:
  • string | function
Default Value
  • null
Source

filterrow :boolean

Optional table filtering for table sections.

Set filterrow to true to display a filter header row in the generated table with per-column text fields to search for string matches in the column. The filter row appears after the titles row.

The filters work cumulatively: text in each field shall match an entry for the row to be displayed. The results are filtered live. Matching is case-sensitive, and partial, i.e. part or all of the result includes the search string.

The filter fields assume the placeholder text Filter suffixed with the column name, to ease correlation of filter fields to their corresponding column entries on narrow displays which might fold the columns over multiple lines.

Type:
  • boolean
Default Value
  • null
Source

Optional footer row for table sections.

Set footer to one of:

  • a function that returns a table row (tr) or node E('...')
  • an array of string cell contents (first entry maps to the name column if present).

This is useful for providing sum totals, extra function buttons or extra space.

The default implementation returns an empty node.

Type:
  • Array.<string> | function
Default Value
  • `E([])`
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

max_cols :number

Specify a maximum amount of columns to display. By default, one table column is rendered for each child option of the form section element. When this option is set to a positive number, then no more columns than the given amount are rendered. When the number of child options exceeds the specified amount, a More… button is rendered in the last column, opening a modal dialog presenting all options elements in NamedSection style when clicked.

Type:
  • number
Default Value
  • null
Source

modaltitle :string|function

Override the per-section instance modal popup title caption shown when clicking the More… button in a section specifying max_cols. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument, and its return value is used as a caption after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Default Value
  • null
Source

nodescriptions :boolean

Set to true, the header row with the descriptions of options will not be displayed. By default, the row of descriptions is automatically displayed when at least one option has a description.

Type:
  • boolean
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

rowcolors :boolean

Set to true, alternating cbi-rowstyle-1 and cbi-rowstyle-2 CSS classes are added to the table row elements. Not all LuCI themes implement these row style classes. The default is false.

Type:
  • boolean
Default Value
  • false
Source

sectiontitle :string|function

Override the per-section instance title caption shown in the first column of the table unless anonymous is set to true. Set to a string, it will be used as a String.format() pattern with the name of the underlying UCI section as the first argument. Set to a function, the function will be invoked with the section name as the first argument and its return value used as a caption, after converting it to a string. If this property is not set, the default is the name of the underlying UCI configuration section.

Type:
  • string | function
Default Value
  • null
Source

sortable :boolean

Set to true, a sort button is added to the last column, allowing the user to reorder the section instances mapped by the section form element.

Type:
  • boolean
Default Value
  • false
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

Methods

(abstract) addModalOptions(modalSection, section_id, ev) → {*|Promise.<*>}

Add further options to the per-section instanced modal popup.

This function may be overridden by user code to perform additional setup steps before displaying the more options modal which is useful to e.g. query additional data or to inject further option elements.

The default implementation of this function does nothing.

Parameters:
NameTypeDescription
modalSectionLuCI.form.NamedSection

The NamedSection instance about to be rendered in the modal popup.

section_idstring

The ID of the underlying UCI section the modal popup belongs to.

evEvent

The DOM event emitted by clicking the More… button.

Source
Returns:

Return values of this function are ignored but if a promise is returned, it is run to completion before the rendering is continued, allowing custom logic to perform asynchronous work before the modal dialog is shown.

Type: 
* | Promise.<*>

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

The TableSection implementation does not support option tabbing, so its implementation of tab() will always throw an exception when invoked.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Overrides
Source
Throws:

Throws an exception when invoked.

Type
string

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.TextValue.html b/jsapi/LuCI.form.TextValue.html index 70ef1f4889..d3349b6198 100644 --- a/jsapi/LuCI.form.TextValue.html +++ b/jsapi/LuCI.form.TextValue.html @@ -1,3 +1,3 @@ Class: TextValue
On this page

LuCI.form. TextValue

The TextValue class implements a multi-line textarea input using LuCI.ui.Textarea.

Source

Extends

Members

cols :number

Allows specifying the cols property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

monospace :boolean

Enforces the use of a monospace font for the textarea contents when set to true.

Type:
  • boolean
Default Value
  • false
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

rows :number

Allows specifying the rows property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

wrap :number

Allows specifying the wrap property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. TextValue

The TextValue class implements a multi-line textarea input using LuCI.ui.Textarea.

Source

Extends

Members

cols :number

Allows specifying the cols property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

monospace :boolean

Enforces the use of a monospace font for the textarea contents when set to true.

Type:
  • boolean
Default Value
  • false
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Inherited From
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Inherited From
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

rows :number

Allows specifying the rows property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Inherited From
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

wrap :number

Allows specifying the wrap property of the underlying textarea widget.

Type:
  • number
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.TypedSection.html b/jsapi/LuCI.form.TypedSection.html index 1df5eb7aa2..d784e728f9 100644 --- a/jsapi/LuCI.form.TypedSection.html +++ b/jsapi/LuCI.form.TypedSection.html @@ -1,3 +1,3 @@ Class: TypedSection
On this page

LuCI.form. TypedSection

The TypedSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

Layout wise, the configuration section instances mapped by the section element (sometimes referred to as "section nodes") are stacked beneath each other in a single column, with an optional section remove button next to each section node and a section add button at the end, depending on the value of the addremove property.

Source

Extends

Members

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Default Value
  • false
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Default Value
  • null
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgsections() → {Array.<string>}

Enumerate the UCI section IDs covered by this form section element.

Overrides
Source
Throws:

Throws an InternalError exception if the function is not implemented.

Type
InternalError
Returns:

Returns an array of UCI section IDs covered by this form element. The sections will be rendered in the same order as the returned array.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Inherited From
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. TypedSection

The TypedSection class maps all or - if filter() is overridden - a subset of the underlying UCI configuration sections of a given type.

Layout wise, the configuration section instances mapped by the section element (sometimes referred to as "section nodes") are stacked beneath each other in a single column, with an optional section remove button next to each section node and a section add button at the end, depending on the value of the addremove property.

Source

Extends

Members

addbtntitle :string|function

Override the caption used for the section add button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Add.

Type:
  • string | function
Default Value
  • null
Source

addremove :boolean

If set to true, the user may add or remove instances from the form section widget, otherwise only pre-existing sections may be edited. The default is false.

Type:
  • boolean
Default Value
  • false
Source

anonymous :boolean

If set to true, mapped section instances are treated as anonymous UCI sections, which means that section instance elements will be rendered without a title element and that no name is required when adding new sections. The default is false.

Type:
  • boolean
Default Value
  • false
Source

delbtntitle :string|function

Override the caption used for the section delete button at the bottom of the section form element. Set to a string, it will be used as-is. Set to a function, the function will be invoked and its return value is used as a caption, after converting it to a string. If this property is not set, the default is Delete.

Type:
  • string | function
Default Value
  • null
Source

hidetitle :boolean

If set to true, the title caption of the form section element which is normally rendered before the start of the section content will not be rendered in the UI. The default is false, meaning that the title is rendered.

Type:
  • boolean
Default Value
  • false
Source

(readonly) parentoption :LuCI.form.AbstractValue

Access the parent option container instance.

In case this section is nested within an option element container, this property will hold a reference to the parent option instance.

If this section is not nested, the property is null.

Type:
Inherited From
Source

tabbed :boolean

When set to true, instead of rendering section instances one below another, treat each instance as a separate tab pane and render a tab menu at the top of the form section element, allowing the user to switch among instances. The default is false.

Type:
  • boolean
Default Value
  • false
Source

uciconfig :string

Override the UCI configuration name to read the section IDs from. By default, the configuration name is inherited from the parent Map. By setting this property, a deviating configuration may be specified. The default of null means inherit from the parent form.

Type:
  • string
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cfgsections() → {Array.<string>}

Enumerate the UCI section IDs covered by this form section element.

Overrides
Source
Throws:

Throws an InternalError exception if the function is not implemented.

Type
InternalError
Returns:

Returns an array of UCI section IDs covered by this form element. The sections will be rendered in the same order as the returned array.

Type: 
Array.<string>

cfgvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query underlying option configuration values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the configuration values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the configuration value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding configuration values or just a single configuration value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

(abstract) filter(section_id) → {boolean}

Filter UCI section IDs to render.

The filter function is invoked for each UCI section ID of a given type and controls whether the given UCI section is rendered or ignored by the form section element.

The default implementation always returns true. User code or classes extending AbstractSection may override this function with custom implementations.

Parameters:
NameTypeDescription
section_idstring

The UCI section ID to test.

Inherited From
Source
Returns:

Returns true when the given UCI section ID should be handled and false when it should be ignored.

Type: 
boolean

formvalue(section_id, optionopt) → {null|string|Array.<string>|Object.<string, (null|string|Array.<string>)>}

Query the underlying option widget input values.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the widget input values of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the widget input value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | string | Array.<string> | Object.<string, (null|string|Array.<string>)>

getOption(optionopt) → {null|LuCI.form.AbstractValue|Object.<string, LuCI.form.AbstractValue>}

Obtain underlying option objects.

This function is sensitive to the amount of arguments passed to it; if no option name is specified, all options within this section are returned as a dictionary.

If an option name is supplied, this function returns the matching LuCI.form.AbstractValue instance only.

Parameters:
NameTypeAttributesDescription
optionstring<optional>

The name of the option object to obtain

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding option instance objects or just a single object instance value, depending on the amount of passed arguments.

Type: 
null | LuCI.form.AbstractValue | Object.<string, LuCI.form.AbstractValue>

getUIElement(section_id, optionopt) → {null|LuCI.ui.AbstractElement|Object.<string, (null|LuCI.ui.AbstractElement)>}

Obtain underlying option LuCI.ui widget instances.

This function is sensitive to the amount of arguments passed to it; if only one argument is specified, the LuCI.ui widget instances of all options within this section are returned as a dictionary.

If both the section ID and an option name are supplied, this function returns the LuCI.ui widget instance value of the specified option only.

Parameters:
NameTypeAttributesDescription
section_idstring

The configuration section ID

optionstring<optional>

The name of the option to query

Inherited From
Source
Returns:

Returns either a dictionary of option names and their corresponding widget input values or just a single widget input value, depending on the amount of passed arguments.

Type: 
null | LuCI.ui.AbstractElement | Object.<string, (null|LuCI.ui.AbstractElement)>

load() → {Promise.<void>}

Load the configuration covered by this section.

The load() function recursively walks the section element tree and invokes the load function of each child option element.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been loaded. The promise may reject with an error if any of the child elements' load functions rejected with an error.

Type: 
Promise.<void>

option(optionclass, cbiClass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to the section.

Note that taboption() should be used instead if this form section element uses tabs.

Parameters:
NameTypeAttributesDescription
optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

cbiClassobject

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

args*<repeatable>

argument array

Inherited From
Source
Throws:

Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

Type
TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

parse() → {Promise.<void>}

Parse this sections form input.

The parse() function recursively walks the section element tree and triggers input value reading and validation for each encountered child option element.

Options which are hidden due to unsatisfied dependencies are skipped.

Inherited From
Source
Returns:

Returns a promise resolving once the values of all child elements have been parsed. The returned promise is rejected if any parsed values do not meet the validation constraints of their respective elements.

Type: 
Promise.<void>

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

tab(name, title, descriptionopt)

Add an option tab to the section.

The child option elements of a section may be divided into multiple tabs to provide a better overview to the user.

Before options can be moved into a tab pane, the corresponding tab has to be defined first, which is done by calling this function.

Note that once tabs are defined, user code must use the taboption() method to add options to specific tabs. Option elements added by option() will not be assigned to any tab and not be rendered in this case.

Parameters:
NameTypeAttributesDescription
namestring

The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs.

titlestring

The human readable caption of the tab.

descriptionstring<optional>

An additional description text for the corresponding tab pane. It is displayed as a text paragraph below the tab but before the tab pane contents. If omitted, no description will be rendered.

Inherited From
Source
Throws:

Throws an exception if a tab with the same name already exists.

Type
Error

taboption(tabName, optionclass, …args) → {LuCI.form.AbstractValue}

Add a configuration option widget to a tab of the section.

Parameters:
NameTypeAttributesDescription
tabNamestring

The name of the section tab to add the option element to.

optionclassLuCI.form.AbstractValue

The option class to use for rendering the configuration option. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class derived from AbstractSection.

args*<repeatable>

(classargs) Additional arguments which are passed as-is to the constructor of the given option class. Refer to the class specific constructor documentation for details.

Inherited From
Source
Throws:

  • Throws a ReferenceError exception when the given tab name does not exist.

    Type
    ReferenceError

  • Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.

    Type
    TypeError
Returns:

Returns the instantiated option class instance.

Type: 
LuCI.form.AbstractValue

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.Value.html b/jsapi/LuCI.form.Value.html index 4a97832467..41ebbcbfc1 100644 --- a/jsapi/LuCI.form.Value.html +++ b/jsapi/LuCI.form.Value.html @@ -1,3 +1,3 @@ Class: Value
On this page

LuCI.form. Value

The Value class represents a simple one-line form input using the LuCI.ui.Textfield or - in case choices are added - the LuCI.ui.Combobox class as underlying widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Overrides
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file +
On this page

LuCI.form. Value

The Value class represents a simple one-line form input using the LuCI.ui.Textfield or - in case choices are added - the LuCI.ui.Combobox class as underlying widget.

Source

Extends

Members

datatype :string

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.

Type:
  • string
Inherited From
Default Value
  • null
Source

default :*

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

Type:
  • *
Inherited From
Default Value
  • null
Source

editable :boolean

Mark the 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 a 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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

modalonly :boolean

Move the 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.

Type:
  • boolean
Inherited From
Default Value
  • null
Source

onchange :function

Register a custom value change handler.

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

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.

Type:
  • function
Inherited From
Default Value
  • null
Source

optional :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

password :boolean

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

Type:
  • boolean
Default Value
  • false
Source

placeholder :string

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

Type:
  • string
Default Value
  • null
Source

readonly :boolean

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, meaning its contents cannot be changed and the widget cannot be interacted with.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

retain :boolean

If set to true, the underlying ui input widget value is not cleared from the configuration on unsatisfied dependencies. The default behavior is to remove the values of all options whose dependencies are not fulfilled.

Type:
  • boolean
Inherited From
Default Value
  • false
Source

rmempty :boolean

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.

Type:
  • boolean
Inherited From
Default Value
  • true
Source

uciconfig :string

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 of null means inherit from the parent form.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucioption :string

Override the UCI option name to read the value from.

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

The default of null means use the option element name.

Type:
  • string
Inherited From
Default Value
  • null
Source

ucisection :string

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 of null means inherit from the parent section.

Type:
  • string
Inherited From
Default Value
  • null
Source

validate :function

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 a validation error message.

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

Type:
  • function
Overrides
Default Value
  • null
Source

width :number|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.

Type:
  • number | string
Inherited From
Default Value
  • null
Source

Methods

append(obj)

Add another form element as children to this element.

Parameters:
NameTypeDescription
objAbstractElement

The form element to add.

Inherited From
Source

cbid(section_id) → {string}

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the element ID.

Type: 
string

cfgvalue(section_id, set_value) → {*}

Query the underlying configuration value.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

set_valuestring

The value to assign

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the configuration value.

Type: 
*

depends(field, valueopt)

Add a dependency constraint to the option.

Dependency constraints allow making the presence of option elements dependent 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 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 the first argument, it is possible to depend on multiple options simultaneously, forming a logical "and" expression.

Option names may be given in "dot notation" which allows referencing option elements outside the current form section. If a name without a 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".
Parameters:
NameTypeAttributesDescription
fieldstring | Object.<string, (string|RegExp)>

The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression).

valuestring | RegExp<optional>

When invoked with a plain option name as the first argument, this parameter specifies the expected value. In case an object is passed as the first argument, this parameter is ignored.

Inherited From
Source

formvalue(section_id) → {*}

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 overridden by user code to handle input values differently.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the current input value.

Type: 
*

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

Obtain the underlying LuCI.ui element instance.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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

Type: 
LuCI.ui.AbstractElement | null

getValidationError(section_id) → {string}

Returns the current validation error for this input.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

The validation error at this time

Type: 
string

isActive(section_id) → {boolean}

Test whether the option element is currently active.

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

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

isValid(section_id) → {boolean}

Test whether the input value is currently valid.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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

Type: 
boolean

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

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 overridden by user code to load data from non-standard sources.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

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.

Type: 
* | Promise.<*>

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

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.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Returns:

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.

Type: 
Promise.<void>

remove(section_id)

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 overridden by user code to implement alternative removal logic, e.g. to retain the original value.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source

render() → {Node|Promise.<Node>}

Render the form element.

The render() function recursively walks the form element tree and renders the markup for each element, returning the assembled DOM tree.

Overrides
Source
Returns:

May return a DOM Node or a promise resolving to a DOM node containing the form element's markup, including the markup of any child elements.

Type: 
Node | Promise.<Node>

stripTags(s) → {string}

Strip any HTML tags from the given input string, and decode HTML entities.

Parameters:
NameTypeDescription
sstring

The input string to clean.

Inherited From
Source
Returns:

The cleaned input string with HTML tags removed, and HTML entities decoded.

Type: 
string

textvalue(section_id) → {string}

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 override this function to apply a different logic, e.g. to return Yes or No depending on the checked state of checkbox elements.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

Inherited From
Source
Throws:

Throws a TypeError exception when no section_id was specified.

Type
TypeError
Returns:

Returns the text representation of the current input value.

Type: 
string

titleFn(attr, …args) → {string|null}

Format the given named property as a title string.

This function looks up the given named property and formats its value suitable for use as an 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.

Parameters:
NameTypeAttributesDescription
attrstring

(property) The name of the element property to use.

argsstring<repeatable>

(fmt_args) Extra values to format the title string with.

Inherited From
Source
Returns:

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

Type: 
string | null

value(key, val)

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.

Parameters:
NameTypeDescription
keystring

The choice value to add.

valNode | 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 a caption.

Source

write(section_id, formvalue) → {null}

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 overridden by user code to implement alternative save logic, e.g. to transform the input value before it is written.

Parameters:
NameTypeDescription
section_idstring

The configuration section ID

formvaluestring | Array.<string>

The input value to write.

Inherited From
Source
Returns:
Type: 
null
LuCI Documentation
GitHub Project Page
Using JSON RPC daemon
Modules
Making Themes
Internationalisation - i18n
cbi
LuCI
baseclass
dom
form
AbstractElement
AbstractSection
AbstractValue
Button
DirectoryPicker
DummyValue
DynamicList
FileUpload
Flag
GridSection
HiddenValue
JSONMap
ListValue
Map
MultiValue
NamedSection
RangeSliderValue
RichListValue
SectionValue
TableSection
TextValue
TypedSection
Value
fs
headers
network
Device
Hosts
Protocol
WifiDevice
WifiNetwork
WifiVlan
poll
request
poll
response
rpc
session
uci
ui
AbstractElement
Checkbox
ComboButton
Combobox
Dropdown
DynamicList
FileUpload
Hiddenfield
RangeSlider
Select
Textarea
Textfield
changes
menu
tabs
validation
Validator
ValidatorFactory
view
xhr
String
\ No newline at end of file diff --git a/jsapi/LuCI.form.html b/jsapi/LuCI.form.html index 16a7b714d8..acbfce18f3 100644 --- a/jsapi/LuCI.form.html +++ b/jsapi/LuCI.form.html @@ -1,6 +1,6 @@ Class: form
On this page

LuCI. form

The LuCI form class provides high level abstractions for creating UCI- or JSON backed configurations forms.

To import the class in views, use 'require form', to import it in external JavaScript, use L.require("form").then(...).

A typical form is created by first constructing a LuCI.form.Map or LuCI.form.JSONMap instance using new and by subsequently adding sections and options to it. Finally render() is invoked on the instance to assemble the HTML markup and insert it into the DOM.

Source
Example
'use strict';
+    
On this page
LuCI. form
The LuCI form class provides high level abstractions for creating UCI- or JSON backed configurations forms.
To import the class in views, use 'require form', to import it in external JavaScript, use L.require("form").then(...).
A typical form is created by first constructing a LuCI.form.Map or LuCI.form.JSONMap instance using new and by subsequently adding sections and options to it. Finally render() is invoked on the instance to assemble the HTML markup and insert it into the DOM.
Source
Example
'use strict';
 'require form';
 
 let m, s, o;
diff --git a/jsapi/LuCI.html b/jsapi/LuCI.html
index 4c35157cf4..2cbef56574 100644
--- a/jsapi/LuCI.html
+++ b/jsapi/LuCI.html
@@ -1,3 +1,3 @@
 Class: LuCI
On this page
LuCI
new LuCI(window, document, undefined)
This is the LuCI base class. It is automatically instantiated and accessible using the global L variable.
Parameters:
NameTypeDescription
windowWindow
The browser global window object.
documentDocument
The DOM document root for the current page.
undefinedundefined
Local undefined slot (prevents shadowing and ensures undefined is the real undefined value).
Properties
NameTypeDescription
envobject
The environment settings to use for the LuCI runtime.
Source
Classes
baseclass
dom
form
fs
headers
network
poll
request
response
rpc
session
uci
ui
validation
view
xhr
Namespaces
validation
Members
Class
Legacy L.Class class alias. New view code should use 'require baseclass'; to request the LuCI.baseclass class.
Deprecated
  • Yes
Source
Poll
Legacy L.Poll class alias. New view code should use 'require poll'; to request the LuCI.poll class.
Deprecated
  • Yes
Source
Request
Legacy L.Request class alias. New view code should use 'require request'; to request the LuCI.request class.
Deprecated
  • Yes
Source
dom
Legacy L.dom class alias. New view code should use 'require dom'; to request the LuCI.dom class.
Deprecated
  • Yes
Source
env
The env object holds environment settings used by LuCI, such as request timeouts, base URLs, etc.
Source
naturalCompare :function
Compares two values numerically and returns -1, 0, or 1 depending on whether the first value is smaller, equal to, or larger than the second one respectively.
This function is meant to be used as a comparator function for Array.sort().
Type:
  • function
Source
view
Legacy L.view class alias. New view code should use 'require view'; to request the LuCI.view class.
Deprecated
  • Yes
Source
Methods
bind(fn, self, …argsopt) → {function}
Return a bound function using the given self as this context and any further arguments as parameters to the bound function.
Parameters:
NameTypeAttributesDescription
fnfunction
The function to bind.
self*
The value to bind as this context to the specified function.
args*<optional>
<repeatable>
Zero or more variable arguments which are bound to the function as parameters.
Source
Returns:
Returns the bound function.
Type: 
function
error(typeopt, fmtopt, …argsopt)
A wrapper around raise() which also renders the error either as modal overlay when ui.js is already loaded or directly into the view body.
Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error
Either a string specifying the type of the error to throw or an existing Error instance to copy.
fmtstring<optional>
Unspecified error
A format string which is used to form the error message, together with all subsequent optional arguments.
args*<optional>
<repeatable>
Zero or more variable arguments to the supplied format string.
Source
Throws:
Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.
Type
Error
fspath(…partsopt) → {string}
Construct an absolute filesystem path relative to the server document root.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a path.
Source
Returns:
Return the joined path.
Type: 
string
get(url, argsopt, cb) → {Promise.<null>}
Issues a GET request to the given url and invokes the specified callback function. The function is a wrapper around Request.request().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
argsObject.<string, string><optional>
Additional query string arguments to append to the URL.
cbLuCI.requestCallbackFn
The callback function to invoke when the request finishes.
Deprecated
  • Yes
Source
Returns:
Returns a promise resolving to null when concluded.
Type: 
Promise.<null>
halt() → {boolean}
Deprecated wrapper around Poll.stop().
Deprecated
  • Yes
Source
Returns:
Returns true when the polling loop has been stopped or false when it didn't run to begin with.
Type: 
boolean
hasSystemFeature(feature, subfeatureopt) → {boolean|null}
Test whether a particular system feature is available, such as hostapd SAE support or an installed firewall. The features are queried once at the beginning of the LuCI session and cached in SessionStorage throughout the lifetime of the associated tab or browser window.
Parameters:
NameTypeAttributesDescription
featurestring
The feature to test. For a detailed list of known feature flags, see /modules/luci-base/root/usr/share/rpcd/ucode/luci.
subfeaturestring<optional>
Some feature classes like hostapd provide sub-feature flags, such as sae or 11w support. The subfeature argument can be used to query these.
Source
Returns:
Return true if the queried feature (and sub-feature) is available or false if the requested feature isn't present or known. Return null when a sub-feature was queried for a feature which has no sub-features.
Type: 
boolean | null
hasViewPermission() → {boolean|null}
Check whether a view has sufficient permissions.
Source
Returns:
Returns null if the current session has no permission at all to load resources required by the view. Returns false if readonly permissions are granted or true if at least one required ACL group is granted with write permissions.
Type: 
boolean | null
isArguments(valopt) → {boolean}
Tests whether the passed argument is a function arguments object.
Parameters:
NameTypeAttributesDescription
val*<optional>
The value to test
Source
Returns:
Returns true if the given value is a function arguments object, else returns false.
Type: 
boolean
isObject(valopt) → {boolean}
Tests whether the passed argument is a JavaScript object. This function is meant to be an object counterpart to the standard Array.isArray() function.
Parameters:
NameTypeAttributesDescription
val*<optional>
The value to test
Source
Returns:
Returns true if the given value is of a type object and not null, else returns false.
Type: 
boolean
location() → {string}
Return the complete URL path to the current view.
Source
Returns:
Returns the URL path to the current view.
Type: 
string
media(…partsopt) → {string}
Construct a URL path relative to the media resource path of the LuCI ui (usually /luci-static/$theme_name).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
path(prefixopt, …partsopt) → {string}
Construct a relative URL path from the given prefix and parts. The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
prefixstring<optional>
The prefix to join the given parts with. If the prefix is omitted, it defaults to an empty string.
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Return the joined URL path.
Type: 
string
poll(interval, url, argsopt, cb, postopt) → {function}
Register a polling HTTP request that invokes the specified callback function. The function is a wrapper around Request.poll.add().
Parameters:
NameTypeAttributesDefaultDescription
intervalnumber
The poll interval to use. If set to a value less than or equal to 0, it will default to the global poll interval configured in LuCI.env.pollinterval.
urlstring
The URL to request.
argsObject.<string, string><optional>
Specifies additional arguments for the request. For GET requests, the arguments are appended to the URL as query string, for POST requests, they'll be added to the request body.
cbLuCI.requestCallbackFn
The callback function to invoke whenever a request finishes.
postboolean<optional>
false
When set to false or not specified, poll requests will be made using the GET method. When set to true, POST requests will be issued. In the case of POST requests, the request body will contain an argument token with the current value of LuCI.env.token by default, regardless of the parameters specified with args.
Deprecated
  • Yes
Source
Returns:
Returns the internally created function that has been passed to Request.poll.add(). This value can be passed to Poll.remove() to remove the polling request.
Type: 
function
post(url, argsopt, cb) → {Promise.<null>}
Issues a POST request to the given url and invokes the specified callback function. The function is a wrapper around Request.request(). The request is sent using application/x-www-form-urlencoded encoding and will contain a field token with the current value of LuCI.env.token by default.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
argsObject.<string, string><optional>
Additional post arguments to append to the request body.
cbLuCI.requestCallbackFn
The callback function to invoke when the request finishes.
Deprecated
  • Yes
Source
Returns:
Returns a promise resolving to null when concluded.
Type: 
Promise.<null>
raise(typeopt, fmtopt, …argsopt)
Captures the current stack trace and throws an error of the specified type as a new exception. Also logs the exception as an error to the debug console if it is available.
Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error
Either a string specifying the type of the error to throw or an existing Error instance to copy.
fmtstring<optional>
Unspecified error
A format string which is used to form the error message, together with all subsequent optional arguments.
args*<optional>
<repeatable>
Zero or more variable arguments to the supplied format string.
Source
Throws:
Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.
Type
Error
require(name, fromopt) → {Promise.<LuCI.baseclass>}
Load an additional LuCI JavaScript class and its dependencies, instantiate it and return the resulting class instance. Each class is only loaded once. Subsequent attempts to load the same class will return the already instantiated class.
Parameters:
NameTypeAttributesDefaultDescription
namestring
The name of the class to load in dotted notation. Dots will be replaced by spaces and joined with the runtime-determined base URL of LuCI.js to form an absolute URL to load the class file from.
fromArray.<string><optional>
[]
Optional dependency chain used during dependency resolution. This array contains the sequence of class names already being resolved (the caller stack). It is used to detect circular dependencies — if name appears in from a DependencyError is thrown.
Source
Throws:
  • Throws a DependencyError when the class to load includes circular dependencies.
    Type
    DependencyError
  • Throws NetworkError when the underlying LuCI.request call failed.
    Type
    NetworkError
  • Throws SyntaxError when the loaded class file code cannot be interpreted by eval.
    Type
    SyntaxError
  • Throws TypeError when the class file could be loaded and interpreted, but when invoking its code did not yield a valid class instance.
    Type
    TypeError
Returns:
Returns the instantiated class.
Type: 
Promise.<LuCI.baseclass>
resolveDefault(value, defvalue) → {Promise.<*>}
Returns a promise resolving with either the given value or with the given default in case the input value is a rejecting promise.
Parameters:
NameTypeDescription
value*
The value to resolve the promise with.
defvalue*
The default value to resolve the promise with in case the given input value is a rejecting promise.
Source
Returns:
Returns a new promise resolving either to the given input value or to the given default value on error.
Type: 
Promise.<*>
resource(…partsopt) → {string}
Construct a URL path relative to the global static resource path of the LuCI ui (usually /luci-static/resources).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
run() → {boolean}
Deprecated wrapper around Poll.start().
Deprecated
  • Yes
Source
Returns:
Returns true when the polling loop has been started or false when it was already running.
Type: 
boolean
sortedArray(val) → {Array.<*>}
Converts the given value to an array using toArray() if needed, performs a numerical sort using naturalCompare() and returns the result. If the input already is an array, no copy is being made and the sorting is performed in-place.
Parameters:
NameTypeDescription
val*
The input value to sort (and convert to an array if needed).
Source
See
  • toArray
  • naturalCompare
Returns:
Returns the resulting, numerically sorted array.
Type: 
Array.<*>
sortedKeys(obj, keyopt, sortmodeopt) → {Array.<string>}
Return an array of sorted object keys, optionally sorted by a different key or a different sorting mode.
Parameters:
NameTypeAttributesDescription
objobject
The object to extract the keys from. If the given value is not an object, the function will return an empty array.
keystring | null<optional>
Specifies the key to order by. This is mainly useful for nested objects of objects or objects of arrays when sorting shall not be performed by the primary object keys but by some other key pointing to a value within the nested values.
sortmode"addr" | "num"<optional>
Can be either addr or num to override the natural lexicographic sorting with a sorting suitable for IP/MAC style addresses or numeric values respectively.
Source
Returns:
Returns an array containing the sorted keys of the given object.
Type: 
Array.<string>
stop(entry) → {boolean}
Deprecated wrapper around Poll.remove().
Parameters:
NameTypeDescription
entryfunction
The polling function to remove.
Deprecated
  • Yes
Source
Returns:
Returns true when the function has been removed or false if it could not be found.
Type: 
boolean
toArray(val) → {Array.<*>}
Converts the given value to an array. If the given value is of type array, it is returned as-is, values of a type object are returned as one-element array containing the object, empty strings and null values are returned as an empty array, all other values are converted using String(), trimmed, split on white space and returned as an array.
Parameters:
NameTypeDescription
val*
The value to convert into an array.
Source
Returns:
Returns the resulting array.
Type: 
Array.<*>
url(…partsopt) → {string}
Construct a URL with a path relative to the script path of the server side LuCI application (usually /cgi-bin/luci).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
Type Definitions
requestCallbackFn(xhr, data, duration)
The request callback function is invoked whenever an HTTP reply to a request made using the L.get(), L.post() or L.poll() function is timed out or received successfully.
Parameters:
NameTypeDescription
xhrXMLHTTPRequest
The XMLHTTPRequest instance used to make the request.
data*
The response JSON if the response could be parsed as such, else null.
durationnumber
The total duration of the request in milliseconds.
Source

\ No newline at end of file
+    
On this page
LuCI
new LuCI(window, document, undefined)
This is the LuCI base class. It is automatically instantiated and accessible using the global L variable.
Parameters:
NameTypeDescription
windowWindow
The browser global window object.
documentDocument
The DOM document root for the current page.
undefinedundefined
Local undefined slot (prevents shadowing and ensures undefined is the real undefined value).
Properties
NameTypeDescription
envobject
The environment settings to use for the LuCI runtime.
Source
Classes
baseclass
dom
form
fs
headers
network
poll
request
response
rpc
session
uci
ui
validation
view
xhr
Namespaces
validation
Members
Class
Legacy L.Class class alias. New view code should use 'require baseclass'; to request the LuCI.baseclass class.
Deprecated
  • Yes
Source
Poll
Legacy L.Poll class alias. New view code should use 'require poll'; to request the LuCI.poll class.
Deprecated
  • Yes
Source
Request
Legacy L.Request class alias. New view code should use 'require request'; to request the LuCI.request class.
Deprecated
  • Yes
Source
dom
Legacy L.dom class alias. New view code should use 'require dom'; to request the LuCI.dom class.
Deprecated
  • Yes
Source
env
The env object holds environment settings used by LuCI, such as request timeouts, base URLs, etc.
Source
naturalCompare :function
Compares two values numerically and returns -1, 0, or 1 depending on whether the first value is smaller, equal to, or larger than the second one respectively.
This function is meant to be used as a comparator function for Array.sort().
Type:
  • function
Source
view
Legacy L.view class alias. New view code should use 'require view'; to request the LuCI.view class.
Deprecated
  • Yes
Source
Methods
bind(fn, self, …argsopt) → {function}
Return a bound function using the given self as this context and any further arguments as parameters to the bound function.
Parameters:
NameTypeAttributesDescription
fnfunction
The function to bind.
self*
The value to bind as this context to the specified function.
args*<optional>
<repeatable>
Zero or more variable arguments which are bound to the function as parameters.
Source
Returns:
Returns the bound function.
Type: 
function
error(typeopt, fmtopt, …argsopt)
A wrapper around raise() which also renders the error either as modal overlay when ui.js is already loaded or directly into the view body.
Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error
Either a string specifying the type of the error to throw or an existing Error instance to copy.
fmtstring<optional>
Unspecified error
A format string which is used to form the error message, together with all subsequent optional arguments.
args*<optional>
<repeatable>
Zero or more variable arguments to the supplied format string.
Source
Throws:
Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.
Type
Error
fspath(…partsopt) → {string}
Construct an absolute filesystem path relative to the server document root.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a path.
Source
Returns:
Return the joined path.
Type: 
string
get(url, argsopt, cb) → {Promise.<null>}
Issues a GET request to the given url and invokes the specified callback function. The function is a wrapper around Request.request().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
argsObject.<string, string><optional>
Additional query string arguments to append to the URL.
cbLuCI.requestCallbackFn
The callback function to invoke when the request finishes.
Deprecated
  • Yes
Source
Returns:
Returns a promise resolving to null when concluded.
Type: 
Promise.<null>
halt() → {boolean}
Deprecated wrapper around Poll.stop().
Deprecated
  • Yes
Source
Returns:
Returns true when the polling loop has been stopped or false when it didn't run to begin with.
Type: 
boolean
hasSystemFeature(feature, subfeatureopt) → {boolean|null}
Test whether a particular system feature is available, such as hostapd SAE support or an installed firewall. The features are queried once at the beginning of the LuCI session and cached in SessionStorage throughout the lifetime of the associated tab or browser window.
Parameters:
NameTypeAttributesDescription
featurestring
The feature to test. For a detailed list of known feature flags, see /modules/luci-base/root/usr/share/rpcd/ucode/luci.
subfeaturestring<optional>
Some feature classes like hostapd provide sub-feature flags, such as sae or 11w support. The subfeature argument can be used to query these.
Source
Returns:
Return true if the queried feature (and sub-feature) is available or false if the requested feature isn't present or known. Return null when a sub-feature was queried for a feature which has no sub-features.
Type: 
boolean | null
hasViewPermission() → {boolean|null}
Check whether a view has sufficient permissions.
Source
Returns:
Returns null if the current session has no permission at all to load resources required by the view. Returns false if readonly permissions are granted or true if at least one required ACL group is granted with write permissions.
Type: 
boolean | null
isArguments(valopt) → {boolean}
Tests whether the passed argument is a function arguments object.
Parameters:
NameTypeAttributesDescription
val*<optional>
The value to test
Source
Returns:
Returns true if the given value is a function arguments object, else returns false.
Type: 
boolean
isObject(valopt) → {boolean}
Tests whether the passed argument is a JavaScript object. This function is meant to be an object counterpart to the standard Array.isArray() function.
Parameters:
NameTypeAttributesDescription
val*<optional>
The value to test
Source
Returns:
Returns true if the given value is of a type object and not null, else returns false.
Type: 
boolean
location() → {string}
Return the complete URL path to the current view.
Source
Returns:
Returns the URL path to the current view.
Type: 
string
media(…partsopt) → {string}
Construct a URL path relative to the media resource path of the LuCI ui (usually /luci-static/$theme_name).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
path(prefixopt, …partsopt) → {string}
Construct a relative URL path from the given prefix and parts. The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
prefixstring<optional>
The prefix to join the given parts with. If the prefix is omitted, it defaults to an empty string.
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Return the joined URL path.
Type: 
string
poll(interval, url, argsopt, cb, postopt) → {function}
Register a polling HTTP request that invokes the specified callback function. The function is a wrapper around Request.poll.add().
Parameters:
NameTypeAttributesDefaultDescription
intervalnumber
The poll interval to use. If set to a value less than or equal to 0, it will default to the global poll interval configured in LuCI.env.pollinterval.
urlstring
The URL to request.
argsObject.<string, string><optional>
Specifies additional arguments for the request. For GET requests, the arguments are appended to the URL as query string, for POST requests, they'll be added to the request body.
cbLuCI.requestCallbackFn
The callback function to invoke whenever a request finishes.
postboolean<optional>
false
When set to false or not specified, poll requests will be made using the GET method. When set to true, POST requests will be issued. In the case of POST requests, the request body will contain an argument token with the current value of LuCI.env.token by default, regardless of the parameters specified with args.
Deprecated
  • Yes
Source
Returns:
Returns the internally created function that has been passed to Request.poll.add(). This value can be passed to Poll.remove() to remove the polling request.
Type: 
function
post(url, argsopt, cb) → {Promise.<null>}
Issues a POST request to the given url and invokes the specified callback function. The function is a wrapper around Request.request(). The request is sent using application/x-www-form-urlencoded encoding and will contain a field token with the current value of LuCI.env.token by default.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
argsObject.<string, string><optional>
Additional post arguments to append to the request body.
cbLuCI.requestCallbackFn
The callback function to invoke when the request finishes.
Deprecated
  • Yes
Source
Returns:
Returns a promise resolving to null when concluded.
Type: 
Promise.<null>
raise(typeopt, fmtopt, …argsopt)
Captures the current stack trace and throws an error of the specified type as a new exception. Also logs the exception as an error to the debug console if it is available.
Parameters:
NameTypeAttributesDefaultDescription
typeError | string<optional>
Error
Either a string specifying the type of the error to throw or an existing Error instance to copy.
fmtstring<optional>
Unspecified error
A format string which is used to form the error message, together with all subsequent optional arguments.
args*<optional>
<repeatable>
Zero or more variable arguments to the supplied format string.
Source
Throws:
Throws the created error object with the captured stack trace appended to the message and the type set to the given type argument or copied from the given error instance.
Type
Error
require(name, fromopt) → {Promise.<LuCI.baseclass>}
Load an additional LuCI JavaScript class and its dependencies, instantiate it and return the resulting class instance. Each class is only loaded once. Subsequent attempts to load the same class will return the already instantiated class.
Parameters:
NameTypeAttributesDefaultDescription
namestring
The name of the class to load in dotted notation. Dots will be replaced by spaces and joined with the runtime-determined base URL of LuCI.js to form an absolute URL to load the class file from.
fromArray.<string><optional>
[]
Optional dependency chain used during dependency resolution. This array contains the sequence of class names already being resolved (the caller stack). It is used to detect circular dependencies — if name appears in from a DependencyError is thrown.
Source
Throws:
  • Throws a DependencyError when the class to load includes circular dependencies.
    Type
    DependencyError
  • Throws NetworkError when the underlying LuCI.request call failed.
    Type
    NetworkError
  • Throws SyntaxError when the loaded class file code cannot be interpreted by eval.
    Type
    SyntaxError
  • Throws TypeError when the class file could be loaded and interpreted, but when invoking its code did not yield a valid class instance.
    Type
    TypeError
Returns:
Returns the instantiated class.
Type: 
Promise.<LuCI.baseclass>
resolveDefault(value, defvalue) → {Promise.<*>}
Returns a promise resolving with either the given value or with the given default in case the input value is a rejecting promise.
Parameters:
NameTypeDescription
value*
The value to resolve the promise with.
defvalue*
The default value to resolve the promise with in case the given input value is a rejecting promise.
Source
Returns:
Returns a new promise resolving either to the given input value or to the given default value on error.
Type: 
Promise.<*>
resource(…partsopt) → {string}
Construct a URL path relative to the global static resource path of the LuCI ui (usually /luci-static/resources).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
run() → {boolean}
Deprecated wrapper around Poll.start().
Deprecated
  • Yes
Source
Returns:
Returns true when the polling loop has been started or false when it was already running.
Type: 
boolean
sortedArray(val) → {Array.<*>}
Converts the given value to an array using toArray() if needed, performs a numerical sort using naturalCompare() and returns the result. If the input already is an array, no copy is being made and the sorting is performed in-place.
Parameters:
NameTypeDescription
val*
The input value to sort (and convert to an array if needed).
Source
See
  • toArray
  • naturalCompare
Returns:
Returns the resulting, numerically sorted array.
Type: 
Array.<*>
sortedKeys(obj, keyopt, sortmodeopt) → {Array.<string>}
Return an array of sorted object keys, optionally sorted by a different key or a different sorting mode.
Parameters:
NameTypeAttributesDescription
objobject
The object to extract the keys from. If the given value is not an object, the function will return an empty array.
keystring | null<optional>
Specifies the key to order by. This is mainly useful for nested objects of objects or objects of arrays when sorting shall not be performed by the primary object keys but by some other key pointing to a value within the nested values.
sortmode"addr" | "num"<optional>
Can be either addr or num to override the natural lexicographic sorting with a sorting suitable for IP/MAC style addresses or numeric values respectively.
Source
Returns:
Returns an array containing the sorted keys of the given object.
Type: 
Array.<string>
stop(entry) → {boolean}
Deprecated wrapper around Poll.remove().
Parameters:
NameTypeDescription
entryfunction
The polling function to remove.
Deprecated
  • Yes
Source
Returns:
Returns true when the function has been removed or false if it could not be found.
Type: 
boolean
toArray(val) → {Array.<*>}
Converts the given value to an array. If the given value is of type array, it is returned as-is, values of a type object are returned as one-element array containing the object, empty strings and null values are returned as an empty array, all other values are converted using String(), trimmed, split on white space and returned as an array.
Parameters:
NameTypeDescription
val*
The value to convert into an array.
Source
Returns:
Returns the resulting array.
Type: 
Array.<*>
url(…partsopt) → {string}
Construct a URL with a path relative to the script path of the server side LuCI application (usually /cgi-bin/luci).
The resulting URL is guaranteed to contain only the characters a-z, A-Z, 0-9, _, ., %, ,, ;, and - as well as / for the path separator. Suffixing '?x=y&foo=bar' URI parameters also limited to the aforementioned characters is permissible.
Parameters:
NameTypeAttributesDescription
partsstring<optional>
<repeatable>
An array of parts to join into a URL path. Parts may contain slashes and any of the other characters mentioned above.
Source
Returns:
Returns the resulting URL path.
Type: 
string
Type Definitions
requestCallbackFn(xhr, data, duration)
The request callback function is invoked whenever an HTTP reply to a request made using the L.get(), L.post() or L.poll() function is timed out or received successfully.
Parameters:
NameTypeDescription
xhrXMLHTTPRequest
The XMLHTTPRequest instance used to make the request.
data*
The response JSON if the response could be parsed as such, else null.
durationnumber
The total duration of the request in milliseconds.
Source

\ No newline at end of file
diff --git a/jsapi/LuCI.poll.html b/jsapi/LuCI.poll.html
index 69000a8f62..033686a1a6 100644
--- a/jsapi/LuCI.poll.html
+++ b/jsapi/LuCI.poll.html
@@ -1,3 +1,3 @@
 Class: poll
On this page
LuCI. poll
The Poll class allows registering and unregistering poll actions, as well as starting, stopping, and querying the state of the polling loop.
Source
Methods
active() → {boolean}
Test whether the polling loop is running.
Source
Returns:
  • Returns true if polling is active, else false.
Type: 
boolean
add(fn, interval) → {boolean}
Add a new operation to the polling loop. If the polling loop is not already started at this point, it will be implicitly started.
Parameters:
NameTypeDescription
fnfunction
The function to invoke on each poll interval.
intervalnumber
The poll interval in seconds.
Source
Throws:
Throws TypeError when an invalid interval was passed.
Type
TypeError
Returns:
Returns true if the function has been added or false if it already is registered.
Type: 
boolean
remove(fn) → {boolean}
Remove an operation from the polling loop. If no further operations are registered, the polling loop is implicitly stopped.
Parameters:
NameTypeDescription
fnfunction
The function to remove.
Source
Throws:
Throws TypeError when the given argument isn't a function.
Type
TypeError
Returns:
Returns true if the function has been removed or false if it wasn't found.
Type: 
boolean
start() → {boolean}
(Re)start the polling loop. Dispatches a custom poll-start event to the document object upon successful start.
Source
Returns:
Returns true if polling has been started (or if no functions where registered) or false when the polling loop already runs.
Type: 
boolean
stop() → {boolean}
Stop the polling loop. Dispatches a custom poll-stop event to the document object upon successful stop.
Source
Returns:
Returns true if polling has been stopped or false if it didn't run to begin with.
Type: 
boolean

\ No newline at end of file
+    
On this page
LuCI. poll
The Poll class allows registering and unregistering poll actions, as well as starting, stopping, and querying the state of the polling loop.
Source
Methods
active() → {boolean}
Test whether the polling loop is running.
Source
Returns:
  • Returns true if polling is active, else false.
Type: 
boolean
add(fn, interval) → {boolean}
Add a new operation to the polling loop. If the polling loop is not already started at this point, it will be implicitly started.
Parameters:
NameTypeDescription
fnfunction
The function to invoke on each poll interval.
intervalnumber
The poll interval in seconds.
Source
Throws:
Throws TypeError when an invalid interval was passed.
Type
TypeError
Returns:
Returns true if the function has been added or false if it already is registered.
Type: 
boolean
remove(fn) → {boolean}
Remove an operation from the polling loop. If no further operations are registered, the polling loop is implicitly stopped.
Parameters:
NameTypeDescription
fnfunction
The function to remove.
Source
Throws:
Throws TypeError when the given argument isn't a function.
Type
TypeError
Returns:
Returns true if the function has been removed or false if it wasn't found.
Type: 
boolean
start() → {boolean}
(Re)start the polling loop. Dispatches a custom poll-start event to the document object upon successful start.
Source
Returns:
Returns true if polling has been started (or if no functions where registered) or false when the polling loop already runs.
Type: 
boolean
stop() → {boolean}
Stop the polling loop. Dispatches a custom poll-stop event to the document object upon successful stop.
Source
Returns:
Returns true if polling has been stopped or false if it didn't run to begin with.
Type: 
boolean

\ No newline at end of file
diff --git a/jsapi/LuCI.request.html b/jsapi/LuCI.request.html
index 1c333fc83b..35553a1b66 100644
--- a/jsapi/LuCI.request.html
+++ b/jsapi/LuCI.request.html
@@ -1,3 +1,3 @@
 Class: request
On this page
LuCI. request
The Request class allows initiating HTTP requests and provides utilities for dealing with responses.
Source
Classes
poll
Methods
addInterceptor(interceptorFn) → {LuCI.request.interceptorFn}
Register an HTTP response interceptor function. Interceptor functions are useful to perform default actions on incoming HTTP responses, such as checking for expired authentication or for implementing request retries before returning a failure.
Parameters:
NameTypeDescription
interceptorFnLuCI.request.interceptorFn
The interceptor function to register.
Source
Returns:
The registered function.
Type: 
LuCI.request.interceptorFn
expandURL(url) → {string}
Turn the given relative URL into an absolute URL if necessary.
Parameters:
NameTypeDescription
urlstring
The URL to convert.
Source
Returns:
The absolute URL derived from the given one, or the original URL if it already was absolute.
Type: 
string
get(url, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP GET request to the given target.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
handleReadyStateChange(resolveFn, rejectFn, evopt) → {void}
Handle XHR readyState changes for an in-flight request and resolve or reject the originating promise.
Parameters:
NameTypeAttributesDescription
resolveFnfunction
Callback invoked on success with the constructed LuCI.response.
rejectFnfunction
Callback invoked on failure or abort with an Error instance.
evEvent<optional>
The XHR readystatechange event (optional).
Source
Returns:
No return value; the function resolves or rejects the supplied callbacks.
Type: 
void
post(url, dataopt, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP POST request to the given target.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
data*<optional>
The request data to send, see LuCI.request.RequestOptions for details.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
removeInterceptor(interceptorFn) → {boolean}
Remove an HTTP response interceptor function. The passed function value must be the very same value that was used to register the function.
Parameters:
NameTypeDescription
interceptorFnLuCI.request.interceptorFn
The interceptor function to remove.
Source
Returns:
Returns true if any function has been removed, else false.
Type: 
boolean
request(target, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP request to the given target.
Parameters:
NameTypeAttributesDescription
targetstring
The URL to request.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
Type Definitions
RequestOptions
Type:
  • Object
Properties
NameTypeAttributesDefaultDescription
methodstring<optional>
GET
The HTTP method to use, e.g. GET or POST.
queryObject.<string, (Object|string)><optional>
Query string data to append to the URL. Non-string values of the given object will be converted to JSON.
cacheboolean<optional>
false
Specifies whether the HTTP response may be retrieved from cache.
usernamestring<optional>
Provides a username for HTTP basic authentication.
passwordstring<optional>
Provides a password for HTTP basic authentication.
timeoutnumber<optional>
Specifies the request timeout in milliseconds.
credentialsboolean<optional>
false
Whether to include credentials such as cookies in the request.
responseTypestring<optional>
text
Overrides the request response type. Valid values or text to interpret the response as UTF-8 string or blob to handle the response as binary Blob data.
content*<optional>
Specifies the HTTP message body to send along with the request. If the value is a function, it is invoked and the return value used as content, if it is a FormData instance, it is used as-is, if it is an object, it will be converted to JSON, in all other cases it is converted to a string.
headerObject.<string, string><optional>
Specifies HTTP headers to set for the request.
progressfunction<optional>
An optional request callback function which receives ProgressEvent instances as sole argument during the HTTP request transfer.
responseProgressfunction<optional>
An optional request callback function which receives ProgressEvent instances as sole argument during the HTTP response transfer.
Source
interceptorFn(res)
Interceptor functions are invoked whenever an HTTP reply is received, in the order these functions have been registered.
Parameters:
NameTypeDescription
resLuCI.response
The HTTP response object
Source

\ No newline at end of file
+    
On this page
LuCI. request
The Request class allows initiating HTTP requests and provides utilities for dealing with responses.
Source
Classes
poll
Methods
addInterceptor(interceptorFn) → {LuCI.request.interceptorFn}
Register an HTTP response interceptor function. Interceptor functions are useful to perform default actions on incoming HTTP responses, such as checking for expired authentication or for implementing request retries before returning a failure.
Parameters:
NameTypeDescription
interceptorFnLuCI.request.interceptorFn
The interceptor function to register.
Source
Returns:
The registered function.
Type: 
LuCI.request.interceptorFn
expandURL(url) → {string}
Turn the given relative URL into an absolute URL if necessary.
Parameters:
NameTypeDescription
urlstring
The URL to convert.
Source
Returns:
The absolute URL derived from the given one, or the original URL if it already was absolute.
Type: 
string
get(url, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP GET request to the given target.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
handleReadyStateChange(resolveFn, rejectFn, evopt) → {void}
Handle XHR readyState changes for an in-flight request and resolve or reject the originating promise.
Parameters:
NameTypeAttributesDescription
resolveFnfunction
Callback invoked on success with the constructed LuCI.response.
rejectFnfunction
Callback invoked on failure or abort with an Error instance.
evEvent<optional>
The XHR readystatechange event (optional).
Source
Returns:
No return value; the function resolves or rejects the supplied callbacks.
Type: 
void
post(url, dataopt, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP POST request to the given target.
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request.
data*<optional>
The request data to send, see LuCI.request.RequestOptions for details.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
removeInterceptor(interceptorFn) → {boolean}
Remove an HTTP response interceptor function. The passed function value must be the very same value that was used to register the function.
Parameters:
NameTypeDescription
interceptorFnLuCI.request.interceptorFn
The interceptor function to remove.
Source
Returns:
Returns true if any function has been removed, else false.
Type: 
boolean
request(target, optionsopt) → {Promise.<LuCI.response>}
Initiate an HTTP request to the given target.
Parameters:
NameTypeAttributesDescription
targetstring
The URL to request.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
Source
Returns:
The resulting HTTP response.
Type: 
Promise.<LuCI.response>
Type Definitions
RequestOptions
Type:
  • Object
Properties
NameTypeAttributesDefaultDescription
methodstring<optional>
GET
The HTTP method to use, e.g. GET or POST.
queryObject.<string, (Object|string)><optional>
Query string data to append to the URL. Non-string values of the given object will be converted to JSON.
cacheboolean<optional>
false
Specifies whether the HTTP response may be retrieved from cache.
usernamestring<optional>
Provides a username for HTTP basic authentication.
passwordstring<optional>
Provides a password for HTTP basic authentication.
timeoutnumber<optional>
Specifies the request timeout in milliseconds.
credentialsboolean<optional>
false
Whether to include credentials such as cookies in the request.
responseTypestring<optional>
text
Overrides the request response type. Valid values or text to interpret the response as UTF-8 string or blob to handle the response as binary Blob data.
content*<optional>
Specifies the HTTP message body to send along with the request. If the value is a function, it is invoked and the return value used as content, if it is a FormData instance, it is used as-is, if it is an object, it will be converted to JSON, in all other cases it is converted to a string.
headerObject.<string, string><optional>
Specifies HTTP headers to set for the request.
progressfunction<optional>
An optional request callback function which receives ProgressEvent instances as sole argument during the HTTP request transfer.
responseProgressfunction<optional>
An optional request callback function which receives ProgressEvent instances as sole argument during the HTTP response transfer.
Source
interceptorFn(res)
Interceptor functions are invoked whenever an HTTP reply is received, in the order these functions have been registered.
Parameters:
NameTypeDescription
resLuCI.response
The HTTP response object
Source

\ No newline at end of file
diff --git a/jsapi/LuCI.request.poll.html b/jsapi/LuCI.request.poll.html
index 502385d754..05a32625ae 100644
--- a/jsapi/LuCI.request.poll.html
+++ b/jsapi/LuCI.request.poll.html
@@ -1,3 +1,3 @@
 Class: poll
On this page
LuCI.request. poll
The Request.poll class provides some convenience wrappers around LuCI.poll mainly to simplify registering repeating HTTP request calls as polling functions.
Source
Methods
active() → {boolean}
Alias for LuCI.poll.active().
Source
Returns:
Type: 
boolean
add(interval, url, optionsopt, callbackopt) → {function}
Register a repeating HTTP request with an optional callback to invoke whenever a response for the request is received.
Parameters:
NameTypeAttributesDescription
intervalnumber
The poll interval in seconds.
urlstring
The URL to request on each poll.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
callbackLuCI.request.poll.callbackFn<optional>
Callback function to invoke for each HTTP reply.
Source
Throws:
Throws TypeError when an invalid interval was passed.
Type
TypeError
Returns:
Returns the internally created poll function.
Type: 
function
remove(entry) → {boolean}
Remove a polling request that has been previously added using add(). This function is essentially a wrapper around LuCI.poll.remove().
Parameters:
NameTypeDescription
entryfunction
The poll function returned by add().
Source
Returns:
Returns true if any function has been removed, else false.
Type: 
boolean
start() → {boolean}
Alias for LuCI.poll.start().
Source
Returns:
Type: 
boolean
stop() → {boolean}
Alias for LuCI.poll.stop().
Source
Returns:
Type: 
boolean
Type Definitions
callbackFn(res, data, duration)
The callback function is invoked whenever an HTTP reply to a polled request is received or when the polled request timed out.
Parameters:
NameTypeDescription
resLuCI.response
The HTTP response object.
data*
The response JSON if the response could be parsed as such, else null.
durationnumber
The total duration of the request in milliseconds.
Source

\ No newline at end of file
+    
On this page
LuCI.request. poll
The Request.poll class provides some convenience wrappers around LuCI.poll mainly to simplify registering repeating HTTP request calls as polling functions.
Source
Methods
active() → {boolean}
Alias for LuCI.poll.active().
Source
Returns:
Type: 
boolean
add(interval, url, optionsopt, callbackopt) → {function}
Register a repeating HTTP request with an optional callback to invoke whenever a response for the request is received.
Parameters:
NameTypeAttributesDescription
intervalnumber
The poll interval in seconds.
urlstring
The URL to request on each poll.
optionsLuCI.request.RequestOptions<optional>
Additional options to configure the request.
callbackLuCI.request.poll.callbackFn<optional>
Callback function to invoke for each HTTP reply.
Source
Throws:
Throws TypeError when an invalid interval was passed.
Type
TypeError
Returns:
Returns the internally created poll function.
Type: 
function
remove(entry) → {boolean}
Remove a polling request that has been previously added using add(). This function is essentially a wrapper around LuCI.poll.remove().
Parameters:
NameTypeDescription
entryfunction
The poll function returned by add().
Source
Returns:
Returns true if any function has been removed, else false.
Type: 
boolean
start() → {boolean}
Alias for LuCI.poll.start().
Source
Returns:
Type: 
boolean
stop() → {boolean}
Alias for LuCI.poll.stop().
Source
Returns:
Type: 
boolean
Type Definitions
callbackFn(res, data, duration)
The callback function is invoked whenever an HTTP reply to a polled request is received or when the polled request timed out.
Parameters:
NameTypeDescription
resLuCI.response
The HTTP response object.
data*
The response JSON if the response could be parsed as such, else null.
durationnumber
The total duration of the request in milliseconds.
Source

\ No newline at end of file
diff --git a/jsapi/LuCI.session.html b/jsapi/LuCI.session.html
index ad67d3fadc..3be6f0ee30 100644
--- a/jsapi/LuCI.session.html
+++ b/jsapi/LuCI.session.html
@@ -1,3 +1,3 @@
 Class: session
On this page
LuCI. session
The session class provides various session related functionality.
Source
Methods
getID() → {string}
Retrieve the current session ID.
Source
Returns:
Returns the current session ID.
Type: 
string
getLocalData(keyopt) → {*}
Retrieve data from the local session storage.
Parameters:
NameTypeAttributesDescription
keystring<optional>
The key to retrieve from the session data store. If omitted, all session data will be returned.
Source
Returns:
Returns the stored session data or null if the given key wasn't found.
Type: 
*
getToken() → {string|null}
Retrieve the current session token.
Source
Returns:
Returns the current session token or null if not logged in.
Type: 
string | null
setLocalData(key, value) → {boolean}
Set data in the local session storage.
Parameters:
NameTypeDescription
keystring
The key to set in the session data store.
value*
The value to store. It will be internally converted to JSON before being put in the session store.
Source
Returns:
Returns true if the data could be stored or false on error.
Type: 
boolean

\ No newline at end of file
+    
On this page
LuCI. session
The session class provides various session related functionality.
Source
Methods
getID() → {string}
Retrieve the current session ID.
Source
Returns:
Returns the current session ID.
Type: 
string
getLocalData(keyopt) → {*}
Retrieve data from the local session storage.
Parameters:
NameTypeAttributesDescription
keystring<optional>
The key to retrieve from the session data store. If omitted, all session data will be returned.
Source
Returns:
Returns the stored session data or null if the given key wasn't found.
Type: 
*
getToken() → {string|null}
Retrieve the current session token.
Source
Returns:
Returns the current session token or null if not logged in.
Type: 
string | null
setLocalData(key, value) → {boolean}
Set data in the local session storage.
Parameters:
NameTypeDescription
keystring
The key to set in the session data store.
value*
The value to store. It will be internally converted to JSON before being put in the session store.
Source
Returns:
Returns true if the data could be stored or false on error.
Type: 
boolean

\ No newline at end of file
diff --git a/jsapi/LuCI.view.html b/jsapi/LuCI.view.html
index 02fb41ae39..f84cdef866 100644
--- a/jsapi/LuCI.view.html
+++ b/jsapi/LuCI.view.html
@@ -1,3 +1,3 @@
 Class: view
On this page
LuCI. view
The view class forms the basis of views and provides a standard set of methods to inherit from.
Source
Methods
addFooter() → {DocumentFragment}
Renders a standard page action footer if any of the handleSave(), handleSaveApply() or handleReset() functions are defined.
The default implementation should be sufficient for most views - it will render a standard page footer with action buttons labeled Save, Save & Apply and Reset triggering the handleSave(), handleSaveApply() and handleReset() functions respectively.
When any of these handle*() functions is overwritten with null by a view extending this class, the corresponding button will not be rendered.
Source
Returns:
Returns a DocumentFragment containing the footer bar with buttons for each corresponding handle*() action or an empty DocumentFragment if all three handle*() methods are overwritten with null.
Type: 
DocumentFragment
handleReset(ev) → {*|Promise.<*>}
The handleReset function is invoked when the user clicks the Reset button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will iterate all forms present in the view and invoke the Map.reset() method on each form.
Views not using Map instances or requiring other special logic should overwrite handleReset() with a custom implementation.
To disable the Reset page footer button, views extending this base class should overwrite the handleReset function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
handleSave(ev) → {*|Promise.<*>}
The handleSave function is invoked when the user clicks the Save button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will iterate all forms present in the view and invoke the Map.save() method on each form.
Views not using Map instances or requiring other special logic should overwrite handleSave() with a custom implementation.
To disable the Save page footer button, views extending this base class should overwrite the handleSave function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
handleSaveApply(ev, mode) → {*|Promise.<*>}
The handleSaveApply function is invoked when the user clicks the Save & Apply button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will first invoke view.handleSave() and then call ui.changes.apply() to start the modal config apply and page reload flow.
Views not using Map instances or requiring other special logic should overwrite handleSaveApply() with a custom implementation.
To disable the Save & Apply page footer button, views extending this base class should overwrite the handleSaveApply function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
modenumber
Whether to apply the changes checked.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
(abstract) load() → {*|Promise.<*>}
The load function is invoked before the view is rendered.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
The return value of the function (or the resolved values of the promise returned by it) will be passed as the first argument to render().
This function is supposed to be overwritten by subclasses, the default implementation does nothing.
Source
Returns:
May return any value or a Promise resolving to any value.
Type: 
* | Promise.<*>
(abstract) render(load_results) → {Node|Promise.<Node>}
The render function is invoked after the load() function and responsible for setting up the view contents. It must return a DOM Node or DocumentFragment holding the contents to insert into the view area.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
The return value of the function (or the resolved values of the promise returned by it) will be inserted into the main content area using dom.append().
This function is supposed to be overwritten by subclasses, the default implementation does nothing.
Parameters:
NameTypeDescription
load_results* | null
This function will receive the return value of the view.load() function as first argument.
Source
Returns:
Should return a DOM Node value or a Promise resolving to a Node value.
Type: 
Node | Promise.<Node>

\ No newline at end of file
+    
On this page
LuCI. view
The view class forms the basis of views and provides a standard set of methods to inherit from.
Source
Methods
addFooter() → {DocumentFragment}
Renders a standard page action footer if any of the handleSave(), handleSaveApply() or handleReset() functions are defined.
The default implementation should be sufficient for most views - it will render a standard page footer with action buttons labeled Save, Save & Apply and Reset triggering the handleSave(), handleSaveApply() and handleReset() functions respectively.
When any of these handle*() functions is overwritten with null by a view extending this class, the corresponding button will not be rendered.
Source
Returns:
Returns a DocumentFragment containing the footer bar with buttons for each corresponding handle*() action or an empty DocumentFragment if all three handle*() methods are overwritten with null.
Type: 
DocumentFragment
handleReset(ev) → {*|Promise.<*>}
The handleReset function is invoked when the user clicks the Reset button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will iterate all forms present in the view and invoke the Map.reset() method on each form.
Views not using Map instances or requiring other special logic should overwrite handleReset() with a custom implementation.
To disable the Reset page footer button, views extending this base class should overwrite the handleReset function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
handleSave(ev) → {*|Promise.<*>}
The handleSave function is invoked when the user clicks the Save button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will iterate all forms present in the view and invoke the Map.save() method on each form.
Views not using Map instances or requiring other special logic should overwrite handleSave() with a custom implementation.
To disable the Save page footer button, views extending this base class should overwrite the handleSave function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
handleSaveApply(ev, mode) → {*|Promise.<*>}
The handleSaveApply function is invoked when the user clicks the Save & Apply button in the page action footer.
The default implementation should be sufficient for most views using form.Map() based forms - it will first invoke view.handleSave() and then call ui.changes.apply() to start the modal config apply and page reload flow.
Views not using Map instances or requiring other special logic should overwrite handleSaveApply() with a custom implementation.
To disable the Save & Apply page footer button, views extending this base class should overwrite the handleSaveApply function with null.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
Parameters:
NameTypeDescription
evEvent
The DOM event that triggered the function.
modenumber
Whether to apply the changes checked.
Source
Returns:
Any return values of this function are discarded, but passed through Promise.resolve() to ensure that any returned promise runs to completion before the button is re-enabled.
Type: 
* | Promise.<*>
(abstract) load() → {*|Promise.<*>}
The load function is invoked before the view is rendered.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
The return value of the function (or the resolved values of the promise returned by it) will be passed as the first argument to render().
This function is supposed to be overwritten by subclasses, the default implementation does nothing.
Source
Returns:
May return any value or a Promise resolving to any value.
Type: 
* | Promise.<*>
(abstract) render(load_results) → {Node|Promise.<Node>}
The render function is invoked after the load() function and responsible for setting up the view contents. It must return a DOM Node or DocumentFragment holding the contents to insert into the view area.
The invocation of this function is wrapped by Promise.resolve() so it may return Promises if needed.
The return value of the function (or the resolved values of the promise returned by it) will be inserted into the main content area using dom.append().
This function is supposed to be overwritten by subclasses, the default implementation does nothing.
Parameters:
NameTypeDescription
load_results* | null
This function will receive the return value of the view.load() function as first argument.
Source
Returns:
Should return a DOM Node value or a Promise resolving to a Node value.
Type: 
Node | Promise.<Node>

\ No newline at end of file
diff --git a/jsapi/LuCI.xhr.html b/jsapi/LuCI.xhr.html
index 0ac44dff31..0510f4e629 100644
--- a/jsapi/LuCI.xhr.html
+++ b/jsapi/LuCI.xhr.html
@@ -1,3 +1,3 @@
 Class: xhr
On this page
LuCI. xhr
The LuCI.xhr class is a legacy compatibility shim for the functionality formerly provided by xhr.js. It is registered as a global window.XHR symbol for compatibility with legacy code.
New code should use LuCI.request instead to implement HTTP request handling.
Constructor
new xhr()
Deprecated
  • Yes
Source
Methods
abort()
Ignored for backwards compatibility.
This function does nothing.
Deprecated
  • Yes
Source
busy() → {boolean}
Checks the running state of the request.
Deprecated
  • Yes
Source
Returns:
Returns true if the request is still running or false if it already completed.
Type: 
boolean
cancel()
Cancels a running request.
This function does not actually cancel the underlying XMLHTTPRequest request but it sets a flag which prevents the invocation of the callback function when the request eventually finishes or timed out.
Deprecated
  • Yes
Source
get(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.get().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request
dataObject<optional>
Additional query string data
callbackLuCI.requestCallbackFn<optional>
Callback function to invoke on completion
timeoutnumber<optional>
Request timeout to use
Deprecated
  • Yes
Source
Returns:
Type: 
Promise.<null>
post(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.post().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request
dataObject<optional>
Additional data to append to the request body.
callbackLuCI.requestCallbackFn<optional>
Callback function to invoke on completion
timeoutnumber<optional>
Request timeout to use
Deprecated
  • Yes
Source
Returns:
Type: 
Promise.<null>
send_form()
Existing for backwards compatibility.
This function simply throws an InternalError when invoked.
Deprecated
  • Yes
Source
Throws:
Throws an InternalError with the message Not implemented when invoked.
Type
InternalError

\ No newline at end of file
+    
On this page
LuCI. xhr
The LuCI.xhr class is a legacy compatibility shim for the functionality formerly provided by xhr.js. It is registered as a global window.XHR symbol for compatibility with legacy code.
New code should use LuCI.request instead to implement HTTP request handling.
Constructor
new xhr()
Deprecated
  • Yes
Source
Methods
abort()
Ignored for backwards compatibility.
This function does nothing.
Deprecated
  • Yes
Source
busy() → {boolean}
Checks the running state of the request.
Deprecated
  • Yes
Source
Returns:
Returns true if the request is still running or false if it already completed.
Type: 
boolean
cancel()
Cancels a running request.
This function does not actually cancel the underlying XMLHTTPRequest request but it sets a flag which prevents the invocation of the callback function when the request eventually finishes or timed out.
Deprecated
  • Yes
Source
get(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.get().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request
dataObject<optional>
Additional query string data
callbackLuCI.requestCallbackFn<optional>
Callback function to invoke on completion
timeoutnumber<optional>
Request timeout to use
Deprecated
  • Yes
Source
Returns:
Type: 
Promise.<null>
post(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.post().
Parameters:
NameTypeAttributesDescription
urlstring
The URL to request
dataObject<optional>
Additional data to append to the request body.
callbackLuCI.requestCallbackFn<optional>
Callback function to invoke on completion
timeoutnumber<optional>
Request timeout to use
Deprecated
  • Yes
Source
Returns:
Type: 
Promise.<null>
send_form()
Existing for backwards compatibility.
This function simply throws an InternalError when invoked.
Deprecated
  • Yes
Source
Throws:
Throws an InternalError with the message Not implemented when invoked.
Type
InternalError

\ No newline at end of file
diff --git a/jsapi/form.js.html b/jsapi/form.js.html
index e66106e9ae..0eac27937b 100644
--- a/jsapi/form.js.html
+++ b/jsapi/form.js.html
@@ -754,18 +754,15 @@ const CBIMap = CBIAbstractElement.extend(/** @lends LuCI.form.Map.prototype */ {
 	 * @param {Event} ev
 	 * @param {number} n
 	 */
-	checkDepends(ev, n, cache) {
-		if (cache == null)
-			cache = Object.create(null);
-
+	checkDepends(ev, n) {
 		let changed = false;
 
 		for (let i = 0, s = this.children[0]; (s = this.children[i]) != null; i++)
-			if (s.checkDepends(ev, n, cache))
+			if (s.checkDepends(ev, n))
 				changed = true;
 
 		if (changed && (n ?? 0) < 10)
-			this.checkDepends(ev, (n ?? 0) + 1, cache);
+			this.checkDepends(ev, (n ?? 10) + 1);
 
 		ui.tabs.updateTabs(ev, this.root);
 	},
@@ -777,12 +774,9 @@ const CBIMap = CBIAbstractElement.extend(/** @lends LuCI.form.Map.prototype */ {
 	 * @param {string} section_id
 	 * @returns {boolean}
 	 */
-	isDependencySatisfied(depends, config_name, section_id, cache) {
+	isDependencySatisfied(depends, config_name, section_id) {
 		let def = false;
 
-		if (cache == null)
-			cache = Object.create(null);
-
 		if (!Array.isArray(depends) || !depends.length)
 			return true;
 
@@ -800,17 +794,8 @@ const CBIMap = CBIAbstractElement.extend(/** @lends LuCI.form.Map.prototype */ {
 					istat = false;
 				}
 				else {
-					const key = `${config_name}::${section_id}::${dep}`;
-					let val;
-
-					if (key in cache) {
-						val = cache[key];
-					}
-					else {
-						const res = this.lookupOption(dep, section_id, config_name);
-						val = (res && res[0].isActive(res[1])) ? res[0].formvalue(res[1]) : null;
-						cache[key] = val;
-					}
+					const res = this.lookupOption(dep, section_id, config_name);
+					const val = (res && res[0].isActive(res[1])) ? res[0].formvalue(res[1]) : null;
 
 					const equal = contains
 						? isContained(val, depends[i][dep])
@@ -1799,9 +1784,9 @@ const CBIAbstractValue = CBIAbstractElement.extend(/** @lends LuCI.form.Abstract
 	 * @param {string} section_id
 	 * @returns {boolean}
 	 */
-	checkDepends(section_id, cache) {
+	checkDepends(section_id) {
 		const config_name = this.uciconfig ?? this.section.uciconfig ?? this.map.config;
-		const active = this.map.isDependencySatisfied(this.deps, config_name, section_id, cache);
+		const active = this.map.isDependencySatisfied(this.deps, config_name, section_id);
 
 		if (active)
 			this.updateDefaultValue(section_id);
@@ -5175,7 +5160,6 @@ const CBIFlagValue = CBIValue.extend(/** @lends LuCI.form.Flag.prototype */ {
 		else if (!this.retain) {
 			return Promise.resolve(this.remove(section_id));
 		}
-		return Promise.resolve();
 	},
 });
 
@@ -6113,9 +6097,9 @@ const CBISectionValue = CBIValue.extend(/** @lends LuCI.form.SectionValue.protot
 	 * @param {string} section_id
 	 * @returns {null}
 	 */
-	checkDepends(section_id, cache) {
-		this.subsection.checkDepends(section_id, cache);
-		return CBIValue.prototype.checkDepends.apply(this, [ section_id, cache ]);
+	checkDepends(section_id) {
+		this.subsection.checkDepends(section_id);
+		return CBIValue.prototype.checkDepends.apply(this, [ section_id ]);
 	},
 
 	/**
diff --git a/jsapi/global.html b/jsapi/global.html
index 25c3b0d61d..0179367b7c 100644
--- a/jsapi/global.html
+++ b/jsapi/global.html
@@ -1,3 +1,3 @@
 Global
On this page
Methods
add(a, n) → {Array.<number>}
Add a small integer to a 64-bit value represented as four 16-bit words.
Treats a as a little-endian 64-bit value (4 × 16-bit words). Adds the integer n to the least-significant word and propagates carry across subsequent 16-bit words. The result is truncated to 64 bits and returned as a 4-element array of 16-bit words (little-endian).
Parameters:
NameTypeDescription
aArray.<number>
Addend as 4 × 16-bit words (little-endian)
nnumber
Value to add (integer carry)
Source
Returns:
Sum as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
calculateBroadcast(s, use_cfgvalue) → {string}
Calculate the broadcast IP for a given IP.
Parameters:
NameTypeDescription
sNode
the ui element to test.
use_cfgvalueboolean
whether to use the config or form value.
Source
Returns:
Type: 
string
derive_color(string) → {string}
Derive a deterministic hex color from an input string.
The color is produced by seeding the PRNG from a string-derived hash and producing RGB components. Returns a #rrggbb hex string.
Parameters:
NameTypeDescription
stringstring
Input string used to derive the color
Source
Returns:
Hex color string in #rrggbb format
Type: 
string
get(loweropt, upperopt) → {number}
Return a pseudo-random value.
Overloads:
  • get() -> number in [0, 1]
  • get(upper) -> integer in [1, upper]
  • get(lower, upper) -> integer in [lower, upper]
Parameters:
NameTypeAttributesDefaultDescription
lowernumber<optional>
0
Lower bound (when two args supplied)
uppernumber<optional>
0
Upper bound (when one or two args supplied)
Source
Returns:
Random value (float in [0,1] or integer in requested range)
Type: 
number
getColorForName(forNamenullable) → {string}
Generate a colour for a name.
Parameters:
NameTypeAttributesDescription
forNamestring<nullable>
Source
Returns:
Type: 
string
getDevices(network) → {Array.<string>}
Get bridge devices or Layer 3 devices of a network object.
Parameters:
NameTypeDescription
networkobject
Source
Returns:
Type: 
Array.<string>
getGroups() → {Array.<string>}
Get users found in /etc/group.
Source
Returns:
Type: 
Array.<string>
getUsers() → {Array.<string>}
Get users found in /etc/passwd.
Source
Returns:
Type: 
Array.<string>
handleCgiIoReply(res) → {string}
Handle a CGI-IO reply.
Parameters:
NameTypeDescription
resobject
Source
Throws:
Error
Returns:
Type: 
string
handleRpcReply(expect, rc) → {number}
Handle an RPC reply.
Parameters:
NameTypeDescription
expectobject
rcnumber
Source
Throws:
Error
Returns:
Type: 
number
initFirewallState() → {Promise}
Load the firewall configuration.
Source
Returns:
Type: 
Promise
int() → {number}
Produce the next PRNG 32-bit integer.
Advances the internal state and returns a 32-bit pseudo-random integer derived from the current state.
Source
Returns:
32-bit pseudo-random integer (JS number)
Type: 
number
isCIDR(value) → {boolean}
Determine whether a provided value is a CIDR format IP string.
Parameters:
NameTypeDescription
valuestring
the IP string to test.
Source
Returns:
Type: 
boolean
isContained(x, y) → {boolean}
Determines containment of two provided parameters. Can be arrays or objects.
Parameters:
NameTypeDescription
x*
y*
Source
Returns:
Type: 
boolean
isEmpty(object, ignore) → {boolean}
Determine whether an object is empty.
Parameters:
NameTypeDescription
objectobject
object to enumerate.
ignorestring
property to ignore.
Source
Returns:
Type: 
boolean
isEqual(x, y) → {boolean}
Determines equality of two provided parameters. Can be arrays or objects.
Parameters:
NameTypeDescription
x*
y*
Source
Returns:
Type: 
boolean
lookupZone(namenullable) → (nullable) {Zone}
Look up a firewall zone.
Parameters:
NameTypeAttributesDescription
namestring<nullable>
Source
Returns:
Type: 
Zone
mul(a, b) → {Array.<number>}
Multiply two 64-bit values represented as arrays of four 16-bit words.
Arrays use little-endian word order (least-significant 16-bit word first). The result is truncated to the lower 64 bits and returned as a 4-element array of 16-bit words.
Parameters:
NameTypeDescription
aArray.<number>
Multiplicand (4 × 16-bit words, little-endian)
bArray.<number>
Multiplier (4 × 16-bit words, little-endian)
Source
Returns:
Product as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
parseEnum(snullable, values) → {string}
Parse an enum value.
Parameters:
NameTypeAttributesDescription
sstring<nullable>
valuesArray.<string>
Source
Returns:
Type: 
string
parsePolicy(snullable, defaultValueopt) → (nullable) {string}
Parse a policy value, or defaultValue if not found.
Parameters:
NameTypeAttributesDefaultDescription
sstring<nullable>
defaultValueArray.<string><optional>
['DROP', 'REJECT', 'ACCEPT']
Source
Returns:
Type: 
string
scrubMenu(node) → {Node}
Erase the menu node
Parameters:
NameTypeDescription
nodeNode
Source
Returns:
Type: 
Node
seed(n) → {void}
Seed the PRNG state.
The seed is treated as a 32-bit integer; the lower 16 bits are stored in s[0], the upper 16 bits in s[1]. s[2] and s[3] are zeroed.
Parameters:
NameTypeDescription
nnumber
Seed value (32-bit integer)
Source
Returns:
Type: 
void
shr(a, n) → {Array.<number>}
Shift a 64-bit value (4 × 16-bit words, little-endian) right by n bits.
The input array is treated as little-endian 16-bit words. Bits shifted out on the right are discarded; the returned array contains the lower 64-bit result after the logical right shift.
Parameters:
NameTypeDescription
aArray.<number>
Source value as 4 × 16-bit words (little-endian)
nnumber
Number of bits to shift right (non-negative integer)
Source
Returns:
Shifted value as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
validateBroadcast(section_id, value) → {boolean}
Validate a broadcast IP for a section value.
Parameters:
NameTypeDescription
section_idstring
valuestring
Source
Returns:
Type: 
boolean

\ No newline at end of file
+    
On this page
Methods
add(a, n) → {Array.<number>}
Add a small integer to a 64-bit value represented as four 16-bit words.
Treats a as a little-endian 64-bit value (4 × 16-bit words). Adds the integer n to the least-significant word and propagates carry across subsequent 16-bit words. The result is truncated to 64 bits and returned as a 4-element array of 16-bit words (little-endian).
Parameters:
NameTypeDescription
aArray.<number>
Addend as 4 × 16-bit words (little-endian)
nnumber
Value to add (integer carry)
Source
Returns:
Sum as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
calculateBroadcast(s, use_cfgvalue) → {string}
Calculate the broadcast IP for a given IP.
Parameters:
NameTypeDescription
sNode
the ui element to test.
use_cfgvalueboolean
whether to use the config or form value.
Source
Returns:
Type: 
string
derive_color(string) → {string}
Derive a deterministic hex color from an input string.
The color is produced by seeding the PRNG from a string-derived hash and producing RGB components. Returns a #rrggbb hex string.
Parameters:
NameTypeDescription
stringstring
Input string used to derive the color
Source
Returns:
Hex color string in #rrggbb format
Type: 
string
get(loweropt, upperopt) → {number}
Return a pseudo-random value.
Overloads:
  • get() -> number in [0, 1]
  • get(upper) -> integer in [1, upper]
  • get(lower, upper) -> integer in [lower, upper]
Parameters:
NameTypeAttributesDefaultDescription
lowernumber<optional>
0
Lower bound (when two args supplied)
uppernumber<optional>
0
Upper bound (when one or two args supplied)
Source
Returns:
Random value (float in [0,1] or integer in requested range)
Type: 
number
getColorForName(forNamenullable) → {string}
Generate a colour for a name.
Parameters:
NameTypeAttributesDescription
forNamestring<nullable>
Source
Returns:
Type: 
string
getDevices(network) → {Array.<string>}
Get bridge devices or Layer 3 devices of a network object.
Parameters:
NameTypeDescription
networkobject
Source
Returns:
Type: 
Array.<string>
getGroups() → {Array.<string>}
Get users found in /etc/group.
Source
Returns:
Type: 
Array.<string>
getUsers() → {Array.<string>}
Get users found in /etc/passwd.
Source
Returns:
Type: 
Array.<string>
handleCgiIoReply(res) → {string}
Handle a CGI-IO reply.
Parameters:
NameTypeDescription
resobject
Source
Throws:
Error
Returns:
Type: 
string
handleRpcReply(expect, rc) → {number}
Handle an RPC reply.
Parameters:
NameTypeDescription
expectobject
rcnumber
Source
Throws:
Error
Returns:
Type: 
number
initFirewallState() → {Promise}
Load the firewall configuration.
Source
Returns:
Type: 
Promise
int() → {number}
Produce the next PRNG 32-bit integer.
Advances the internal state and returns a 32-bit pseudo-random integer derived from the current state.
Source
Returns:
32-bit pseudo-random integer (JS number)
Type: 
number
isCIDR(value) → {boolean}
Determine whether a provided value is a CIDR format IP string.
Parameters:
NameTypeDescription
valuestring
the IP string to test.
Source
Returns:
Type: 
boolean
isContained(x, y) → {boolean}
Determines containment of two provided parameters. Can be arrays or objects.
Parameters:
NameTypeDescription
x*
y*
Source
Returns:
Type: 
boolean
isEmpty(object, ignore) → {boolean}
Determine whether an object is empty.
Parameters:
NameTypeDescription
objectobject
object to enumerate.
ignorestring
property to ignore.
Source
Returns:
Type: 
boolean
isEqual(x, y) → {boolean}
Determines equality of two provided parameters. Can be arrays or objects.
Parameters:
NameTypeDescription
x*
y*
Source
Returns:
Type: 
boolean
lookupZone(namenullable) → (nullable) {Zone}
Look up a firewall zone.
Parameters:
NameTypeAttributesDescription
namestring<nullable>
Source
Returns:
Type: 
Zone
mul(a, b) → {Array.<number>}
Multiply two 64-bit values represented as arrays of four 16-bit words.
Arrays use little-endian word order (least-significant 16-bit word first). The result is truncated to the lower 64 bits and returned as a 4-element array of 16-bit words.
Parameters:
NameTypeDescription
aArray.<number>
Multiplicand (4 × 16-bit words, little-endian)
bArray.<number>
Multiplier (4 × 16-bit words, little-endian)
Source
Returns:
Product as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
parseEnum(snullable, values) → {string}
Parse an enum value.
Parameters:
NameTypeAttributesDescription
sstring<nullable>
valuesArray.<string>
Source
Returns:
Type: 
string
parsePolicy(snullable, defaultValueopt) → (nullable) {string}
Parse a policy value, or defaultValue if not found.
Parameters:
NameTypeAttributesDefaultDescription
sstring<nullable>
defaultValueArray.<string><optional>
['DROP', 'REJECT', 'ACCEPT']
Source
Returns:
Type: 
string
scrubMenu(node) → {Node}
Erase the menu node
Parameters:
NameTypeDescription
nodeNode
Source
Returns:
Type: 
Node
seed(n) → {void}
Seed the PRNG state.
The seed is treated as a 32-bit integer; the lower 16 bits are stored in s[0], the upper 16 bits in s[1]. s[2] and s[3] are zeroed.
Parameters:
NameTypeDescription
nnumber
Seed value (32-bit integer)
Source
Returns:
Type: 
void
shr(a, n) → {Array.<number>}
Shift a 64-bit value (4 × 16-bit words, little-endian) right by n bits.
The input array is treated as little-endian 16-bit words. Bits shifted out on the right are discarded; the returned array contains the lower 64-bit result after the logical right shift.
Parameters:
NameTypeDescription
aArray.<number>
Source value as 4 × 16-bit words (little-endian)
nnumber
Number of bits to shift right (non-negative integer)
Source
Returns:
Shifted value as 4 × 16-bit words (little-endian)
Type: 
Array.<number>
validateBroadcast(section_id, value) → {boolean}
Validate a broadcast IP for a section value.
Parameters:
NameTypeDescription
section_idstring
valuestring
Source
Returns:
Type: 
boolean

\ No newline at end of file
diff --git a/jsapi/luci.js.html b/jsapi/luci.js.html
index 34ba7625c2..db0e1987d1 100644
--- a/jsapi/luci.js.html
+++ b/jsapi/luci.js.html
@@ -573,9 +573,8 @@
 		}
 
 		requestQueue.length = 0;
-		const requestBaseURL = Request.expandURL(classes.rpc.getBaseURL());
 
-		Request.request(requestBaseURL, reqopt).then(reply => {
+		Request.request(rpcBaseURL, reqopt).then(reply => {
 			let json = null, req = null;
 
 			try { json = reply.json() }
@@ -2837,7 +2836,7 @@
 		 * @returns {string}
 		 * Return the joined URL path.
 		 */
-		path(prefix = '', ...parts) {
+		path(prefix = '', parts) {
 			const url = [ prefix ];
 
 			for (let i = 0; i < parts.length; i++){