LuCI Documentation
Start with the LuCI Client side JavaScript APIs
Historical
The older Lua API docs are available for historical reference.
Start with the LuCI Client side JavaScript APIs
The older Lua API docs are available for historical reference.
LuCI.baseclass is the abstract base class all LuCI classes inherit from.
It provides a simple means to create subclasses of given classes and implements prototypal inheritance.
Walks up the parent class chain and looks for a class member called key in any of the parent classes this class inherits from. Returns the member value of the superclass or calls the member as a function and returns its return value when the optional callArgs array is given.
This function has two signatures and is sensitive to the amount of arguments passed to it:
super('key') - Returns the value of key when found within one of the parent classes.super('key', ['arg1', 'arg2']) - Calls the key() method with parameters arg1 and arg2 when found within one of the parent classes.| Name | Type | Attributes | Description |
|---|---|---|---|
key | string | The name of the superclass member to retrieve. | |
callArgs | * | | <optional> | Arguments to pass when invoking the superclass method. May be either an argument array or variadic arguments. |
Throws a ReferenceError when callArgs are specified and the found member named by key is not a function value.
Returns the value of the found member or the return value of the call to the found method. Returns null when no member was found in the parent class chain or when the call to the superclass method returned null.
Returns a string representation of this class.
Returns a string representation of this class containing the constructor functions displayName and describing the class members and their respective types.
Extract all values from the given argument array beginning from offset and prepend any further given optional parameters to the beginning of the resulting array copy.
| Name | Type | Attributes | Description |
|---|---|---|---|
args | Array.<*> | The array to extract the values from. | |
offset | number | The offset from which to extract the values. An offset of | |
extra_args | * | <optional> <repeatable> | Extra arguments to add to prepend to the resulting array. |
Returns a new array consisting of the optional extra arguments and the values extracted from the args array beginning with offset.
Extends this base class with the properties described in properties and returns a new subclassed Class instance
| Name | Type | Description |
|---|---|---|
properties | Object.<string, *> | An object describing the properties to add to the new subclass. |
Returns a new LuCI.baseclass subclassed from this class, extended by the given properties and with its prototype set to this base class to enable inheritance. The resulting value represents a class constructor and can be instantiated with new.
Calls the class constructor using new with the given argument array being passed as variadic parameters to the constructor.
| Name | Type | Description |
|---|---|---|
args | Array.<*> | An array of arbitrary values which will be passed as arguments to the constructor function. |
Returns a new LuCI.baseclass instance extended by the given properties with its prototype set to this base class to enable inheritance.
Checks whether the given class value is a subclass of this class.
| Name | Type | Description |
|---|---|---|
classValue | LuCI. | The class object to test. |
Returns true when the given classValue is a subclass of this class or false if the given value is not a valid class or not a subclass of this class.
Extends this base class with the properties described in properties, instantiates the resulting subclass using the given arguments passed to this function and returns the resulting subclassed Class instance.
This function serves as a convenience shortcut for Class.extend() and subsequent new.
| Name | Type | Attributes | Description |
|---|---|---|---|
properties | Object.<string, *> | An object describing the properties to add to the new subclass. | |
new_args | * | <repeatable> | Arguments forwarded to the constructor of the generated subclass. |
Returns a new LuCI.baseclass instance extended by the given properties with its prototype set to this base class to enable inheritance.
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(...).
Appends the given children data to the given node.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | * | The | |
children | * | <optional> | The children to append to the given node. When When When When |
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.
Sets attributes or registers event listeners on element nodes.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | * | The | |
key | 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 When When When |
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.
| Name | Type | Description |
|---|---|---|
node | Node | The DOM |
inst | Class | The Class instance to bind to the node. |
Throws a TypeError when the given instance argument isn't a valid Class instance.
Returns the bound class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | Node | The DOM | |
method | string | The name of the method to invoke on the found class instance. | |
args | * | <repeatable> | Additional arguments to pass to the invoked method as-is. |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | * | The | |
children | * | <optional> | The children to replace into the given node. When When When When |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
html | string | Describes the node to create. When the value of When the value of When the value of When the value of | |
attr | Object.<string, *> | <optional> | Specifies an Object of key, value pairs to set as attributes or event handlers on the created node. Refer to |
data | * | <optional> | Specifies children to append to the newly created element. Refer to |
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.
Returns the newly created Node.
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.| Name | Type | Attributes | Description |
|---|---|---|---|
node | Node | The DOM | |
key | string | | <optional> | This is either a string specifying the key to retrieve, or |
val | * | | <optional> | This is either a non- |
Returns the get or set value, or null when no value could be found.
Tests whether the given argument is a valid DOM Node.
| Name | Type | Description |
|---|---|---|
e | * | The value to test. |
Returns true if the value is a DOM Node, else false.
Finds a bound class instance on the given node itself or the first bound instance on its closest parent node.
| Name | Type | Description |
|---|---|---|
node | Node | The DOM |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | Node | The DOM | |
ignoreFn | LuCI. | <optional> | Specifies an optional function which is invoked for each child node to decide whether the child node should be ignored or not. |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | * | The | |
selector | string | <optional> | The query selector expression to test against the given node. |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
node | * | The | |
selector | string | <optional> | The query selector expression to test against each parent. |
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.
Parses a given string as HTML and returns the first child node.
| Name | Type | Description |
|---|---|---|
s | string | 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 |
Returns the first DOM Node extracted from the HTML fragment or null on parsing failures or if no element could be found.
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.
| Name | Type | Description |
|---|---|---|
node | Node | The child node to test. |
Boolean indicating whether to ignore the node or not.
The AbstractElement class serves as an abstract base for the different form elements implemented by LuCI.form. It provides the common logic for loading and rendering values, for nesting elements and for defining common properties.
This class is private and not directly accessible by user code.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Parse this element's form input.
The parse() function recursively walks the form element tree and triggers input value reading and validation for each encountered element.
Elements which are hidden due to unsatisfied dependencies are skipped.
Returns a promise resolving once this element's value and 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.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Enumerate the UCI section IDs covered by this form section element.
Throws an InternalError exception if the function is not implemented.
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The UCI section ID to test. |
Returns true when the given UCI section ID should be handled and false when it should be ignored.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
option | string | <optional> | The name of the option object to obtain |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
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.
Add a configuration option widget to the section.
Note that taboption() should be used instead if this form section element uses tabs.
| Name | Type | Attributes | Description |
|---|---|---|---|
optionclass | LuCI. | 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 | |
cbiClass | object | (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 |
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
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.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs. | |
title | string | The human readable caption of the tab. | |
description | string | <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. |
Throws an exception if a tab with the same name already exists.
Add a configuration option widget to a tab of the section.
| Name | Type | Attributes | Description |
|---|---|---|---|
tabName | string | The name of the section tab to add the option element to. | |
optionclass | LuCI. | 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 | |
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. |
Throws a ReferenceError exception when the given tab name does not exist.
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
value | * | The value to validate |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The Button element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The DirectoryPicker element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, create, delete and select remote directories.
Render the widget in browser mode initially instead of a button to 'Select Directory...'.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
Toggle download file functionality.
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.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The DummyValue element wraps a LuCI.ui.Hiddenfield widget and renders the underlying UCI option or default value as readonly text.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
Render the UCI option value as hidden using the HTML 'display: none' style property.
By default, the value is displayed.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The FileUpload element wraps a LuCI.ui.FileUpload widget and offers the ability to browse, upload and select remote files.
Render the widget in browser mode initially instead of a button to 'Select File...'.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
Toggle download file functionality.
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.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The Flag element builds upon the LuCI.ui.Checkbox widget to implement a simple checkbox element.
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.
Sets a default value to use when the underlying UCI option is not set.
Sets the input value to use for the checkbox unchecked state.
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.
Sets the input value to use for the checkbox checked state.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
Query the checked state of the underlying checkbox widget and return either the enabled or the disabled property value, depending on the checked state.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
Query the checked state of the underlying checkbox widget and return either a localized Yes or No string, depending on the checked state.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
Set a custom text for the actions column header row when actions buttons are present.
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.
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.
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.
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.
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.
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.
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.
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.
Optional footer row for table sections.
Set footer to one of:
tr) or node E('...')This is useful for providing sum totals, extra function buttons or extra space.
The default implementation returns an empty node.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
| Name | Type | Description |
|---|---|---|
modalSection | LuCI. | The |
section_id | string | The ID of the underlying UCI section the modal popup belongs to. |
ev | Event | The DOM event emitted by clicking the |
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The UCI section ID to test. |
Returns true when the given UCI section ID should be handled and false when it should be ignored.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
option | string | <optional> | The name of the option object to obtain |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
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.
Add a configuration option widget to the section.
Note that taboption() should be used instead if this form section element uses tabs.
| Name | Type | Attributes | Description |
|---|---|---|---|
optionclass | LuCI. | 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 | |
cbiClass | object | (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 |
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs. | |
title | string | The human readable caption of the tab. | |
description | string | <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. |
Throws an exception if a tab with the same name already exists.
Add a configuration option widget to a tab of the section.
| Name | Type | Attributes | Description |
|---|---|---|---|
tabName | string | The name of the section tab to add the option element to. | |
optionclass | LuCI. | 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 | |
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. |
Throws a ReferenceError exception when the given tab name does not exist.
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
A JSONMap class functions similar to LuCI.form.Map but uses a multidimensional JavaScript object instead of UCI configuration as a data source.
| Name | Type | Attributes | Description |
|---|---|---|---|
data | Object.<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. | |
title | string | <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. |
description | string | <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. |
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
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.
| Name | Type | Description |
|---|---|---|
config | string | 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. |
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
args | * | <repeatable> | argument array |
selector_or_attrname | string | If invoked with only one parameter, this argument is a | |
attrvalue | string | <optional> | In case the function is invoked with two parameters, this argument specifies the attribute value to match. |
Throws an InternalError if more than two function parameters are passed.
Returns the first found DOM node or null if no element matched.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
args | * | <repeatable> | argument array |
selector_or_attrname | string | If invoked with only one parameter, this argument is a | |
attrvalue | string | <optional> | In case the function is invoked with two parameters, this argument specifies the attribute value to match. |
Throws an InternalError if more than two function parameters are passed.
Returns a (possibly empty) DOM NodeList containing the found DOM nodes.
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.
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.
Find a form option element instance.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name or the full ID of the option element to look up. | |
section_id | string | <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_name | string | <optional> | The name of the UCI configuration the option instance belongs to. Defaults to the main UCI configuration of the map if omitted. |
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.
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.
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.
Render the form markup.
Returns a promise resolving to the top-level form DOM node once the rendering is complete.
Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.
Returns a promise resolving to the top-level form DOM node once the re-rendering is complete.
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.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
cb | function | <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. | |
silent | boolean | <optional> | false | If set to |
Returns a promise resolving once the entire save operation is complete. The returned promise is rejected if any step of the save operation failed.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
cbiClass | LuCI. | (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 | |
args | string | <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. |
Returns the instantiated section class instance.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
Set the orientation of the underlying radio or checkbox elements.
May be one of horizontal or vertical. Only applies to non-select widget types.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
Set the size attribute of the underlying HTML select element.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The Map class represents one complete form. A form usually maps one UCI configuration file and is divided into multiple sections containing multiple fields each.
It serves as the main entry point into the LuCI.form for typical view code.
| Name | Type | Attributes | Description |
|---|---|---|---|
config | string | The UCI configuration to map. It is automatically loaded along with the resulting map instance. | |
title | string | <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. |
description | string | <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. |
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
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.
| Name | Type | Description |
|---|---|---|
config | string | 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. |
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
args | * | <repeatable> | argument array |
selector_or_attrname | string | If invoked with only one parameter, this argument is a | |
attrvalue | string | <optional> | In case the function is invoked with two parameters, this argument specifies the attribute value to match. |
Throws an InternalError if more than two function parameters are passed.
Returns the first found DOM node or null if no element matched.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
args | * | <repeatable> | argument array |
selector_or_attrname | string | If invoked with only one parameter, this argument is a | |
attrvalue | string | <optional> | In case the function is invoked with two parameters, this argument specifies the attribute value to match. |
Throws an InternalError if more than two function parameters are passed.
Returns a (possibly empty) DOM NodeList containing the found DOM nodes.
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.
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.
Find a form option element instance.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name or the full ID of the option element to look up. | |
section_id | string | <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_name | string | <optional> | The name of the UCI configuration the option instance belongs to. Defaults to the main UCI configuration of the map if omitted. |
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.
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.
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.
Render the form markup.
Returns a promise resolving to the top-level form DOM node once the rendering is complete.
Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.
Returns a promise resolving to the top-level form DOM node once the re-rendering is complete.
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.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
cb | function | <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. | |
silent | boolean | <optional> | false | If set to |
Returns a promise resolving once the entire save operation is complete. The returned promise is rejected if any step of the save operation failed.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
cbiClass | LuCI. | (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 | |
args | string | <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. |
Returns the instantiated section class instance.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Allows custom value entry in addition to those already specified.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
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.
Returns a one-element array containing the mapped section ID.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The UCI section ID to test. |
Returns true when the given UCI section ID should be handled and false when it should be ignored.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
option | string | <optional> | The name of the option object to obtain |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
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.
Add a configuration option widget to the section.
Note that taboption() should be used instead if this form section element uses tabs.
| Name | Type | Attributes | Description |
|---|---|---|---|
optionclass | LuCI. | 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 | |
cbiClass | object | (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 |
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
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.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs. | |
title | string | The human readable caption of the tab. | |
description | string | <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. |
Throws an exception if a tab with the same name already exists.
Add a configuration option widget to a tab of the section.
| Name | Type | Attributes | Description |
|---|---|---|---|
tabName | string | The name of the section tab to add the option element to. | |
optionclass | LuCI. | 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 | |
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. |
Throws a ReferenceError exception when the given tab name does not exist.
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Define the units of the calculated value.
Suffix a unit string to the calculated value, e.g. 'seconds' or 'dBm'.
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.
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.
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.
Maximum value the slider can represent.
Minimum value the slider can represent.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
Step size for each tick of the slider, or the special value "any" when handling arbitrary precision floating point numbers.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
Query the current form input value.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns the currently selected value if it does not match the default. If the currently selected value matches the default value, returns null.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
Set the orientation of the underlying radio or checkbox elements.
May be one of horizontal or vertical. Only applies to non-select widget types.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
Set the size attribute of the underlying HTML select element.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
value | string | The choice value to add. |
title | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
description | Node | | 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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
The SectionValue widget embeds a form section element within an option element container, allowing to nest form sections into other sections.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Access the embedded section instance.
This property holds a reference to the instantiated nested section.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
Since the section container is not tied to any UCI configuration, its cfgvalue() implementation will always return null.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
Since the section container is not tied to any UCI configuration, its formvalue() implementation will always return null.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
Since the section container is not tied to any UCI configuration, its remove() implementation is a no-op.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Since the section container is not rendering an own widget, its value() implementation is a no-op.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
Since the section container is not tied to any UCI configuration, its write() implementation is a no-op.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
Set a custom text for the actions column header row when actions buttons are present.
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.
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.
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.
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.
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.
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.
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.
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.
Optional footer row for table sections.
Set footer to one of:
tr) or node E('...')This is useful for providing sum totals, extra function buttons or extra space.
The default implementation returns an empty node.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
| Name | Type | Description |
|---|---|---|
modalSection | LuCI. | The |
section_id | string | The ID of the underlying UCI section the modal popup belongs to. |
ev | Event | The DOM event emitted by clicking the |
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The UCI section ID to test. |
Returns true when the given UCI section ID should be handled and false when it should be ignored.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
option | string | <optional> | The name of the option object to obtain |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
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.
Add a configuration option widget to the section.
Note that taboption() should be used instead if this form section element uses tabs.
| Name | Type | Attributes | Description |
|---|---|---|---|
optionclass | LuCI. | 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 | |
cbiClass | object | (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 |
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
The TableSection implementation does not support option tabbing, so its implementation of tab() will always throw an exception when invoked.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs. | |
title | string | The human readable caption of the tab. | |
description | string | <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. |
Throws an exception when invoked.
Add a configuration option widget to a tab of the section.
| Name | Type | Attributes | Description |
|---|---|---|---|
tabName | string | The name of the section tab to add the option element to. | |
optionclass | LuCI. | 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 | |
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. |
Throws a ReferenceError exception when the given tab name does not exist.
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
The TextValue class implements a multi-line textarea input using LuCI.ui.Textarea.
Allows specifying the cols property of the underlying textarea widget.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
Enforces the use of a monospace font for the textarea contents when set to true.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
Allows specifying the rows property of the underlying textarea widget.
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.
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.
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.
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.
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.
Allows specifying the wrap property of the underlying textarea widget.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Enumerate the UCI section IDs covered by this form section element.
Throws an InternalError exception if the function is not implemented.
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The UCI section ID to test. |
Returns true when the given UCI section ID should be handled and false when it should be ignored.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
option | string | <optional> | The name of the option object to obtain |
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.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
section_id | string | The configuration section ID | |
option | string | <optional> | The name of the option to query |
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.
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.
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.
Add a configuration option widget to the section.
Note that taboption() should be used instead if this form section element uses tabs.
| Name | Type | Attributes | Description |
|---|---|---|---|
optionclass | LuCI. | 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 | |
cbiClass | object | (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 |
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
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.
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
name | string | The name of the tab to register. It may be freely chosen and just serves as an identifier to differentiate tabs. | |
title | string | The human readable caption of the tab. | |
description | string | <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. |
Throws an exception if a tab with the same name already exists.
Add a configuration option widget to a tab of the section.
| Name | Type | Attributes | Description |
|---|---|---|---|
tabName | string | The name of the section tab to add the option element to. | |
optionclass | LuCI. | 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 | |
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. |
Throws a ReferenceError exception when the given tab name does not exist.
Throws a TypeError exception in case the passed class value is not a descendant of AbstractValue.
Returns the instantiated option class instance.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
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.
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.
Sets a default value to use when the underlying UCI option is not set.
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.
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.
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.
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.
If set to true, the field is rendered as a password input, otherwise as a plain text input.
Set a placeholder string to use when the input field is empty.
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.
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.
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.
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.
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.
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.
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.
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.
Add another form element as children to this element.
| Name | Type | Description |
|---|---|---|
obj | AbstractElement | The form element to add. |
Obtain the internal ID ("cbid") of the element instance.
Since each form section element may map multiple underlying configuration sections, the configuration section ID is required to form a fully qualified ID pointing to the specific element instance within the given specific section.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the element ID.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
set_value | string | The value to assign |
Throws a TypeError exception when no section_id was specified.
Returns the configuration value.
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!contains!defaultExamples:
opt.depends("foo", "test")opt.depends({ foo: "test" })opt.depends({ foo: /test/ })opt.depends({ foo: "test", bar: "qrx" })opt.depends({ foo: "test" })
opt.depends({ bar: "qrx" })foo to be set to test, or the bar option to be qrx.opt.depends("test.section1.foo", "bar")opt.depends({ foo: "test", "!contains": true })| Name | Type | Attributes | Description |
|---|---|---|---|
field | string | | The name of the option to depend on or an object describing multiple dependencies which must be satisfied (a logical "and" expression). | |
value | string | | <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. |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the current input value.
Obtain the underlying LuCI.ui element instance.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the LuCI.ui element instance or null in case the form option implementation does not use LuCI.ui widgets.
Returns the current validation error for this input.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
The validation error at this time
Test whether the option element is currently active.
An element is active when it is not hidden due to unsatisfied dependency constraints.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the option element currently is active, otherwise it returns false.
Test whether the input value is currently valid.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns true if the input value currently is valid, otherwise it returns false.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
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.
Parse the option element input.
The function is invoked when the parse() method has been invoked on the parent form and triggers input value reading and validation.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Returns 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.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
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.
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.
Strip any HTML tags from the given input string, and decode HTML entities.
| Name | Type | Description |
|---|---|---|
s | string | The input string to clean. |
The cleaned input string with HTML tags removed, and HTML entities decoded.
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
Throws a TypeError exception when no section_id was specified.
Returns the text representation of the current input value.
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.
| Name | Type | Attributes | Description |
|---|---|---|---|
attr | string | (property) The name of the element property to use. | |
args | string | <repeatable> | (fmt_args) Extra values to format the title string with. |
The formatted title string or null if the property did not exist or was neither a string nor a function.
Add a predefined choice to the form option. By adding one or more choices, the plain text input field is turned into a combobox widget which prompts the user to select a predefined choice, or to enter a custom value.
| Name | Type | Description |
|---|---|---|
key | string | The choice value to add. |
val | Node | | The caption for the choice value. May be a DOM node, a document fragment or a plain text string. If omitted, the |
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.
| Name | Type | Description |
|---|---|---|
section_id | string | The configuration section ID |
formvalue | string | | The input value to write. |
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.
'use strict';
'require form';
diff --git a/LuCI.fs.html b/jsapi/LuCI.fs.html
similarity index 99%
rename from LuCI.fs.html
rename to jsapi/LuCI.fs.html
index b1f7243f82..a4c975627e 100644
--- a/LuCI.fs.html
+++ b/jsapi/LuCI.fs.html
@@ -1,3 +1,3 @@
-Class: fs On this pageLuCI. fs
Provides high level utilities to wrap file system related RPC calls. To import the class in views, use 'require fs', to import it in external JavaScript, use L.require("fs").then(...).
Methods
exec(command, paramsopt, envopt) → {Promise.<LuCI.fs.FileExecResult>}
Execute the specified command, optionally passing params and environment variables.
Note: The command must be either the path to an executable, or a basename without arguments in which case it will be searched in $PATH. If specified, the values given in params will be passed as arguments to the command.
The key/value pairs in the optional env table are translated to setenv() calls prior to running the command.
Parameters:Name Type Attributes Description commandstring The command to invoke.
paramsArray.<string> <optional>
The arguments to pass to the command.
envObject.<string, string> <optional>
Environment variables to set.
Returns:Returns a promise resolving to an object describing the execution results or rejecting with an error stating the failure reason.
- Type:
- Promise.<LuCI.fs.FileExecResult>
exec_direct(command, paramsopt, typeopt, latin1opt, stderropt, responseProgressopt) → {Promise.<*>}
Execute the specified command, bypassing ubus.
Note: The command must be either the path to an executable, or a basename without arguments in which case it will be searched in $PATH. If specified, the values given in params will be passed as arguments to the command.
This function will invoke the requested commands through the cgi-io helper applet at /cgi-bin/cgi-exec which bypasses the ubus rpc transport. This is useful to fetch large command outputs which might exceed the ubus message size limits or which contain binary data.
The cgi-io helper will enforce the same access permission rules as the ubus based exec call.
Parameters:Name Type Attributes Default Description commandstring The command to invoke.
paramsArray.<string> <optional>
The arguments to pass to the command.
type"blob" | "text" | "json" <optional>
text The expected output type of the invoked program. Valid values are text to interpret the output as string, json to parse the output as JSON or blob to return the output as Blob instance.
latin1boolean <optional>
false Whether to encode the command line as Latin1 instead of UTF-8. This is usually not needed but can be useful for programs that cannot handle UTF-8 input.
stderrboolean <optional>
false Whether to include stderr output in command output. This is usually not needed but can be useful to execute a command and get full output.
responseProgressfunction <optional>
null An optional request callback function which receives ProgressEvent instances as sole argument during the HTTP response transfer. This is usually not needed but can be useful to receive realtime command output before command exit.
Returns:Returns a promise resolving with the command stdout output interpreted according to the specified type or rejecting with an error stating the failure reason.
- Type:
- Promise.<*>
lines(path) → {Promise.<Array.<string>>}
Read the contents of the given file, split it into lines, trim leading and trailing white space of each line and return the resulting array.
This function is guaranteed to not reject its promises, on failure, an empty array will be returned.
Parameters:Name Type Description pathstring The file path to read.
Returns:Returns a promise resolving to an array containing the stripped lines of the given file or [] on failure.
- Type:
- Promise.<Array.<string>>
list(path) → {Promise.<Array.<LuCI.fs.FileStatEntry>>}
Obtains a listing of the specified directory.
Parameters:Name Type Description pathstring The directory path to list.
Returns:Returns a promise resolving to an array of stat detail objects or rejecting with an error stating the failure reason.
- Type:
- Promise.<Array.<LuCI.fs.FileStatEntry>>
read(path) → {Promise.<string>}
Read the contents of the given file and return them. Note: this function is unsuitable for obtaining binary data.
Parameters:Name Type Description pathstring The file path to read.
Returns:Returns a promise resolving to a string containing the file contents or rejecting with an error stating the failure reason.
- Type:
- Promise.<string>
read_direct(path, typeopt) → {Promise.<*>}
Read the contents of the given file and return them, bypassing ubus.
This function will read the requested file through the cgi-io helper applet at /cgi-bin/cgi-download which bypasses the ubus rpc transport. This is useful to fetch large file contents which might exceed the ubus message size limits or which contain binary data.
The cgi-io helper will enforce the same access permission rules as the ubus based read call.
Parameters:Name Type Attributes Default Description pathstring The file path to read.
type"blob" | "text" | "json" <optional>
text The expected type of read file contents. Valid values are text to interpret the contents as string, json to parse the contents as JSON or blob to return the contents as Blob instance.
Returns:Returns a promise resolving with the file contents interpreted according to the specified type or rejecting with an error stating the failure reason.
- Type:
- Promise.<*>
remove(path) → {Promise.<number>}
Unlink the given file.
Parameters:Name Type Description pathstring The file path to remove.
Returns:Returns a promise resolving to 0 or rejecting with an error stating the failure reason.
- Type:
- Promise.<number>
stat(path) → {Promise.<LuCI.fs.FileStatEntry>}
Return file stat information on the specified path.
Parameters:Name Type Description pathstring The filesystem path to stat.
Returns:Returns a promise resolving to a stat detail object or rejecting with an error stating the failure reason.
- Type:
- Promise.<LuCI.fs.FileStatEntry>
trimmed(path) → {Promise.<string>}
Read the contents of the given file, trim leading and trailing white space and return the trimmed result. In case of errors, return an empty string instead.
Note: this function is useful to read single-value files in /sys or /proc.
This function is guaranteed to not reject its promises, on failure, an empty string will be returned.
Parameters:Name Type Description pathstring The file path to read.
Returns:Returns a promise resolving to the file contents or the empty string on failure.
- Type:
- Promise.<string>
write(path, dataopt, modeopt) → {Promise.<number>}
Write the given data to the specified file path. If the specified file path does not exist, it will be created, given sufficient permissions.
Note: data will be converted to a string using String(data) or to '' when it is null.
Parameters:Name Type Attributes Description pathstring The file path to write to.
data* <optional>
The file data to write. If it is null, it will be set to an empty string.
modenumber <optional>
The permissions to use on file creation. Default is 420 (0644).
Returns:Returns a promise resolving to 0 or rejecting with an error stating the failure reason.
- Type:
- Promise.<number>
Type Definitions
FileExecResult
Type:- Object
PropertiesName Type Attributes Description codenumber The exit code of the invoked command
stdoutstring <optional>
The stdout produced by the command, if any
stderrstring <optional>
The stderr produced by the command, if any
FileStatEntry
Type:- Object
PropertiesName Type Description namestring Name of the directory entry
typestring Type of the entry, one of block, char, directory, fifo, symlink, file, socket or unknown
sizenumber Size in bytes
modenumber Access permissions
atimenumber Last access time in seconds since epoch
mtimenumber Last modification time in seconds since epoch
ctimenumber Last change time in seconds since epoch
inodenumber Inode number
uidnumber Numeric owner id
gidnumber Numeric group id
Class: headers On this pageLuCI. headers
The Headers class is an internal utility class exposed in HTTP response objects using the response.headers property.
Methods
get(name) → {string|null}
Returns the value of the given header name. Note: Header-Names are case-insensitive.
Parameters:Name Type Description namestring The header name to read
Returns:The value of the given header name or null if the header isn't present.
- Type:
- string |
null
has(name) → {boolean}
Checks whether the given header name is present. Note: Header-Names are case-insensitive.
Parameters:Name Type Description namestring The header name to check
Returns:Returns true if the header name is present, false otherwise
- Type:
- boolean
Class: LuCI On this pageLuCI
new LuCI(window, document, undefined)
This is the LuCI base class. It is automatically instantiated and accessible using the global L variable.
Parameters:Name Type Description 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).
PropertiesName Type Description envobject The environment settings to use for the LuCI runtime.
Classes
Namespaces
Members
Class
Legacy L.Class class alias. New view code should use 'require baseclass'; to request the LuCI.baseclass class.
- Deprecated
- Yes
Poll
Legacy L.Poll class alias. New view code should use 'require poll'; to request the LuCI.poll class.
- Deprecated
- Yes
Request
Legacy L.Request class alias. New view code should use 'require request'; to request the LuCI.request class.
- Deprecated
- Yes
dom
Legacy L.dom class alias. New view code should use 'require dom'; to request the LuCI.dom class.
- Deprecated
- Yes
env
The env object holds environment settings used by LuCI, such as request timeouts, base URLs, etc.
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
view
Legacy L.view class alias. New view code should use 'require view'; to request the LuCI.view class.
- Deprecated
- Yes
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:Name Type Attributes Description 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.
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:Name Type Attributes Default Description 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.
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:Name Type Attributes Description partsstring <optional>
<repeatable>
An array of parts to join into a path.
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:Name Type Attributes Description 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
Returns:Returns a promise resolving to null when concluded.
- Type:
- Promise.<null>
halt() → {boolean}
Deprecated wrapper around Poll.stop().
- Deprecated
- Yes
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:Name Type Attributes Description 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.
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.
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:Name Type Attributes Description val* <optional>
The value to test
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:Name Type Attributes Description val* <optional>
The value to test
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.
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:Name Type Attributes Description 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.
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:Name Type Attributes Description 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.
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:Name Type Attributes Default Description 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
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:Name Type Attributes Description 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
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:Name Type Attributes Default Description 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.
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:Name Type Attributes Default Description 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.
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:Name Type Description 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.
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:Name Type Attributes Description 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.
Returns:Returns the resulting URL path.
- Type:
- string
run() → {boolean}
Deprecated wrapper around Poll.start().
- Deprecated
- Yes
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:Name Type Description val* The input value to sort (and convert to an array if needed).
- 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:Name Type Attributes Description 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.
Returns:Returns an array containing the sorted keys of the given object.
- Type:
- Array.<string>
stop(entry) → {boolean}
Deprecated wrapper around Poll.remove().
Parameters:Name Type Description entryfunction The polling function to remove.
- Deprecated
- Yes
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:Name Type Description val* The value to convert into an array.
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:Name Type Attributes Description 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.
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:Name Type Description 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.
Module: cbi On this pageCBI (Configuration Bindings Interface) helper utilities and DOM helpers.
Provides initialization for CBI UI elements, dependency handling, validation wiring and miscellaneous helpers used by LuCI forms. Functions defined here are registered as global window.* symbols.
Methods
(inner) E() → {HTMLElement}
Create DOM elements using L.dom.create helper (convenience wrapper).
Returns:- Type:
- HTMLElement
(inner) N_(n, s, p, copt) → {string}
Plural-aware translation lookup.
Parameters:Name Type Attributes Description nnumber Quantity to evaluate plural form.
sstring Singular string.
pstring Plural string.
cstring <optional>
Optional context.
Returns:Translated plural form or source string.
- Type:
- string
(inner) _(s, copt) → {string}
Lookup a translated string for the given message and optional context. Falls back to the source string when no translation found.
Parameters:Name Type Attributes Description sstring Source string.
cstring <optional>
Optional translation context.
Returns:Translated string or original.
- Type:
- string
(inner) cbi_d_add(field, dep, index)
Register a dependency entry for a field.
Parameters:Name Type Description fieldHTMLElement | string Field element or its id.
depObject Dependency specification object.
indexnumber Order index of the dependent node.
(inner) cbi_d_check(deps) → {boolean}
Evaluate a list of dependency descriptors and return whether any match.
Parameters:Name Type Description depsArray.<Object> Array of dependency objects to evaluate.
Returns:True when dependencies indicate the element should be shown.
- Type:
- boolean
(inner) cbi_d_checkvalue(target, ref) → {boolean}
Check whether an input/select identified by target matches the given reference value.
Parameters:Name Type Description targetstring Element id or name to query.
refstring Reference value to compare with.
Returns:True if the current value matches ref.
- Type:
- boolean
(inner) cbi_d_update()
Update DOM nodes based on registered dependencies, showing or hiding nodes and restoring their order when dependency state changes.
(inner) cbi_dropdown_init(sb) → {L.ui.Dropdown|undefined}
Initialize a dropdown element into an L.ui.Dropdown instance and bind it. If already bound, this is a no-op.
Parameters:Name Type Description sbHTMLElement The select element to convert.
Returns:Dropdown instance or undefined when already bound.
- Type:
- L.
ui.Dropdown | undefined
(inner) cbi_init()
Initialize CBI widgets and wire up dependency and validation handlers. Walks the DOM looking for CBI-specific data attributes and replaces placeholders with interactive widgets.
(inner) cbi_row_swap(elem, up, store) → {boolean}
Move a table row up or down within a section and update the storage field.
Parameters:Name Type Description elemHTMLElement Element inside the row that triggers the swap.
upboolean If true, move the row up; otherwise move down.
storestring ID of the hidden input used to store the order.
Returns:Always returns false to cancel default action.
- Type:
- boolean
(inner) cbi_submit(elem, nameopt, valueopt, actionopt) → {boolean}
Submit a form, optionally adding a hidden input to pass a name/value pair.
Parameters:Name Type Attributes Description elemHTMLElement Element inside the form or an element with a form.
namestring <optional>
Name of hidden input to include, if any.
valuestring <optional>
Value for the hidden input (defaults to '1').
actionstring <optional>
Optional form action URL override.
Returns:True on successful submit, false when no form found.
- Type:
- boolean
(inner) cbi_tag_last(container)
Mark the last visible value container child with class cbi-value-last.
Parameters:Name Type Description containerHTMLElement Parent container element.
(inner) cbi_update_table(table, …data, placeholderopt)
Update or initialize a table UI widget with new data.
Parameters:Name Type Attributes Description tableHTMLElement | string Table element or selector.
dataArray.<Node> <repeatable>
Data to update the table with.
placeholderstring <optional>
Placeholder text when empty.
(inner) cbi_validate_field(cbid, optional, type)
Attach a validator to a field and wire validation events.
Parameters:Name Type Description cbidHTMLElement | string Element or element id to validate.
optionalboolean Whether an empty value is allowed.
typestring Validator type expression (passed to L.validation).
(inner) cbi_validate_form(form, errmsgopt) → {boolean}
Run all validators associated with a form and optionally show an error.
Parameters:Name Type Attributes Description formHTMLFormElement Form element containing validators.
errmsgstring <optional>
Message to show when validation fails.
Returns:True when form is valid.
- Type:
- boolean
(inner) cbi_validate_named_section_add(input)
Enable/disable a named-section add button depending on input value.
Parameters:Name Type Description inputHTMLInputElement Input that contains the new section name.
(inner) cbi_validate_reset(form) → {boolean}
Trigger a delayed form validation (used to allow UI state to settle).
Parameters:Name Type Description formHTMLFormElement Form to validate after a short delay.
Returns:Always returns true.
- Type:
- boolean
(inner) findParent(node, selector) → {HTMLElement|null}
Find the parent matching selector from node upwards.
Parameters:Name Type Description nodeNode Starting node.
selectorstring CSS selector to match ancestor.
Returns:- Type:
- HTMLElement |
null
(inner) isElem(e) → {HTMLElement|null}
Return the element for input which may be an element or an id.
Parameters:Name Type Description eElement | string Element or id.
Returns:- Type:
- HTMLElement |
null
(inner) matchesElem(node, selector) → {boolean}
Test whether node matches a CSS selector.
Parameters:Name Type Description nodeNode Node to test.
selectorstring CSS selector.
Returns:- Type:
- boolean
(inner) s8(bytes, off) → {number}
Read signed 8-bit integer from a byte array at the given offset.
Parameters:Name Type Description bytesArray.<number> Byte array.
offnumber Offset into the array.
Returns:Signed 8-bit value (returned as unsigned number).
- Type:
- number
(inner) sfh(s) → {string|null}
Compute a stable 32-bit-ish string hash used for translation keys. Encodes UTF-8 surrogate pairs and mixes bytes into a hex hash string.
Parameters:Name Type Description sstring | null Input string.
Returns:Hex hash string or null for empty input.
- Type:
- string |
null
(inner) trimws(s) → {string}
Trim whitespace and normalise internal whitespace sequences to single spaces.
Parameters:Name Type Description s* Value to convert to string and trim.
Returns:Trimmed and normalised string.
- Type:
- string
(inner) u16(bytes, off) → {number}
Read unsigned 16-bit little-endian integer from a byte array at offset.
Parameters:Name Type Description bytesArray.<number> Byte array.
offnumber Offset into the array.
Returns:Unsigned 16-bit integer.
- Type:
- number
Class: Device On this pageLuCI.network. Device
A Network.Device class instance represents an underlying Linux network device and allows querying device details such as packet statistics or MTU.
- Source
Methods
getBridgeID() → {null|string}
Get the bridge ID
- Source
Returns:Returns the ID of this network bridge or null if this network device is not a Linux bridge.
- Type:
- null |
string
getBridgeSTP() → {boolean}
Get the bridge STP setting
- Source
Returns:Returns true when this device is a Linux bridge and has stp enabled, else false.
- Type:
- boolean
getCarrier() → {boolean}
Get the carrier state of the network device.
- Source
Returns:Returns true if the device has a carrier, e.g. when a cable is inserted into an Ethernet port of false if there is none.
- Type:
- boolean
getDuplex() → {string|null}
Get the current duplex mode of the network device if available.
- Source
Returns:Returns the current duplex mode of the network device. Returns either "full" or "half" if the device supports duplex modes or null if the duplex mode is unknown or unsupported.
- Type:
- string |
null
getI18n() → {string}
Get a long description string for the device.
- Source
Returns:Returns a string containing the type description and device name for non-WiFi devices or operation mode and SSID for WiFi ones.
- Type:
- string
getIP6Addrs() → {Array.<string>}
Get the IPv6 addresses configured on the device.
- Source
Returns:Returns an array of IPv6 address strings.
- Type:
- Array.<string>
getIPAddrs() → {Array.<string>}
Get the IPv4 addresses configured on the device.
- Source
Returns:Returns an array of IPv4 address strings.
- Type:
- Array.<string>
getMAC() → {null|string}
Get the MAC address of the device.
- Source
Returns:Returns the MAC address of the device or null if not applicable, e.g. for non-Ethernet tunnel devices.
- Type:
- null |
string
getMTU() → {number}
Get the MTU of the device.
- Source
Returns:Returns the MTU of the device.
- Type:
- number
getName() → {string}
Get the name of the network device.
- Source
Returns:Returns the name of the device, e.g. eth0 or wlan0.
- Type:
- string
getNetwork() → {null|LuCI.network.Protocol}
Get the primary logical interface this device is assigned to.
- Source
Returns:Returns a Network.Protocol instance representing the logical interface this device is attached to or null if it is not assigned to any logical interface.
- Type:
- null |
LuCI.network.Protocol
getNetworks() → {Array.<LuCI.network.Protocol>}
Get the logical interfaces this device is assigned to.
- Source
Returns:Returns an array of Network.Protocol instances representing the logical interfaces this device is assigned to.
- Type:
- Array.<LuCI.network.Protocol>
getPSE() → {Object|null}
Get the PSE (Power Sourcing Equipment / PoE) status of the device.
- Source
Returns:Returns an object containing PSE status information or null if PSE is not available on this device. The object may contain:
- c33AdminState: "enabled" or "disabled" (C33 PoE admin state)
- c33PowerStatus: "disabled", "searching", "delivering", "test", "fault", "otherfault"
- c33PowerClass: Power class number (1-8)
- c33ActualPower: Actual power consumption in mW
- c33AvailablePowerLimit: Available power limit in mW
- podlAdminState: "enabled" or "disabled" (PoDL admin state)
- podlPowerStatus: "disabled", "searching", "delivering", "sleep", "idle", "error"
- priority: Current priority level
- priorityMax: Maximum priority level
- Type:
- Object |
null
getParent() → {null|LuCI.network.Device}
Get the logical parent device of this device.
In case of DSA switch ports, the parent device will be the DSA switch device itself, for VLAN devices, the parent refers to the base device etc.
- Source
Returns:Returns a Network.Device instance representing the parent device or null when this device has no parent, as it is the case for e.g. ordinary Ethernet interfaces.
- Type:
- null |
LuCI.network.Device
getPorts() → {null|Array.<LuCI.network.Device>}
Get the associated bridge ports of the device.
- Source
Returns:Returns an array of Network.Device instances representing the ports (slave interfaces) of the bridge or null when this device isn't a Linux bridge.
- Type:
- null |
Array.<LuCI.network.Device>
getRXBytes() → {number}
Get the amount of received bytes.
- Source
Returns:Returns the amount of bytes received by the network device.
- Type:
- number
getRXPackets() → {number}
Get the amount of received packets.
- Source
Returns:Returns the amount of packets received by the network device.
- Type:
- number
getShortName() → {string}
Get a short description string for the device.
- Source
Returns:Returns the device name for non-WiFi devices or a string containing the operation mode and SSID for WiFi devices.
- Type:
- string
getSpeed() → {number|null}
Get the current link speed of the network device if available.
- Source
Returns:Returns the current speed of the network device in Mbps. If the device supports no Ethernet speed levels, null is returned. If the device supports Ethernet speeds but has no carrier, -1 is returned.
- Type:
- number |
null
getTXBytes() → {number}
Get the amount of transmitted bytes.
- Source
Returns:Returns the amount of bytes transmitted by the network device.
- Type:
- number
getTXPackets() → {number}
Get the amount of transmitted packets.
- Source
Returns:Returns the amount of packets transmitted by the network device.
- Type:
- number
getType() → {string}
Get the type of the device.
- Source
Returns:Returns a string describing the type of the network device:
alias if it is an abstract alias device (@ notation)wifi if it is a wireless interface (e.g. wlan0)bridge if it is a bridge device (e.g. br-lan)tunnel if it is a tun or tap device (e.g. tun0)vlan if it is a vlan device (e.g. eth0.1)vrf if it is a Virtual Routing and Forwarding type (e.g. vrf0)switch if it is a switch device (e.g.eth1 connected to switch0)ethernet for all other device types
- Type:
- string
getTypeI18n() → {string}
Get a string describing the device type.
- Source
Returns:Returns a string describing the type, e.g. "Wireless Adapter" or "Bridge".
- Type:
- string
getWifiNetwork() → {null|LuCI.network.WifiNetwork}
Get the related wireless network this device is related to.
- Source
Returns:Returns a Network.WifiNetwork instance representing the wireless network corresponding to this network device or null if this device is not a wireless device.
- Type:
- null |
LuCI.network.WifiNetwork
hasPSE() → {boolean}
Check if PSE (PoE) is available on this device.
- Source
Returns:Returns true if PSE hardware is available on this device.
- Type:
- boolean
isBridge() → {boolean}
Checks whether this device is a Linux bridge.
- Source
Returns:Returns true when the network device is present and a Linux bridge, else false.
- Type:
- boolean
isBridgePort() → {boolean}
Checks whether this device is part of a Linux bridge.
- Source
Returns:Returns true when this network device is part of a bridge, else false.
- Type:
- boolean
isUp() → {boolean}
Checks whether this device is up.
- Source
Returns:Returns true when the associated device is running or false when it is down or absent.
- Type:
- boolean
Class: Hosts On this pageLuCI.network. Hosts
The LuCI.network.Hosts class encapsulates host information aggregated from multiple sources and provides convenience functions to access the host information by different criteria.
- Source
Methods
getHostnameByIP6Addr(ip6addr) → {null|string}
Look up the hostname associated with the given IPv6 address.
Parameters:Name Type Description ip6addrstring The IPv6 address to look up.
- Source
Returns:Returns the hostname associated with the given IPv6 or null if no matching host could be found or if no hostname is known for the corresponding host.
- Type:
- null |
string
getHostnameByIPAddr(ipaddr) → {null|string}
Look up the hostname associated with the given IPv4 address.
Parameters:Name Type Description ipaddrstring The IPv4 address to look up.
- Source
Returns:Returns the hostname associated with the given IPv4 or null if no matching host could be found or if no hostname is known for the corresponding host.
- Type:
- null |
string
getHostnameByMACAddr(mac) → {null|string}
Look up the hostname associated with the given MAC address.
Parameters:Name Type Description macstring The MAC address to look up.
- Source
Returns:Returns the hostname associated with the given MAC or null if no matching host could be found or if no hostname is known for the corresponding host.
- Type:
- null |
string
getIP6AddrByMACAddr(mac) → {null|string}
Look up the IPv6 address associated with the given MAC address.
Parameters:Name Type Description macstring The MAC address to look up.
- Source
Returns:Returns the IPv6 address associated with the given MAC or null if no matching host could be found or if no IPv6 address is known for the corresponding host.
- Type:
- null |
string
getIPAddrByMACAddr(mac) → {null|string}
Look up the IPv4 address associated with the given MAC address.
Parameters:Name Type Description macstring The MAC address to look up.
- Source
Returns:Returns the IPv4 address associated with the given MAC or null if no matching host could be found or if no IPv4 address is known for the corresponding host.
- Type:
- null |
string
getMACAddrByIP6Addr(ip6addr) → {null|string}
Look up the MAC address associated with the given IPv6 address.
Parameters:Name Type Description ip6addrstring The IPv6 address to look up.
- Source
Returns:Returns the MAC address associated with the given IPv6 or null if no matching host could be found or if no MAC address is known for the corresponding host.
- Type:
- null |
string
getMACAddrByIPAddr(ipaddr) → {null|string}
Look up the MAC address associated with the given IPv4 address.
Parameters:Name Type Description ipaddrstring The IPv4 address to look up.
- Source
Returns:Returns the MAC address associated with the given IPv4 or null if no matching host could be found or if no MAC address is known for the corresponding host.
- Type:
- null |
string
getMACHints(preferIp6opt) → {Array.<Array.<string>>}
Return an array of (MAC address, name hint) tuples sorted by MAC address.
Parameters:Name Type Attributes Default Description preferIp6boolean <optional>
false Whether to prefer IPv6 addresses (true) or IPv4 addresses (false) as name hint when no hostname is known for a specific MAC address.
- Source
Returns:Returns an array of arrays containing a name hint for each found MAC address on the system. The array is sorted ascending by MAC.
Each item of the resulting array is a two element array with the MAC being the first element and the name hint being the second element. The name hint is either the hostname, an IPv4 or an IPv6 address related to the MAC address.
If no hostname but both IPv4 and IPv6 addresses are known, the preferIP6 flag specifies whether the IPv6 or the IPv4 address is used as hint.
- Type:
- Array.<Array.<string>>
Class: Protocol On this pageLuCI.network. Protocol
The Network.Protocol class serves as the base for protocol-specific subclasses which describe logical UCI networks defined by config interface sections in /etc/config/network.
- Source
Methods
addDevice(device) → {boolean}
Add the given network device to the logical interface.
Parameters:Name Type Description deviceLuCI.network.Protocol | LuCI.network.Device | LuCI.network.WifiDevice | LuCI.network.WifiNetwork | string The object or device name to add to the logical interface. In case the given argument is not a string, it is resolved though the Network.getIfnameOf() function.
- Source
Returns:Returns true if the device name has been added or false if any argument was invalid, if the device was already part of the logical interface or if the logical interface is virtual.
- Type:
- boolean
containsDevice(device) → {boolean}
Checks whether this logical interface contains the given device object.
Parameters:Name Type Description deviceLuCI.network.Protocol | LuCI.network.Device | LuCI.network.WifiDevice | LuCI.network.WifiNetwork | string The object or device name to check. In case the given argument is not a string, it is resolved though the Network.getIfnameOf() function.
- Source
Returns:Returns true when this logical interface contains the given network device or false if not.
- Type:
- boolean
(abstract) deleteConfiguration() → {*|Promise.<*>}
Cleanup related configuration entries.
This function will be invoked if an interface is about to be removed from the configuration and is responsible for performing any required cleanup tasks, such as unsetting uci entries in related configurations.
It should be overridden by protocol specific subclasses.
- Source
Returns:This function may return a promise which is awaited before the rest of the configuration is removed. Any non-promise return value and any resolved promise value is ignored. If the returned promise is rejected, the interface removal will be aborted.
- Type:
- * |
Promise.<*>
deleteDevice(device) → {boolean}
Remove the given network device from the logical interface.
Parameters:Name Type Description deviceLuCI.network.Protocol | LuCI.network.Device | LuCI.network.WifiDevice | LuCI.network.WifiNetwork | string The object or device name to remove from the logical interface. In case the given argument is not a string, it is resolved though the Network.getIfnameOf() function.
- Source
Returns:Returns true if the device name has been added or false if any argument was invalid, if the device was already part of the logical interface or if the logical interface is virtual.
- Type:
- boolean
get(opt) → {null|string|Array.<string>}
Read the given UCI option value of this network.
Parameters:Name Type Description optstring The UCI option name to read.
- Source
Returns:Returns the UCI option value or null if the requested option is not found.
- Type:
- null |
string | Array.<string>
getDNS6Addrs() → {Array.<string>}
Query the IPv6 DNS servers associated with the logical interface.
- Source
Returns:Returns an array of IPv6 DNS servers registered by the remote protocol back-end.
- Type:
- Array.<string>
getDNSAddrs() → {Array.<string>}
Query the IPv4 DNS servers associated with the logical interface.
- Source
Returns:Returns an array of IPv4 DNS servers registered by the remote protocol back-end.
- Type:
- Array.<string>
getDevice() → {LuCI.network.Device}
Returns the Linux network device associated with this logical interface.
- Source
Returns:Returns a Network.Device class instance representing the expected Linux network device according to the configuration.
- Type:
- LuCI.
network.Device
getDevices() → {null|Array.<LuCI.network.Device>}
Returns a list of network sub-devices associated with this logical interface.
- Source
Returns:Returns an array of Network.Device class instances representing the sub-devices attached to this logical interface or null if the logical interface does not support sub-devices, e.g. because it is virtual and not a bridge.
- Type:
- null |
Array.<LuCI.network.Device>
getErrors() → {Array.<string>}
Query interface error messages published in ubus runtime state.
Interface errors are emitted by remote protocol handlers if the setup of the underlying logical interface failed, e.g. due to bad configuration or network connectivity issues.
This function will translate the found error codes to human readable messages using the descriptions registered by Network.registerErrorCode() and fall back to "Unknown error (%s)" where %s is replaced by the error code in case no translation can be found.
- Source
Returns:Returns an array of translated interface error messages.
- Type:
- Array.<string>
getExpiry() → {number}
Get the logical interface expiry time in seconds.
For protocols that have a concept of a lease, such as DHCP or DHCPv6, this function returns the remaining time in seconds until the lease expires.
- Source
Returns:Returns the number of seconds until the lease expires or -1 if it isn't applicable to the associated protocol.
- Type:
- number
getGateway6Addr() → {string}
Query the gateway (nexthop) of the IPv6 default route associated with this logical interface.
- Source
Returns:Returns a string containing the IPv6 nexthop address of the associated default route or null if no default route was found.
- Type:
- string
getGatewayAddr() → {string}
Query the gateway (nexthop) of the default route associated with this logical interface.
- Source
Returns:Returns a string containing the IPv4 nexthop address of the associated default route or null if no default route was found.
- Type:
- string
(abstract) getI18n() → {string}
Return a human readable description for the protocol, such as Static address or DHCP client.
This function should be overridden by subclasses.
- Source
Returns:Returns the description string.
- Type:
- string
getIP6Addr() → {null|string}
Query the first (primary) IPv6 address of the logical interface.
- Source
Returns:Returns the primary IPv6 address registered by the protocol handler in CIDR notation or null if no IPv6 addresses were set.
- Type:
- null |
string
getIP6Addrs() → {Array.<string>}
Query all IPv6 addresses of the logical interface.
- Source
Returns:Returns an array of IPv6 addresses in CIDR notation which have been registered by the protocol handler. The order of the resulting array follows the order of the addresses in ubus runtime information.
- Type:
- Array.<string>
getIP6Prefix() → {null|string}
Query the routed IPv6 prefix associated with the logical interface.
- Source
Returns:Returns the routed IPv6 prefix registered by the remote protocol handler or null if no prefix is present.
- Type:
- null |
string
getIP6Prefixes() → {null|Array.<string>}
Query the routed IPv6 prefixes associated with the logical interface.
- Source
Returns:Returns an array of the routed IPv6 prefixes registered by the remote protocol handler or null if no prefixes are present.
- Type:
- null |
Array.<string>
getIPAddr() → {null|string}
Query the first (primary) IPv4 address of the logical interface.
- Source
Returns:Returns the primary IPv4 address registered by the protocol handler or null if no IPv4 addresses were set.
- Type:
- null |
string
getIPAddrs() → {Array.<string>}
Query all IPv4 addresses of the logical interface.
- Source
Returns:Returns an array of IPv4 addresses in CIDR notation which have been registered by the protocol handler. The order of the resulting array follows the order of the addresses in ubus runtime information.
- Type:
- Array.<string>
getIfname() → {null|string}
Get the associated Linux network device of this network.
- Source
Returns:Returns the name of the associated network device or null if it could not be determined.
- Type:
- null |
string
getL2Device() → {LuCI.network.Device}
Returns the layer 2 Linux network device currently associated with this logical interface.
- Source
Returns:Returns a Network.Device class instance representing the Linux network device currently associated with the logical interface.
- Type:
- LuCI.
network.Device
getL3Device() → {LuCI.network.Device}
Returns the layer 3 Linux network device currently associated with this logical interface.
- Source
Returns:Returns a Network.Device class instance representing the Linux network device currently associated with the logical interface.
- Type:
- LuCI.
network.Device
getMetric() → {number}
Get the metric value of the logical interface.
- Source
Returns:Returns the current metric value used for device and network routes spawned by the associated logical interface.
- Type:
- number
getName() → {string}
Get the name of the associated logical interface.
- Source
Returns:Returns the logical interface name, such as lan or wan.
- Type:
- string
getNetmask() → {null|string}
Query the first (primary) IPv4 netmask of the logical interface.
- Source
Returns:Returns the netmask of the primary IPv4 address registered by the protocol handler or null if no IPv4 addresses were set.
- Type:
- null |
string
(abstract) getPackageName() → {string}
Gets the name of the package providing the protocol functionality. The package is available via the system default package manager. This is used when a config refers to a protocol handler which is not yet installed.
This function should be overridden by protocol specific subclasses.
- Source
Returns:Returns the name of the package to download, required for the protocol to function, e.g. odhcp6c for the dhcpv6 protocol.
- Type:
- string
(abstract) getProtocol() → {string}
Get the name of this network protocol class.
This function will be overridden by subclasses created by Network.registerProtocol().
- Source
Returns:Returns the name of the network protocol implementation, e.g. static or dhcp.
- Type:
- string
getType() → {null|string}
Get the type of the underlying interface.
This function actually is a convenience wrapper around proto.get("type") and is mainly used by other LuCI.network code to check whether the interface is declared as bridge in UCI.
- Source
Returns:Returns the value of the type option of the associated logical interface or null if no type option is set.
- Type:
- null |
string
getUptime() → {number}
Get the uptime of the logical interface.
- Source
Returns:Returns the uptime of the associated interface in seconds.
- Type:
- number
getZoneName() → {null|string}
Get the requested firewall zone name of the logical interface.
Some protocol implementations request a specific firewall zone to trigger inclusion of their resulting network devices into the firewall rule set.
- Source
Returns:Returns the requested firewall zone name as published in the ubus runtime information or null if the remote protocol handler didn't request a zone.
- Type:
- null |
string
isAlias() → {null|string}
Checks whether this interface is an alias interface.
Alias interfaces are interfaces layering on top of another interface and are denoted by a special @interfacename notation in the underlying device option.
- Source
Returns:Returns the name of the parent interface if this logical interface is an alias or null if it is not an alias interface.
- Type:
- null |
string
isBridge() → {boolean}
Checks whether the underlying logical interface is declared as bridge.
- Source
Returns:Returns true when the interface is declared with option type bridge and when the associated protocol implementation is not marked virtual or false when the logical interface is no bridge.
- Type:
- boolean
(abstract) isCreateable(ifname) → {Promise.<void>}
Check function for the protocol handler if a new interface is creatable.
This function should be overridden by protocol specific subclasses.
Parameters:Name Type Description ifnamestring The name of the interface to be created.
- Source
Returns:Returns a promise resolving if a new interface is creatable, else rejects with an error message string.
- Type:
- Promise.<void>
isDynamic() → {boolean}
Checks whether this logical interface is dynamic.
A dynamic interface is an interface that has been created at runtime. E.g. as a sub-interface of another interface, but which is not backed by any user configuration. Such dynamic interfaces cannot be edited but only brought down or restarted.
- Source
Returns:Returns a boolean indicating whether this interface is dynamic (true) or not (false).
- Type:
- boolean
isEmpty() → {boolean}
Checks whether this logical interface is "empty", where empty means that it has no network devices attached.
- Source
Returns:Returns true if this logical interface is empty, else false.
- Type:
- boolean
isFloating() → {boolean}
Checks whether this protocol is "floating".
A "floating" protocol is a protocol which spawns its own interfaces on demand, like a virtual one but which relies on an existing lower level interface to initiate the connection.
An example for such a protocol is "pppoe".
This function exists for backwards compatibility with older code but should not be used anymore.
- Deprecated
- Yes
- Source
Returns:Returns a boolean indicating whether this protocol is floating (true) or not (false).
- Type:
- boolean
(abstract) isInstalled() → {boolean}
Checks whether the protocol functionality is installed.
This function exists for compatibility with old code, it always returns true.
- Deprecated
- Yes
- Source
Returns:Returns true if the protocol support is installed, else false.
- Type:
- boolean
isPending() → {boolean}
Checks whether this logical interface is pending.
- Source
Returns:returns true when the interface is pending or false when it is not.
- Type:
- boolean
isUp() → {boolean}
Checks whether this logical interface is configured and running.
- Source
Returns:Returns true when the interface is active or false when it is not.
- Type:
- boolean
isVirtual() → {boolean}
Checks whether this protocol is "virtual".
A "virtual" protocol is a protocol which spawns its own interfaces on demand instead of using existing physical interfaces.
Examples for virtual protocols are 6in4 which gre spawn a tunnel network device on startup, examples for non-virtual protocols are dhcp or static which apply IP configuration to existing interfaces.
This function should be overridden by subclasses.
- Source
Returns:Returns a boolean indicating whether the underlying protocol spawns dynamic interfaces (true) or not (false).
- Type:
- boolean
set(opt, val) → {null}
Set the given UCI option of this network to the given value.
Parameters:Name Type Description optstring The name of the UCI option to set.
valnull | string | Array.<string> The value to set or null to remove the given option from the configuration.
- Source
Returns:- Type:
- null
Class: WifiDevice On this pageLuCI.network. WifiDevice
A Network.WifiDevice class instance represents a wireless radio device present on the system and provides wireless capability information as well as methods for enumerating related wireless networks.
- Source
Methods
addWifiNetwork(optionsopt) → {Promise.<(null|LuCI.network.WifiNetwork)>}
Adds a new wireless network associated with this radio device to the configuration and sets its options to the provided values.
Parameters:Name Type Attributes Description optionsObject.<string, (string|Array.<string>)> <optional>
The options to set for the newly added wireless network.
- Source
Returns:Returns a promise resolving to a WifiNetwork instance describing the newly added wireless network or null if the given options were invalid.
- Type:
- Promise.<(null|LuCI.network.WifiNetwork)>
deleteWifiNetwork(network) → {Promise.<boolean>}
Deletes the wireless network with the given name associated with this radio device.
Parameters:Name Type Description networkstring The name of the wireless network to look up. This may be either an uci configuration section ID, a network ID in the form radio#.network# or a Linux network device name like wlan0 which is resolved to the corresponding configuration section through ubus runtime information.
- Source
Returns:Returns a promise resolving to true when the wireless network was successfully deleted from the configuration or false when the given network could not be found or if the found network was not associated with this wireless radio device.
- Type:
- Promise.<boolean>
get(opt) → {null|string|Array.<string>}
Read the given UCI option value of this wireless device.
Parameters:Name Type Description optstring The UCI option name to read.
- Source
Returns:Returns the UCI option value or null if the requested option is not found.
- Type:
- null |
string | Array.<string>
getHTModes() → {Array.<string>}
Gets a list of supported htmodes.
The htmode values describe the wide-frequency options supported by the wireless phy.
- Source
Returns:Returns an array of valid htmode values for this radio. Currently known mode values are:
HT20 - applicable to IEEE 802.11n, 20 MHz wide channelsHT40 - applicable to IEEE 802.11n, 40 MHz wide channelsVHT20 - applicable to IEEE 802.11ac, 20 MHz wide channelsVHT40 - applicable to IEEE 802.11ac, 40 MHz wide channelsVHT80 - applicable to IEEE 802.11ac, 80 MHz wide channelsVHT160 - applicable to IEEE 802.11ac, 160 MHz wide channelsHE20 - applicable to IEEE 802.11ax, 20 MHz wide channelsHE40 - applicable to IEEE 802.11ax, 40 MHz wide channelsHE80 - applicable to IEEE 802.11ax, 80 MHz wide channelsHE160 - applicable to IEEE 802.11ax, 160 MHz wide channelsEHT20 - applicable to IEEE 802.11be, 20 MHz wide channelsEHT40 - applicable to IEEE 802.11be, 40 MHz wide channelsEHT80 - applicable to IEEE 802.11be, 80 MHz wide channelsEHT160 - applicable to IEEE 802.11be, 160 MHz wide channelsEHT320 - applicable to IEEE 802.11be, 320 MHz wide channels
- Type:
- Array.<string>
getHWModes() → {Array.<string>}
Gets a list of supported hwmodes.
The hwmode values describe the frequency band and wireless standard versions supported by the wireless phy.
- Source
Returns:Returns an array of valid hwmode values for this radio. Currently known mode values are:
a - Legacy 802.11a mode, 5 GHz, up to 54 Mbit/sb - Legacy 802.11b mode, 2.4 GHz, up to 11 Mbit/sg - Legacy 802.11g mode, 2.4 GHz, up to 54 Mbit/sn - IEEE 802.11n mode, 2.4 or 5 GHz, up to 600 Mbit/sac - IEEE 802.11ac mode, 5 GHz, up to 6770 Mbit/sax - IEEE 802.11ax mode, 2.4 or 5 GHz- 'be' - IEEE 802.11be mode, 2.4, 5 or 6 GHz
- Type:
- Array.<string>
getI18n() → {string}
Get a string describing the wireless radio hardware.
- Source
Returns:Returns the description string.
- Type:
- string
getName() → {string}
Get the configuration name of this wireless radio.
- Source
Returns:Returns the UCI section name (e.g. radio0) of the corresponding radio configuration, which also serves as a unique logical identifier for the wireless phy.
- Type:
- string
getScanList() → {Promise.<Array.<LuCI.network.WifiScanResult>>}
Trigger a wireless scan on this radio device and obtain a list of nearby networks.
- Source
Returns:Returns a promise resolving to an array of scan result objects describing the networks found in the vicinity.
- Type:
- Promise.<Array.<LuCI.network.WifiScanResult>>
getWifiNetwork(network) → {Promise.<LuCI.network.WifiNetwork>}
Get the wifi network of the given name belonging to this radio device
Parameters:Name Type Description networkstring The name of the wireless network to look up. This may be either an uci configuration section ID, a network ID in the form radio#.network# or a Linux network device name like wlan0 which is resolved to the corresponding configuration section through ubus runtime information.
- Source
Returns:Returns a promise resolving to a Network.WifiNetwork instance representing the wireless network and rejecting with null if the given network could not be found or is not associated with this radio device.
- Type:
- Promise.<LuCI.network.WifiNetwork>
getWifiNetworks() → {Promise.<Array.<LuCI.network.WifiNetwork>>}
Get all wireless networks associated with this wireless radio device.
- Source
Returns:Returns a promise resolving to an array of Network.WifiNetwork instances representing the wireless networks associated with this radio device.
- Type:
- Promise.<Array.<LuCI.network.WifiNetwork>>
isDisabled() → {boolean}
Checks whether this wireless radio is disabled.
- Source
Returns:Returns true when the wireless radio is marked as disabled in ubus runtime state or when the disabled option is set in the corresponding UCI configuration.
- Type:
- boolean
isUp() → {boolean}
Check whether the wireless radio is marked as up in the ubus runtime state.
- Source
Returns:Returns true when the radio device is up, else false.
- Type:
- boolean
set(opt, value) → {null}
Set the given UCI option of this network to the given value.
Parameters:Name Type Description optstring The name of the UCI option to set.
valuenull | string | Array.<string> The value to set or null to remove the given option from the configuration.
- Source
Returns:- Type:
- null
Class: WifiNetwork On this pageLuCI.network. WifiNetwork
A Network.WifiNetwork instance represents a wireless network (vif) configured on top of a radio device and provides functions for querying the runtime state of the network. Most radio devices support multiple such networks in parallel.
- Source
Methods
disconnectClient(mac, deauthopt, reasonopt, ban_timeopt) → {Promise.<number>}
Forcibly disconnect the given client from the wireless network.
Parameters:Name Type Attributes Default Description macstring The MAC address of the client to disconnect.
deauthboolean <optional>
false Specifies whether to de-authenticate (true) or disassociate (false) the client.
reasonnumber <optional>
1 Specifies the IEEE 802.11 reason code to disassoc/deauth the client with. Default is 1 which corresponds to Unspecified reason.
ban_timenumber <optional>
0 Specifies the number of milliseconds to ban the client from reconnecting. By default, no ban time is set which allows the client to re-associate / reauthenticate immediately.
- Source
Returns:Returns a promise resolving to the underlying ubus call result code which is typically 0, even for not existing MAC addresses. The promise might reject with an error in case invalid arguments are passed.
- Type:
- Promise.<number>
get(opt) → {null|string|Array.<string>}
Read the given UCI option value of this wireless network.
Parameters:Name Type Description optstring The UCI option name to read.
- Source
Returns:Returns the UCI option value or null if the requested option is not found.
- Type:
- null |
string | Array.<string>
getActiveBSSID() → {string}
Query the current BSSID from runtime information.
- Source
Returns:Returns the current BSSID or Mesh ID as reported by ubus runtime information.
- Type:
- string
getActiveEncryption() → {string}
Query the current encryption settings from runtime information.
- Source
Returns:Returns a string describing the current encryption or - if the encryption state could not be found in ubus runtime information.
- Type:
- string
getActiveMode() → {string}
Query the current operation mode from runtime information.
- Source
Returns:Returns the human readable mode name as reported by iwinfo or uci mode. Possible returned values are:
MasterAd-HocClientMonitorMaster (VLAN)WDSMesh PointP2P ClientP2P GoUnknown
- Type:
- string
getActiveModeI18n() → {string}
Query the current operation mode from runtime information as translated string.
- Source
Returns:Returns the translated, human readable mode name as reported by ubus runtime state.
- Type:
- string
getActiveSSID() → {string}
Query the current SSID from runtime information.
- Source
Returns:Returns the current SSID or Mesh ID as reported by ubus runtime information.
- Type:
- string
getAssocList() → {Promise.<Array.<LuCI.network.WifiPeerEntry>>}
Fetch the list of associated peers.
- Source
Returns:Returns a promise resolving to an array of wireless peers associated with this network.
- Type:
- Promise.<Array.<LuCI.network.WifiPeerEntry>>
getBSSID() → {null|string}
Get the configured BSSID of the wireless network.
- Source
Returns:Returns the BSSID value or null if none has been specified.
- Type:
- null |
string
getBitRate() → {null|number}
Query the current average bit-rate of all peers associated with this wireless network.
- Source
Returns:Returns the average bit rate among all peers associated with the network as reported by ubus runtime information or null if the information is not available.
- Type:
- null |
number
getChannel() → {null|number}
Query the current wireless channel.
- Source
Returns:Returns the wireless channel as reported by ubus runtime information or null if it cannot be determined.
- Type:
- null |
number
getCountryCode() → {string}
Query the current country code.
- Source
Returns:Returns the wireless country code as reported by ubus runtime information or 00 if it cannot be determined.
- Type:
- string
getDevice() → {LuCI.network.Device}
Get the associated Linux network device.
- Source
Returns:Returns a Network.Device instance representing the Linux network device associated with this wireless network.
- Type:
- LuCI.
network.Device
getFrequency() → {null|string}
Query the current operating frequency of the wireless network.
- Source
Returns:Returns the current operating frequency of the network from ubus runtime information in GHz or null if the information is not available.
- Type:
- null |
string
getI18n() → {string}
Get a description string for this wireless network.
- Source
Returns:Returns a string describing this network, consisting of the term Wireless Network, followed by the active operation mode, the SSID, BSSID or internal network ID and the Linux network device name, depending on which information is available.
- Type:
- string
getID() → {string}
Get the internal network ID of this wireless network.
The network ID is a LuCI specific identifier in the form radio#.network# to identify wireless networks by their corresponding radio and network index numbers.
- Source
Returns:Returns the LuCI specific network ID.
- Type:
- string
getIfname() → {null|string}
Get the Linux network device name.
- Source
Returns:Returns the current Linux network device name as resolved from ubus runtime information or null if this network has no associated network device, e.g. when not configured or up.
- Type:
- null |
string
getMeshID() → {null|string}
Get the configured Mesh ID of the wireless network.
- Source
Returns:Returns the configured mesh ID value or null when this network is not in mesh mode.
- Type:
- null |
string
getMode() → {string}
Get the configured operation mode of the wireless network.
- Source
Returns:Returns the configured operation mode. Possible values are:
ap - Master (Access Point) modesta - Station (client) modeadhoc - Ad-Hoc (IBSS) modemesh - Mesh (IEEE 802.11s) modemonitor - Monitor mode
- Type:
- string
getName() → {string}
Get the configuration ID of this wireless network.
- Source
Returns:Returns the corresponding UCI section ID of the network.
- Type:
- string
getNetwork() → {null|LuCI.network.Protocol}
Get the primary logical interface this network is attached to.
- Source
Returns:Returns a Network.Protocol instance representing the logical interface or null if this network is not attached to any logical interface.
- Type:
- null |
LuCI.network.Protocol
getNetworkNames() → {Array.<string>}
Get the names of the logical interfaces this wireless network is attached to.
- Source
Returns:Returns an array of logical interface names.
- Type:
- Array.<string>
getNetworks() → {Array.<LuCI.network.Protocol>}
Get the logical interfaces this network is attached to.
- Source
Returns:Returns an array of Network.Protocol instances representing the logical interfaces this wireless network is attached to.
- Type:
- Array.<LuCI.network.Protocol>
getNoise() → {number}
Query the current radio noise floor.
- Source
Returns:Returns the radio noise floor in dBm as reported by ubus runtime information or 0 if it cannot be determined.
- Type:
- number
getSSID() → {null|string}
Get the configured SSID of the wireless network.
- Source
Returns:Returns the configured SSID value or null when this network is in mesh mode.
- Type:
- null |
string
getShortName() → {string}
Get a short description string for this wireless network.
- Source
Returns:Returns a string describing this network, consisting of the active operation mode, followed by either the SSID, BSSID or internal network ID, depending on which information is available.
- Type:
- string
getSignal() → {null|number}
Query the current wireless signal.
- Source
Returns:Returns the wireless signal in dBm as reported by ubus runtime information or null if it cannot be determined.
- Type:
- null |
number
getSignalLevel(signal, noise) → {number}
Calculate the current signal.
Parameters:Name Type Description signalnumber noisenumber
- Deprecated
- Yes
- Source
Returns:Returns the calculated signal level, which is the difference between noise and signal (SNR), divided by 5.
- Type:
- number
getSignalPercent() → {number}
Calculate the current signal quality percentage.
- Source
Returns:Returns the calculated signal quality in percent. The value is calculated from the quality and quality_max indicators reported by ubus runtime state.
- Type:
- number
getTXPower() → {null|number}
Query the current radio TX power.
- Source
Returns:Returns the wireless network transmit power in dBm as reported by ubus runtime information or null if it cannot be determined.
- Type:
- null |
number
getTXPowerOffset() → {number}
Query the radio TX power offset.
Some wireless radios have a fixed power offset, e.g. due to the use of external amplifiers.
- Source
Returns:Returns the wireless network transmit power offset in dBm as reported by ubus runtime information or 0 if there is no offset, or if it cannot be determined.
- Type:
- number
getVlanIfnames() → {Array.<string>}
Get the Linux VLAN network device names.
- Source
Returns:Returns the current Linux VLAN network device name as resolved from ubus runtime information or empty array if this network has no associated VLAN network devices.
- Type:
- Array.<string>
getVlans() → {Array.<LuCI.network.WifiVlan>}
Fetch the vlans for this network.
- Source
Returns:Returns an array of vlans for this network.
- Type:
- Array.<LuCI.network.WifiVlan>
getWifiDevice() → {null|LuCI.network.WifiDevice}
Get the corresponding WiFi radio device.
- Source
Returns:Returns a Network.WifiDevice instance representing the corresponding WiFi radio device or null if the related radio device could not be found.
- Type:
- null |
LuCI.network.WifiDevice
getWifiDeviceName() → {null|string}
Get the name of the corresponding WiFi radio device.
- Source
Returns:Returns the name of the radio device this network is configured on or null if it cannot be determined.
- Type:
- null |
string
isClientDisconnectSupported() → {boolean}
Check whether this WiFi network supports de-authenticating clients.
- Source
Returns:Returns true when this WiFi network instance supports forcibly de-authenticating clients, otherwise false.
- Type:
- boolean
isDisabled() → {boolean}
Checks whether this wireless network is disabled.
- Source
Returns:Returns true when the wireless radio is marked as disabled in ubus runtime state or when the disabled option is set in the corresponding UCI configuration.
- Type:
- boolean
isUp() → {boolean}
Check whether the radio network is up.
This function actually queries the up state of the related radio device and assumes this network to be up as well when the parent radio is up. This is due to the fact that OpenWrt does not control virtual interfaces individually but within one common hostapd instance.
- Source
Returns:Returns true when the network is up, else false.
- Type:
- boolean
set(opt, value) → {null}
Set the given UCI option of this network to the given value.
Parameters:Name Type Description optstring The name of the UCI option to set.
valuenull | string | Array.<string> The value to set or null to remove the given option from the configuration.
- Source
Returns:- Type:
- null
Class: WifiVlan On this pageLuCI.network. WifiVlan
A Network.WifiVlan class instance represents a vlan on a WifiNetwork.
- Source
Methods
getI18n() → {string}
Get a long description string for the wifi vlan.
- Source
Returns:Returns a string containing the vlan id and the vlan name, if it is different than the vlan id
- Type:
- string
getIfname() → {string}
Get the Linux network device name of the wifi vlan.
- Source
Returns:Returns the current network device name for this wifi vlan.
- Type:
- string
getName() → {string}
Get the name of the wifi vlan.
- Source
Returns:Returns the name.
- Type:
- string
getNetwork() → {string}
Get the network of the wifi vlan.
- Source
Returns:Returns the network.
- Type:
- string
getVlanId() → {number}
Get the vlan id of the wifi vlan.
- Source
Returns:Returns the vlan id.
- Type:
- number
Class: network On this pageLuCI. network
The LuCI.network class combines data from multiple ubus APIs to provide an abstraction of the current network configuration state.
It provides methods to enumerate interfaces and devices, to query current configuration details and to manipulate settings.
- Source
Classes
Methods
addNetwork(name, optionsopt) → {Promise.<(null|LuCI.network.Protocol)>}
Adds a new network of the given name and update it with the given uci option values.
If a network with the given name already exist but is empty, then this function will update its option, otherwise it will do nothing.
Parameters:Name Type Attributes Description namestring The name of the network to add. Must be in the format [a-zA-Z0-9_]+.
optionsObject.<string, (string|Array.<string>)> <optional>
An object of uci option values to set on the new network or to update in an existing, empty network.
- Source
Returns:Returns a promise resolving to the Protocol subclass instance describing the added network or resolving to null if the name was invalid or if a non-empty network of the given name already existed.
- Type:
- Promise.<(null|LuCI.network.Protocol)>
addWifiNetwork(options) → {Promise.<(null|LuCI.network.WifiNetwork)>}
Adds a new wireless network to the configuration and sets its options to the provided values.
Parameters:Name Type Description optionsObject.<string, (string|Array.<string>)> The options to set for the newly added wireless network. This object must at least contain a device property which is set to the radio name the new network belongs to.
- Source
Returns:Returns a promise resolving to a WifiNetwork instance describing the newly added wireless network or null if the given options were invalid or if the associated radio device could not be found.
- Type:
- Promise.<(null|LuCI.network.WifiNetwork)>
deleteNetwork(name) → {Promise.<boolean>}
Deletes the given network and its references from the network and firewall configuration.
Parameters:Name Type Description namestring The name of the network to delete.
- Source
Returns:Returns a promise resolving to either true if the network and references to it were successfully deleted from the configuration or false if the given network could not be found.
- Type:
- Promise.<boolean>
deleteWifiNetwork(netname) → {Promise.<boolean>}
Deletes the given wireless network from the configuration.
Parameters:Name Type Description netnamestring The name of the network to remove. This may be either a network ID in the form radio#.network# or a Linux network device name like wlan0 which is resolved to the corresponding configuration section through ubus runtime information.
- Source
Returns:Returns a promise resolving to true if the wireless network has been successfully deleted from the configuration or false if it could not be found.
- Type:
- Promise.<boolean>
flushCache() → {Promise.<Object>}
Flushes the local network state cache and fetches updated information from the remote ubus apis.
- Source
Returns:Returns a promise resolving to the internal network state object.
- Type:
- Promise.<Object>
formatWifiEncryption(encryption) → {null|string}
Converts a given encryption entry into a human readable string such as mixed WPA/WPA2 PSK (TKIP, CCMP) or WPA3 SAE (CCMP).
Parameters:Name Type Description encryptionLuCI.network.WifiEncryption The wireless encryption entry to convert.
- Source
Returns:Returns the description string for the given encryption entry or null if the given entry was invalid.
- Type:
- null |
string
getDSLModemType() → {Promise.<(null|string)>}
Queries the internal DSL modem type from board information.
- Source
Returns:Returns a promise resolving to the type of the internal modem (e.g. vdsl) or to null if no internal modem is present.
- Type:
- Promise.<(null|string)>
getDevice(name) → {Promise.<(null|LuCI.network.Device)>}
Get a Device instance describing the given network device.
Parameters:Name Type Description namestring The name of the network device to get, e.g. eth0 or br-lan.
- Source
Returns:Returns a promise resolving to the Device instance describing the network device or null if the given device name could not be found.
- Type:
- Promise.<(null|LuCI.network.Device)>
getDevices() → {Promise.<Array.<LuCI.network.Device>>}
Get a sorted list of all found network devices.
- Source
Returns:Returns a promise resolving to a sorted array of Device class instances describing the network devices found on the system.
- Type:
- Promise.<Array.<LuCI.network.Device>>
getHostHints() → {Promise.<LuCI.network.Hosts>}
Queries aggregated information about known hosts.
This function aggregates information from various sources such as DHCP lease databases, ARP and IPv6 neighbour entries, wireless association list etc. and returns a Hosts class instance describing the found hosts.
- Source
Returns:Returns a Hosts instance describing a host known on the system.
- Type:
- Promise.<LuCI.network.Hosts>
getIfnameOf(obj) → {null|string}
Obtains the network device name of the given object.
Parameters:Name Type Description objLuCI.network.Protocol | LuCI.network.Device | LuCI.network.WifiDevice | LuCI.network.WifiNetwork | string The object to get the device name from.
- Source
Returns:Returns a string containing the device name or null if the given object could not be converted to a name.
- Type:
- null |
string
getNetwork(name) → {Promise.<(null|LuCI.network.Protocol)>}
Get a Protocol instance describing the network with the given name.
Parameters:Name Type Description namestring The logical interface name of the network get, e.g. lan or wan.
- Source
Returns:Returns a promise resolving to a Protocol subclass instance describing the network or null if the network did not exist.
- Type:
- Promise.<(null|LuCI.network.Protocol)>
getNetworks() → {Promise.<Array.<LuCI.network.Protocol>>}
Gets an array containing all known networks.
- Source
Returns:Returns a promise resolving to a name-sorted array of Protocol subclass instances describing all known networks.
- Type:
- Promise.<Array.<LuCI.network.Protocol>>
getProtocol(protoname, netnameopt) → {null|LuCI.network.Protocol}
Instantiates the given Protocol back-end, optionally using the given network name.
Parameters:Name Type Attributes Default Description protonamestring The protocol back-end to use, e.g. static or dhcp.
netnamestring <optional>
__dummy__ The network name to use for the instantiated protocol. This should be usually set to one of the interfaces described in /etc/config/network but it is allowed to omit it, e.g. to query protocol capabilities without the need for an existing interface.
- Source
Returns:Returns the instantiated protocol back-end class or null if the given protocol isn't known.
- Type:
- null |
LuCI.network.Protocol
getProtocols() → {Array.<LuCI.network.Protocol>}
Obtains instances of all known Protocol back-end classes.
- Source
Returns:Returns an array of protocol class instances.
- Type:
- Array.<LuCI.network.Protocol>
getSwitchTopologies() → {Promise.<Object.<string, LuCI.network.SwitchTopology>>}
Returns the topologies of all swconfig switches found on the system.
- Source
Returns:Returns a promise resolving to an object containing the topologies of each switch. The object keys correspond to the name of the switches such as switch0, the values are SwitchTopology objects describing the layout.
- Type:
- Promise.<Object.<string, LuCI.network.SwitchTopology>>
getWAN6Networks() → {Promise.<Array.<LuCI.network.Protocol>>}
Get IPv6 wan networks.
This function looks up all networks having a default ::/0 route and returns them as an array.
- Source
Returns:Returns a promise resolving to an array of Protocol subclass instances describing the found IPv6 default route interfaces.
- Type:
- Promise.<Array.<LuCI.network.Protocol>>
getWANNetworks() → {Promise.<Array.<LuCI.network.Protocol>>}
Get IPv4 wan networks.
This function looks up all networks having a default 0.0.0.0/0 route and returns them as an array.
- Source
Returns:Returns a promise resolving to an array of Protocol subclass instances describing the found default route interfaces.
- Type:
- Promise.<Array.<LuCI.network.Protocol>>
getWifiDevice(devname) → {Promise.<(null|LuCI.network.WifiDevice)>}
Get a WifiDevice instance describing the given wireless radio.
Parameters:Name Type Description devnamestring The configuration name of the wireless radio to look up, e.g. radio0 for the first mac80211 phy on the system.
- Source
Returns:Returns a promise resolving to the WifiDevice instance describing the underlying radio device or null if the wireless radio could not be found.
- Type:
- Promise.<(null|LuCI.network.WifiDevice)>
getWifiDevices() → {Promise.<Array.<LuCI.network.WifiDevice>>}
Obtain a list of all configured radio devices.
- Source
Returns:Returns a promise resolving to an array of WifiDevice instances describing the wireless radios configured in the system. The order of the array corresponds to the order of the radios in the configuration.
- Type:
- Promise.<Array.<LuCI.network.WifiDevice>>
getWifiNetwork(netname) → {Promise.<(null|LuCI.network.WifiNetwork)>}
Get a WifiNetwork instance describing the given wireless network.
Parameters:Name Type Description netnamestring The name of the wireless network to look up. This may be either an uci configuration section ID, a network ID in the form radio#.network# or a Linux network device name like wlan0 which is resolved to the corresponding configuration section through ubus runtime information.
- Source
Returns:Returns a promise resolving to the WifiNetwork instance describing the wireless network or null if the corresponding network could not be found.
- Type:
- Promise.<(null|LuCI.network.WifiNetwork)>
getWifiNetworks() → {Promise.<Array.<LuCI.network.WifiNetwork>>}
Get an array of all WifiNetwork instances describing the wireless networks present on the system.
- Source
Returns:Returns a promise resolving to an array of WifiNetwork instances describing the wireless networks. The array will be empty if no networks are found.
- Type:
- Promise.<Array.<LuCI.network.WifiNetwork>>
isIgnoredDevice(name) → {boolean}
Test if a given network device name is in the list of patterns for device names to ignore.
Ignored device names are usually Linux network devices which are spawned implicitly by kernel modules such as tunl0 or hwsim0 and which are unsuitable for use in network configuration.
Parameters:Name Type Description namestring The device name to test.
- Source
Returns:Returns true if the given name is in the ignore-pattern list, else returns false.
- Type:
- boolean
maskToPrefix(netmask, v6opt) → {null|number}
Converts the given netmask to a prefix size in bits.
Parameters:Name Type Attributes Default Description netmaskstring The netmask to convert into a bits count.
v6boolean <optional>
false Whether to parse the given netmask as IPv4 (false) or IPv6 (true) address.
- Source
Returns:Returns the number of prefix bits contained in the netmask or null if the given netmask value was invalid.
- Type:
- null |
number
prefixToMask(bits, v6opt) → {null|string}
Converts the given prefix size in bits to a netmask.
Parameters:Name Type Attributes Default Description bitsnumber The prefix size in bits.
v6boolean <optional>
false Whether to convert the bits value into an IPv4 netmask (false) or an IPv6 netmask (true).
- Source
Returns:Returns a string containing the netmask corresponding to the bit count or null when the given amount of bits exceeds the maximum possible value of 32 for IPv4 or 128 for IPv6.
- Type:
- null |
string
registerErrorCode(code, message) → {boolean}
Registers a new human readable translation string for a Protocol error code.
Parameters:Name Type Description codestring The ubus protocol error code to register a translation for, e.g. NO_DEVICE.
messagestring The message to use as a translation for the given protocol error code.
- Source
Returns:Returns true if the error code description has been added or false if either the arguments were invalid or if there already was a description for the given code.
- Type:
- boolean
registerPatternVirtual(pat)
Registers a new regular expression pattern to recognize virtual interfaces.
Parameters:Name Type Description patRegExp A RegExp instance to match a virtual interface name such as 6in4-wan or tun0.
- Source
registerProtocol(protoname, methods) → {LuCI.network.Protocol}
Registers a new Protocol subclass with the given methods and returns the resulting subclass value.
This function internally calls baseclass.extend() on the Network.Protocol base class.
Parameters:Name Type Description protonamestring The name of the new protocol to register.
methodsObject.<string, *> The member methods and values of the new Protocol subclass to be passed to baseclass.extend().
- Source
Returns:Returns the new Protocol subclass.
- Type:
- LuCI.
network.Protocol
renameNetwork(oldName, newName) → {Promise.<boolean>}
Rename the given network and its references to a new name.
Parameters:Name Type Description oldNamestring The current name of the network.
newNamestring The name to rename the network to, must be in the format [a-z-A-Z0-9_]+.
- Source
Returns:Returns a promise resolving to either true if the network was successfully renamed or false if the new name was invalid, if a network with the new name already exists or if the network to rename could not be found.
- Type:
- Promise.<boolean>
Type Definitions
SwitchTopology
Describes a swconfig switch topology by specifying the CPU connections and external port labels of a switch.
Type:- Object.<string, (Object|Array)>
PropertiesName Type Description netdevsObject.<number, string> The netdevs property points to an object describing the CPU port connections of the switch. The numeric key of the enclosed object is the port number, the value contains the Linux network device name the port is hardwired to.
portsArray.<Object.<string, (boolean|number|string)>> The ports property points to an array describing the populated ports of the switch in the external label order. Each array item is an object containing the following keys:
num - the internal switch port numberlabel - the label of the port, e.g. LAN 1 or CPU (eth0)device - the connected Linux network device name (CPU ports only)tagged - a boolean indicating whether the port must be tagged to function (CPU ports only)
- Source
WifiEncryption
An encryption entry describes active wireless encryption settings such as the used key management protocols, active ciphers and protocol versions.
Type:- Object.<string, (boolean|Array.<(number|string)>)>
PropertiesName Type Attributes Description enabledboolean Specifies whether any kind of encryption, such as WEP or WPA is enabled. If set to false, then no encryption is active and the corresponding network is open.
wepArray.<string> <optional>
When the wep property exists, the network uses WEP encryption. In this case, the property is set to an array of active WEP modes which might be either open, shared or both.
wpaArray.<number> <optional>
When the wpa property exists, the network uses WPA security. In this case, the property is set to an array containing the WPA protocol versions used, e.g. [ 1, 2 ] for WPA/WPA2 mixed mode or [ 3 ] for WPA3-SAE.
authenticationArray.<string> <optional>
The authentication property only applies to WPA encryption and is defined when the wpa property is set as well. It points to an array of active authentication suites used by the network, e.g. [ "psk" ] for a WPA(2)-PSK network or [ "psk", "sae" ] for mixed WPA2-PSK/WPA3-SAE encryption.
ciphersArray.<string> <optional>
If either WEP or WPA encryption is active, then the ciphers property will be set to an array describing the active encryption ciphers used by the network, e.g. [ "tkip", "ccmp" ] for a WPA/WPA2-PSK mixed network or [ "wep-40", "wep-104" ] for an WEP network.
- Source
WifiPeerEntry
A wireless peer entry describes the properties of a remote wireless peer associated with a local network.
Type:- Object.<string, (boolean|number|string|LuCI.network.WifiRateEntry)>
PropertiesName Type Attributes Description macstring The MAC address (BSSID).
signalnumber The received signal strength.
signal_avgnumber <optional>
The average signal strength if supported by the driver.
noisenumber <optional>
The current noise floor of the radio. May be 0 or absent if not supported by the driver.
inactivenumber The number of milliseconds the peer has been inactive, e.g. due to power-saving.
connected_timenumber The number of milliseconds the peer is associated to this network.
thrnumber <optional>
The estimated throughput of the peer, May be 0 or absent if not supported by the driver.
authorizedboolean Specifies whether the peer is authorized to associate to this network.
authenticatedboolean Specifies whether the peer completed authentication to this network.
preamblestring The preamble mode used by the peer. May be long or short.
wmeboolean Specifies whether the peer supports WME/WMM capabilities.
mfpboolean Specifies whether management frame protection is active.
tdlsboolean Specifies whether TDLS is active.
mesh_llidnumber <optional>
The mesh LLID, may be 0 or absent if not applicable or supported by the driver.
mesh_plidnumber <optional>
The mesh PLID, may be 0 or absent if not applicable or supported by the driver.
mesh_plinkstring <optional>
The mesh peer link state description, may be an empty string ('') or absent if not applicable or supported by the driver.
The following states are known:
LISTENOPN_SNTOPN_RCVDCNF_RCVDESTABHOLDINGBLOCKEDUNKNOWN
mesh_local_PSnumber <optional>
The local power-save mode for the peer link, may be an empty string ('') or absent if not applicable or supported by the driver.
The following modes are known:
ACTIVE (no power save)LIGHT SLEEPDEEP SLEEPUNKNOWN
mesh_peer_PSnumber <optional>
The remote power-save mode for the peer link, may be an empty string ('') or absent if not applicable or supported by the driver.
The following modes are known:
ACTIVE (no power save)LIGHT SLEEPDEEP SLEEPUNKNOWN
mesh_non_peer_PSnumber <optional>
The power-save mode for all non-peer neighbours, may be an empty string ('') or absent if not applicable or supported by the driver.
The following modes are known:
ACTIVE (no power save)LIGHT SLEEPDEEP SLEEPUNKNOWN
rxLuCI.network.WifiRateEntry Describes the receiving wireless rate from the peer.
txLuCI.network.WifiRateEntry Describes the transmitting wireless rate to the peer.
- Source
WifiRateEntry
A wireless rate entry describes the properties of a wireless transmission rate to or from a peer.
Type:- Object.<string, (boolean|number)>
PropertiesName Type Attributes Description drop_miscnumber <optional>
The amount of received misc. packages that have been dropped, e.g. due to corruption or missing authentication. Only applicable to receiving rates.
packetsnumber The amount of packets that have been received or sent.
bytesnumber The amount of bytes that have been received or sent.
failednumber <optional>
The amount of failed transmission attempts. Only applicable to transmit rates.
retriesnumber <optional>
The amount of retried transmissions. Only applicable to transmit rates.
is_htboolean Specifies whether this rate is an HT (IEEE 802.11n) rate.
is_vhtboolean Specifies whether this rate is an VHT (IEEE 802.11ac) rate.
mhznumber The channel width in MHz used for the transmission.
ratenumber The bitrate in bit/s of the transmission.
mcsnumber <optional>
The MCS index of the used transmission rate. Only applicable to HT or VHT rates.
40mhznumber <optional>
Specifies whether the transmission rate used 40MHz wide channel. Only applicable to HT or VHT rates.
Note: this option exists for backwards compatibility only, and its use is discouraged. The mhz field should be used instead to determine the channel width.
short_giboolean <optional>
Specifies whether a short guard interval is used for the transmission. Only applicable to HT or VHT rates.
nssnumber <optional>
Specifies the number of spatial streams used by the transmission. Only applicable to VHT rates.
heboolean <optional>
Specifies whether this rate is an HE (IEEE 802.11ax) rate.
he_ginumber <optional>
Specifies whether the guard interval used for the transmission. Only applicable to HE rates.
he_dcmnumber <optional>
Specifies whether dual concurrent modulation is used for the transmission. Only applicable to HE rates.
ehtboolean <optional>
Specifies whether this rate is an EHT (IEEE 802.11be) rate.
eht_ginumber <optional>
Specifies whether the guard interval is used for the transmission. Only applicable to EHT rates.
eht_dcmnumber <optional>
Specifies whether dual concurrent modulation is used for the transmission. Only applicable to EHT rates.
- Source
WifiScanResult
A wireless scan result object describes a neighbouring wireless network found in the vicinity.
Type:- Object.<string, (number|string|LuCI.network.WifiEncryption)>
PropertiesName Type Description ssidstring The SSID / Mesh ID of the network.
bssidstring The BSSID if the network.
modestring The operation mode of the network (Master, Ad-Hoc, Mesh Point).
channelnumber The wireless channel of the network.
signalnumber The received signal strength of the network in dBm.
qualitynumber The numeric quality level of the signal, can be used in conjunction with quality_max to calculate a quality percentage.
quality_maxnumber The maximum possible quality level of the signal, can be used in conjunction with quality to calculate a quality percentage.
encryptionLuCI.network.WifiEncryption The encryption used by the wireless network.
- Source
Class: poll On this pageLuCI. poll
The Poll class allows registering and unregistering poll actions, as well as starting, stopping, and querying the state of the polling loop.
Methods
active() → {boolean}
Test whether the polling loop is running.
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:Name Type Description fnfunction The function to invoke on each poll interval.
intervalnumber The poll interval in seconds.
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:Name Type Description fnfunction The function to remove.
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.
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.
Returns:Returns true if polling has been stopped or false if it didn't run to begin with.
- Type:
- boolean
Class: request On this pageLuCI. request
The Request class allows initiating HTTP requests and provides utilities for dealing with responses.
Classes
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:Name Type Description interceptorFnLuCI.request.interceptorFn The interceptor function to register.
Returns:The registered function.
expandURL(url) → {string}
Turn the given relative URL into an absolute URL if necessary.
Parameters:Name Type Description urlstring The URL to convert.
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:Name Type Attributes Description urlstring The URL to request.
optionsLuCI.request.RequestOptions <optional>
Additional options to configure the request.
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:Name Type Attributes Description 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).
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:Name Type Attributes Description 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.
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:Name Type Description interceptorFnLuCI.request.interceptorFn The interceptor function to remove.
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:Name Type Attributes Description targetstring The URL to request.
optionsLuCI.request.RequestOptions <optional>
Additional options to configure the request.
Returns:The resulting HTTP response.
- Type:
- Promise.<LuCI.response>
Type Definitions
RequestOptions
Type:- Object
PropertiesName Type Attributes Default Description 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.
interceptorFn(res)
Interceptor functions are invoked whenever an HTTP reply is received, in the order these functions have been registered.
Parameters:Name Type Description resLuCI.response The HTTP response object
Class: poll On this pageLuCI.request. poll
The Request.poll class provides some convenience wrappers around LuCI.poll mainly to simplify registering repeating HTTP request calls as polling functions.
Methods
active() → {boolean}
Alias for LuCI.poll.active().
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:Name Type Attributes Description 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.
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:Name Type Description entryfunction The poll function returned by add().
Returns:Returns true if any function has been removed, else false.
- Type:
- boolean
start() → {boolean}
Alias for LuCI.poll.start().
Returns:- Type:
- boolean
stop() → {boolean}
Alias for LuCI.poll.stop().
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:Name Type Description 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.
Class: response On this pageLuCI. response
The Response class is an internal utility class representing HTTP responses.
Members
duration :number
The total duration of the HTTP request in milliseconds
Type:- number
headers :LuCI.headers
The HTTP headers of the response
Type:
ok :boolean
Describes whether the response is successful (status codes 200..299) or not
Type:- boolean
status :number
The numeric HTTP status code of the response
Type:- number
statusText :string
The HTTP status description message of the response
Type:- string
url :string
The final URL of the request, i.e. after following redirects.
Type:- string
Methods
blob() → {Blob}
Access the response content as blob.
Returns:The response content as blob.
- Type:
- Blob
clone(contentopt) → {LuCI.response}
Clones the given response object, optionally overriding the content of the cloned instance.
Parameters:Name Type Attributes Description content* <optional>
Override the content of the cloned response. Object values will be treated as JSON response data, all other types will be converted using String() and treated as response text.
Returns:The cloned Response instance.
- Type:
- LuCI.
response
json() → {*}
Access the response content as JSON data.
Throws:Throws SyntaxError if the content isn't valid JSON.
- Type
- SyntaxError
Returns:The parsed JSON data.
- Type:
- *
text() → {string}
Access the response content as string.
Returns:The response content.
- Type:
- string
Class: rpc On this pageLuCI. rpc
The LuCI.rpc class provides high level ubus JSON-RPC abstractions and means for listing and invoking remove RPC methods.
Methods
addInterceptor(interceptorFn) → {LuCI.rpc.interceptorFn}
Registers a new interceptor function.
Parameters:Name Type Description interceptorFnLuCI.rpc.interceptorFn The interceptor function to register.
Returns:Returns the given function value.
- Type:
- LuCI.
rpc.interceptorFn
declare(options) → {LuCI.rpc.invokeFn}
Describes a remote RPC call procedure and returns a function implementing it.
Parameters:Name Type Description optionsLuCI.rpc.DeclareOptions If any object names are given, this function will return the method signatures of each given object.
Returns:Returns a new function implementing the method call described in options.
- Type:
- LuCI.
rpc.invokeFn
getBaseURL() → {string}
Returns the current RPC base URL.
Returns:Returns the RPC URL endpoint to issue requests against.
- Type:
- string
getSessionID() → {string}
Returns the current RPC session id.
Returns:Returns the 32 byte session ID string used for authenticating remote requests.
- Type:
- string
getStatusText(statusCode) → {string}
Translates a numeric ubus error code into a human readable description.
Parameters:Name Type Description statusCodenumber The numeric status code.
Returns:Returns the textual description of the code.
- Type:
- string
list(…argsopt) → {Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)>}
Lists available remote ubus objects or the method signatures of specific objects.
This function has two signatures and is sensitive to the number of arguments passed to it:
list() - Returns an array containing the names of all remote ubus objectslist("objname", ...) Returns method signatures for each given ubus object name.
Parameters:Name Type Attributes Description argsstring <optional>
<repeatable>
(objectNames) If any object names are given, this function will return the method signatures of each given object.
Returns:When invoked without arguments, this function will return a promise resolving to an array of ubus object names. When invoked with one or more arguments, a promise resolving to an object describing the method signatures of each requested ubus object name will be returned.
- Type:
- Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)>
removeInterceptor(interceptorFn) → {boolean}
Removes a registered interceptor function.
Parameters:Name Type Description interceptorFnLuCI.rpc.interceptorFn The interceptor function to remove.
Returns:Returns true if the given function has been removed or false if it has not been found.
- Type:
- boolean
setBaseURL(url)
Set the RPC base URL to use.
Parameters:Name Type Description urlstring Sets the RPC URL endpoint to issue requests against.
setSessionID(sid)
Set the RPC session id to use.
Parameters:Name Type Description sidstring Sets the 32 byte session ID string used for authenticating remote requests.
Type Definitions
DeclareOptions
Type:- Object
PropertiesName Type Attributes Default Description objectstring The name of the remote ubus object to invoke.
methodstring The name of the remote ubus method to invoke.
paramsArray.<string> <optional>
Lists the named parameters expected by the remote ubus RPC method. The arguments passed to the resulting generated method call function will be mapped to named parameters in the order they appear in this array.
Extraneous parameters passed to the generated function will not be sent to the remote procedure but are passed to the filter function if one is specified.
Examples:
params: [ "foo", "bar" ] - When the resulting call function is invoked with fn(true, false), the corresponding args object sent to the remote procedure will be { foo: true, bar: false }.params: [ "test" ], filter: function(reply, args, extra) { ... } - When the resulting generated function is invoked with fn("foo", "bar", "baz") then { "test": "foo" } will be sent as argument to the remote procedure and the filter function will be invoked with filterFn(reply, [ "foo" ], "bar", "baz")
expectObject.<string, *> <optional>
Describes the expected return data structure. The given object is supposed to contain a single key selecting the value to use from the returned ubus reply object. The value of the sole key within the expect object is used to infer the expected type of the received ubus reply data.
If the received data does not contain expect's key, or if the type of the data differs from the type of the value in the expect object, the expect object's value is returned as default instead.
The key in the expect object may be an empty string ('') in which case the entire reply object is selected instead of one of its subkeys.
If the expect option is omitted, the received reply will be returned as-is, regardless of its format or type.
Examples:
expect: { '': { error: 'Invalid response' } } - This requires the entire ubus reply to be a plain JavaScript object. If the reply isn't an object but e.g. an array or a numeric error code instead, it will get replaced with { error: 'Invalid response' } instead.expect: { results: [] } - This requires the received ubus reply to be an object containing a key results with an array as value. If the received reply does not contain such a key, or if reply.results points to a non-array value, the empty array ([]) will be used instead.expect: { success: false } - This requires the received ubus reply to be an object containing a key success with a boolean value. If the reply does not contain success or if reply.success is not a boolean value, false will be returned as default instead.
filterLuCI.rpc.filterFn <optional>
Specifies an optional filter function which is invoked to transform the received reply data before it is returned to the caller.
rejectboolean <optional>
false If set to true, non-zero ubus call status codes are treated as fatal error and lead to the rejection of the call promise. The default behaviour is to resolve with the call return code value instead.
filterFn(data, args, …extraArgs) → {*}
The filter function is invoked to transform a received ubus RPC call reply before returning it to the caller.
Parameters:Name Type Attributes Description data* The received ubus reply data or a subset of it as described in the expect option of the RPC call declaration. In case of remote call errors, data is numeric ubus error code instead.
argsArray.<*> The arguments the RPC method has been invoked with.
extraArgs* <repeatable>
All extraneous arguments passed to the RPC method exceeding the number of arguments describes in the RPC call declaration.
Returns:The return value of the filter function will be returned to the caller of the RPC method as-is.
- Type:
- *
invokeFn(…params) → {Promise.<*>}
The generated invocation function is returned by rpc.declare() and encapsulates a single RPC method call.
Calling this function will execute a remote ubus HTTP call request using the arguments passed to it as arguments and return a promise resolving to the received reply values.
Parameters:Name Type Attributes Description params* <repeatable>
The parameters to pass to the remote procedure call. The given positional arguments will be named to named RPC parameters according to the names specified in the params array of the method declaration.
Any additional parameters exceeding the amount of arguments in the params declaration are passed as private extra arguments to the declared filter function.
Returns:Returns a promise resolving to the result data of the remote ubus RPC method invocation, optionally substituted and filtered according to the expect and filter declarations.
- Type:
- Promise.<*>
interceptorFn(msg, req) → {Promise.<*>|*}
Registered interceptor functions are invoked before the standard reply parsing and handling logic.
By returning rejected promises, interceptor functions can cause the invocation function to fail, regardless of the received reply.
Interceptors may also modify their message argument in-place to rewrite received replies before they're processed by the standard response handling code.
A common use case for such functions is to detect failing RPC replies due to expired authentication in order to trigger a new login.
Parameters:Name Type Description msg* The unprocessed, JSON decoded remote RPC method call reply.
Since interceptors run before the standard parsing logic, the reply data is not verified for correctness or filtered according to expect and filter specifications in the declarations.
reqObject The related request object which is an extended variant of the declaration object, allowing access to internals of the invocation function such as filter, expect or params values.
Returns:Interceptor functions may return a promise to defer response processing until some delayed work completed. Any values the returned promise resolves to are ignored.
When the returned promise rejects with an error, the invocation function will fail too, forwarding the error to the caller.
- Type:
- Promise.<*> |
*
Class: session On this pageLuCI. session
The session class provides various session related functionality.
Methods
getID() → {string}
Retrieve the current session ID.
Returns:Returns the current session ID.
- Type:
- string
getLocalData(keyopt) → {*}
Retrieve data from the local session storage.
Parameters:Name Type Attributes Description keystring <optional>
The key to retrieve from the session data store. If omitted, all session data will be returned.
Returns:Returns the stored session data or null if the given key wasn't found.
- Type:
- *
getToken() → {string|null}
Retrieve the current session token.
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:Name Type Description 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.
Returns:Returns true if the data could be stored or false on error.
- Type:
- boolean
Class: uci On this pageLuCI. uci
The LuCI.uci class utilizes LuCI.rpc to declare low level remote UCI ubus procedures and implements a local caching and data manipulation layer on top to allow for synchronous operations on UCI configuration data.
Methods
add(conf, type, nameopt) → {string}
Adds a new section of the given type to the given configuration, optionally named according to the given name.
Parameters:Name Type Attributes Description confstring The name of the configuration to add the section to.
typestring The type of the section to add.
namestring <optional>
The name of the section to add. If the name is omitted, an anonymous section will be added instead.
Returns:Returns the section ID of the newly added section which is equivalent to the given name for non-anonymous sections.
- Type:
- string
apply(timeoutopt) → {Promise.<number>}
Instructs the remote ubus UCI api to commit all saved changes with rollback protection and attempts to confirm the pending commit operation to cancel the rollback timer.
Parameters:Name Type Attributes Default Description timeoutnumber <optional>
10 Override the confirmation timeout after which a rollback is triggered.
Returns:Returns a promise resolving/rejecting with the ubus RPC status code.
- Type:
- Promise.<number>
changes() → {Promise.<Object.<string, Array.<LuCI.uci.ChangeRecord>>>}
Fetches uncommitted UCI changes from the remote ubus RPC api.
Returns:Returns a promise resolving to an object containing the configuration names as keys and arrays of related change records as values.
- Type:
- Promise.<Object.<string, Array.<LuCI.uci.ChangeRecord>>>
clone(conf, type, srcsid, put_nextopt, nameopt) → {string}
Clones an existing section of the given type to the given configuration, optionally named according to the given name.
Parameters:Name Type Attributes Description confstring The name of the configuration into which to clone the section.
typestring The type of the section to clone.
srcsidstring The source section id to clone.
put_nextboolean <optional>
Whether to put the cloned item next (true) or last (false: default).
namestring <optional>
The name of the new cloned section. If the name is omitted, an anonymous section will be created instead.
Returns:Returns the section ID of the newly cloned section which is equivalent to the given name for non-anonymous sections.
- Type:
- string
createSID(conf) → {string}
Generates a new, unique section ID for the given configuration.
Note that the generated ID is temporary, it will get replaced by an identifier in the form cfgXXXXXX once the configuration is saved by the remote ubus UCI api.
Parameters:Name Type Description confstring The configuration to generate the new section ID for.
Returns:A newly generated, unique section ID in the form newXXXXXX where X denotes a hexadecimal digit.
- Type:
- string
get(conf, sid, optopt) → {null|string|Array.<string>|LuCI.uci.SectionObject}
Gets the value of the given option within the specified section of the given configuration or the entire section object if the option name is omitted.
Parameters:Name Type Attributes Description confstring The name of the configuration to read the value from.
sidstring The name or ID of the section to read.
optstring <optional>
The option name to read the value from. If the option name is omitted or null, the entire section is returned instead.
Returns:- Returns a string containing the option value in case of a plain UCI option.
- Returns an array of strings containing the option values in case of
option pointing to an UCI list. - Returns a
section object if the option argument has been omitted or is null. - Returns
null if the config, section or option has not been found or if the corresponding configuration is not loaded.
- Type:
- null |
string | Array.<string> | LuCI.uci.SectionObject
get_bool(conf, type, optopt) → {boolean}
A special case of get that always returns either true or false.
Many configuration files contain boolean settings, such as enabled or advanced_mode, where there is no consistent definition for the values. This function allows users to enter any of the values "yes", "on", "true", "enabled" or 1 in their config files and we return the expected boolean result.
Character case is not significant, so for example, any of "YES", "Yes" or "yes" will be interpreted as a true value.
Parameters:Name Type Attributes Description confstring The name of the configuration to read.
typestring The section type to read.
optstring <optional>
The option name from which to read the value. If the option name is omitted or null, the value false is returned.
Returns:- Returns boolean
true if the configuration value is defined and looks like a true value, otherwise returns false.
See the Developers Guide for more.
- Type:
- boolean
get_first(conf, typeopt, optopt) → {null|string|Array.<string>|LuCI.uci.SectionObject}
Gets the value of the given option or the entire section object of the first found section of the specified type or the first found section of the entire configuration if no type is specified.
Parameters:Name Type Attributes Description confstring The name of the configuration to read the value from.
typestring <optional>
The type of the first section to find. If it is null, the first section of the entire config is read, otherwise the first section matching the given type.
optstring <optional>
The option name to read the value from. If the option name is omitted or null, the entire section is returned instead.
Returns:- Returns a string containing the option value in case of a plain UCI option.
- Returns an array of strings containing the option values in case of
option pointing to an UCI list. - Returns a
section object if the option argument has been omitted or is null. - Returns
null if the config, section or option has not been found or if the corresponding configuration is not loaded.
- Type:
- null |
string | Array.<string> | LuCI.uci.SectionObject
load(packages) → {Promise.<Array.<string>>}
Loads the given UCI configurations from the remote ubus api.
Loaded configurations are cached and only loaded once. Subsequent load operations of the same configurations will return the cached data.
To force reloading a configuration, it has to be unloaded with uci.unload() first.
Parameters:Name Type Description packagesstring | Array.<string> The name of the configuration or an array of configuration names to load.
Returns:Returns a promise resolving to the names of the configurations that have been successfully loaded.
- Type:
- Promise.<Array.<string>>
move(conf, sid1, sid2opt, afteropt) → {boolean}
Move the first specified section within the given configuration before or after the second specified section.
Parameters:Name Type Attributes Default Description confstring The configuration to move the section within.
sid1string The ID of the section to move within the configuration.
sid2string <optional>
The ID of the target section for the move operation. If the after argument is false or not specified, the section named by sid1 will be moved before this target section, if the after argument is true, the sid1 section will be moved after this section.
When the sid2 argument is null, the section specified by sid1 is moved to the end of the configuration.
afterboolean <optional>
false When true, the section sid1 is moved after the section sid2, when false, the section sid1 is moved before sid2.
If sid2 is null, then this parameter has no effect and the section sid1 is moved to the end of the configuration instead.
Returns:Returns true when the section was successfully moved, or false when either the section specified by sid1 or by sid2 is not found.
- Type:
- boolean
remove(conf, sid)
Removes the section with the given ID from the given configuration.
Parameters:Name Type Description confstring The name of the configuration to remove the section from.
sidstring The ID of the section to remove.
resolveSID(conf, sid) → {string|null}
Resolves a given section ID in extended notation to the internal section ID value.
Parameters:Name Type Description confstring The configuration to resolve the section ID for.
sidstring The section ID to resolve. If the ID is in the form @typename[#], it will get resolved to an internal anonymous ID in the forms cfgXXXXXX/newXXXXXX or to the name of a section in case it points to a named section. When the given ID is not in extended notation, it will be returned as-is.
Returns:Returns the resolved section ID or the original given ID if it was not in extended notation. Returns null when an extended ID could not be resolved to existing section ID.
- Type:
- string |
null
save() → {Array.<string>}
Submits all local configuration changes to the remove ubus api, adds, removes and reorders remote sections as needed and reloads all loaded configurations to resynchronize the local state with the remote configuration values.
Returns:Returns a promise resolving to an array of configuration names which have been reloaded by the save operation.
- Type:
- Array.<string>
sections(conf, typeopt, cbopt) → {Array.<LuCI.uci.SectionObject>}
Enumerates the sections of the given configuration, optionally filtered by type.
Parameters:Name Type Attributes Description confstring The name of the configuration to enumerate the sections for.
typestring <optional>
Enumerate only sections of the given type. If omitted, enumerate all sections.
cbLuCI.uci.sections <optional>
An optional callback to invoke for each enumerated section.
Returns:Returns a sorted array of the section objects within the given configuration, filtered by type, if a type has been specified.
- Type:
- Array.<LuCI.uci.SectionObject>
set(conf, sid, opt, val)
Sets the value of the given option within the specified section of the given configuration.
If either config, section or option is null, or if option begins with a dot, the function will do nothing.
Parameters:Name Type Description confstring The name of the configuration to set the option value in.
sidstring The name or ID of the section to set the option value in.
optstring The option name to set the value for.
valnull | string | Array.<string> The option value to set. If the value is null or an empty string, the option will be removed, otherwise it will be set or overwritten with the given value.
set_first(conf, typeopt, opt, val) → {null}
Sets the value of the given option within the first found section of the given configuration matching the specified type or within the first section of the entire config when no type has is specified.
If either config, type or option is null, or if option begins with a dot, the function will do nothing.
Parameters:Name Type Attributes Description confstring The name of the configuration to set the option value in.
typestring <optional>
The type of the first section to find. If it is null, the first section of the entire config is written to, otherwise the first section matching the given type is used.
optstring The option name to set the value for.
valnull | string | Array.<string> The option value to set. If the value is null or an empty string, the option will be removed, otherwise it will be set or overwritten with the given value.
Returns:- Type:
- null
unload(packages)
Unloads the given UCI configurations from the local cache.
Parameters:Name Type Description packagesstring | Array.<string> The name of the configuration or an array of configuration names to unload.
unset(conf, sid, opt) → {null}
Remove the given option within the specified section of the given configuration.
This function is a convenience wrapper around uci.set(config, section, option, null).
Parameters:Name Type Description confstring The name of the configuration to remove the option from.
sidstring The name or ID of the section to remove the option from.
optstring The name of the option to remove.
Returns:- Type:
- null
unset_first(conf, typeopt, opt) → {null}
Removes the given option within the first found section of the given configuration matching the specified type or within the first section of the entire config when no type has is specified.
This function is a convenience wrapper around uci.set_first(config, type, option, null).
Parameters:Name Type Attributes Description confstring The name of the configuration to set the option value in.
typestring <optional>
The type of the first section to find. If it is null, the first section of the entire config is written to, otherwise the first section matching the given type is used.
optstring The option name to set the value for.
Returns:- Type:
- null
Type Definitions
ChangeRecord
An UCI change record is a plain array containing the change operation name as first element, the affected section ID as second argument and an optional third and fourth argument whose meanings depend on the operation.
Type:- Array.<string>
PropertiesName Type Attributes Description operationstring The operation name - may be one of add, set, remove, order, list-add, list-del or rename.
section_idstring The section ID targeted by the operation.
parameterstring The meaning of the third element depends on the operation.
- For
add it is type of the section that has been added - For
set it either is the option name if a fourth element exists, or the type of a named section which has been added when the change entry only contains three elements. - For
remove it contains the name of the option that has been removed. - For
order it specifies the new sort index of the section. - For
list-add it contains the name of the list option a new value has been added to. - For
list-del it contains the name of the list option a value has been removed from. - For
rename it contains the name of the option that has been renamed if a fourth element exists, else it contains the new name a section has been renamed to if the change entry only contains three elements.
valuestring <optional>
The meaning of the fourth element depends on the operation.
- For
set it is the value an option has been set to. - For
list-add it is the new value that has been added to a list option. - For
rename it is the new name of an option that has been renamed.
SectionObject
A section object represents the options and their corresponding values enclosed within a configuration section, as well as some additional meta data such as sort indexes and internal ID.
Any internal metadata fields are prefixed with a dot which isn't an allowed character for normal option names.
Type:- Object.<string, (boolean|number|string|Array.<string>)>
PropertiesName Type Description ".anonymous"boolean The .anonymous property specifies whether the configuration is anonymous (true) or named (false).
".index"number The .index property specifies the sort order of the section.
".name"string The .name property holds the name of the section object. It may be either an anonymous ID in the form cfgXXXXXX or newXXXXXX with X being a hexadecimal digit or a string holding the name of the section.
".type"string The .type property contains the type of the corresponding uci section.
*string | Array.<string> A section object may contain an arbitrary number of further properties representing the uci option enclosed in the section.
All option property names will be in the form [A-Za-z0-9_]+ and either contain a string value or an array of strings, in case the underlying option is an UCI list.
sections(section, sid)
The sections callback is invoked for each section found within the given configuration and receives the section object and its associated name as arguments.
Parameters:Name Type Description sectionLuCI.uci.SectionObject The section object.
sidstring The name or ID of the section.
Class: AbstractElement On this pageLuCI.ui. AbstractElement
The AbstractElement class serves as abstract base for the different widgets implemented by LuCI.ui. It provides the common logic for getting and setting values, for checking the validity state and for wiring up required events.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.AbstractElement. To import it in external JavaScript, use L.require("ui").then(...) and access the AbstractElement property of the class instance value.
Methods
getValidationError() → {string}
Returns the current validation error
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
(abstract) render() → {Node}
Render the widget, set up event listeners and return resulting markup.
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
Returns:- Type:
- boolean
Type Definitions
InitOptions
Type:- Object
PropertiesName Type Attributes Default Description idstring <optional>
Specifies the widget ID to use. It will be used as HTML id attribute on the toplevel widget DOM node.
namestring <optional>
Specifies the widget name which is set as HTML name attribute on the corresponding <input> element.
optionalboolean <optional>
true Specifies whether the input field allows empty values.
datatypestring <optional>
string An expression describing the input data validation constraints. It defaults to string which will allow any value. See LuCI.validation for details on the expression format.
validatorfunction | Array.<function()> <optional>
Specifies one or more custom validator functions which are invoked after the standard validation constraints are checked. Each function should return true to accept the given input value. When multiple functions are provided as an array, they are executed serially and validation stops at the first function that returns a non-true value. Any non-true return value type is converted to a string and treated as a validation error message.
disabledboolean <optional>
false Specifies whether the widget should be rendered in disabled state (true) or not (false). Disabled widgets cannot be interacted with and are displayed in a slightly faded style.
Class: Checkbox On this pageLuCI.ui. Checkbox
The Checkbox class implements a simple checkbox input field.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Checkbox. To import it in external JavaScript, use L.require("ui").then(...) and access the Checkbox property of the class instance value.
Constructor
new Checkbox(valueopt, optionsopt)
Instantiate a checkbox widget.
Parameters:Name Type Attributes Default Description valuestring <optional>
null The initial input value.
optionsLuCI.ui.Checkbox.InitOptions <optional>
Object describing the widget specific options to initialize the input.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isChecked() → {boolean}
Test whether the checkbox is currently checked.
Returns:Returns true when the checkbox is currently checked, otherwise false.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description value_enabledstring <optional>
1 Specifies the value corresponding to a checked checkbox.
value_disabledstring <optional>
0 Specifies the value corresponding to an unchecked checkbox.
hiddennamestring <optional>
Specifies the HTML name attribute of the hidden input backing the checkbox. This is a legacy property existing for compatibility reasons, it is required for HTML based form submissions.
Class: ComboButton On this pageLuCI.ui. ComboButton
The ComboButton class implements a button element which can be expanded into a dropdown to chose from a set of different action choices.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.ComboButton. To import it in external JavaScript, use L.require("ui").then(...) and access the ComboButton property of the class instance value.
Constructor
new ComboButton(valueopt, choices, optionsopt)
Instantiate a combo button widget offering multiple action choices.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value(s).
choicesObject.<string, *> Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels.
optionsLuCI.ui.ComboButton.InitOptions <optional>
Object describing the widget specific options to initialize the button.
Extends
Methods
addChoices(values, labels)
Add new choices to the dropdown menu.
This function adds further choices to an existing dropdown menu, ignoring choice values which are already present.
Parameters:Name Type Description valuesArray.<string> The choice values to add to the dropdown widget.
labelsObject.<string, *> The choice label values to use when adding dropdown choices. If no label is found for a particular choice value, the value itself is used as label text. Choice labels may be any valid value accepted by LuCI.dom#content.
- Inherited From
clearChoices(reset_valueopt)
Remove all existing choices from the dropdown menu.
This function removes all preexisting dropdown choices from the widget, keeping only choices currently being selected unless reset_values is given, in which case all choices and deselected and removed.
Parameters:Name Type Attributes Default Description reset_valueboolean <optional>
false If set to true, deselect and remove selected choices as well instead of keeping them.
- Inherited From
closeAllDropdowns()
Close all open dropdown widgets in the current document.
- Inherited From
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
ComboButtons support the same properties as Dropdown.InitOptions but enforce specific values for some properties and add additional button specific properties.
PropertiesName Type Attributes Default Description multipleboolean <optional>
false Since ComboButtons never allow selecting multiple actions, this property is forcibly set to false.
createboolean <optional>
false Since ComboButtons never allow creating custom choices, this property is forcibly set to false.
optionalboolean <optional>
false Since ComboButtons must always select one action, this property is forcibly set to false.
classesObject.<string, string> <optional>
Specifies a mapping of choice values to CSS class names. If an action choice is selected by the user and if a corresponding entry exists in the classes object, the class names corresponding to the selected value are set on the button element.
This is useful to apply different button styles, such as colors, to the combined button depending on the selected action.
clickfunction <optional>
Specifies a handler function to invoke when the user clicks the button. This function will be called with the button DOM node as this context and receive the DOM click event as first as well as the selected action choice value as second argument.
Class: Combobox On this pageLuCI.ui. Combobox
The Combobox class implements a rich, stylable dropdown menu which allows to enter custom values. Historically, comboboxes used to be a dedicated widget type in LuCI but nowadays they are direct aliases of dropdown widgets with a set of enforced default properties for easier instantiation.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Combobox. To import it in external JavaScript, use L.require("ui").then(...) and access the Combobox property of the class instance value.
Constructor
new Combobox(valueopt, choices, optionsopt)
Instantiate a rich dropdown choice widget allowing custom values.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value(s).
choicesObject.<string, *> Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels.
optionsLuCI.ui.Combobox.InitOptions <optional>
Object describing the widget specific options to initialize the dropdown.
Extends
Methods
addChoices(values, labels)
Add new choices to the dropdown menu.
This function adds further choices to an existing dropdown menu, ignoring choice values which are already present.
Parameters:Name Type Description valuesArray.<string> The choice values to add to the dropdown widget.
labelsObject.<string, *> The choice label values to use when adding dropdown choices. If no label is found for a particular choice value, the value itself is used as label text. Choice labels may be any valid value accepted by LuCI.dom#content.
- Inherited From
clearChoices(reset_valueopt)
Remove all existing choices from the dropdown menu.
This function removes all preexisting dropdown choices from the widget, keeping only choices currently being selected unless reset_values is given, in which case all choices and deselected and removed.
Parameters:Name Type Attributes Default Description reset_valueboolean <optional>
false If set to true, deselect and remove selected choices as well instead of keeping them.
- Inherited From
closeAllDropdowns()
Close all open dropdown widgets in the current document.
- Inherited From
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
Comboboxes support the same properties as Dropdown.InitOptions but enforce specific values for the following properties:
PropertiesName Type Attributes Default Description multipleboolean <optional>
false Since Comboboxes never allow selecting multiple values, this property is forcibly set to false.
createboolean <optional>
true Since Comboboxes always allow custom choice values, this property is forcibly set to true.
optionalboolean <optional>
true Since Comboboxes are always optional, this property is forcibly set to true.
Class: Dropdown On this pageLuCI.ui. Dropdown
The Dropdown class implements a rich, stylable dropdown menu which supports non-text choice labels.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Dropdown. To import it in external JavaScript, use L.require("ui").then(...) and access the Dropdown property of the class instance value.
Constructor
new Dropdown(valueopt, choices, optionsopt)
Instantiate a rich dropdown choice widget.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value(s).
choicesObject.<string, *> Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels.
optionsLuCI.ui.Dropdown.InitOptions <optional>
Object describing the widget specific options to initialize the dropdown.
Extends
Methods
addChoices(values, labels)
Add new choices to the dropdown menu.
This function adds further choices to an existing dropdown menu, ignoring choice values which are already present.
Parameters:Name Type Description valuesArray.<string> The choice values to add to the dropdown widget.
labelsObject.<string, *> The choice label values to use when adding dropdown choices. If no label is found for a particular choice value, the value itself is used as label text. Choice labels may be any valid value accepted by LuCI.dom#content.
clearChoices(reset_valueopt)
Remove all existing choices from the dropdown menu.
This function removes all preexisting dropdown choices from the widget, keeping only choices currently being selected unless reset_values is given, in which case all choices and deselected and removed.
Parameters:Name Type Attributes Default Description reset_valueboolean <optional>
false If set to true, deselect and remove selected choices as well instead of keeping them.
closeAllDropdowns()
Close all open dropdown widgets in the current document.
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description optionalboolean <optional>
true Specifies whether the dropdown selection is optional. In contrast to other widgets, the optional constraint of dropdowns works differently; instead of marking the widget invalid on empty values when set to false, the user is not allowed to deselect all choices.
For single value dropdowns that means that no empty "please select" choice is offered and for multi value dropdowns, the last selected choice may not be deselected without selecting another choice first.
multipleboolean <optional>
Specifies whether multiple choice values may be selected. It defaults to true when an array is passed as input value to the constructor.
sortboolean | Array.<string> <optional>
false Specifies if and how to sort choice values. If set to true, the choice values will be sorted alphabetically. If set to an array of strings, the choice sort order is derived from the array.
select_placeholderstring <optional>
-- Please choose -- Specifies a placeholder text which is displayed when no choice is selected yet.
custom_placeholderstring <optional>
-- custom -- Specifies a placeholder text which is displayed in the text input field allowing to enter custom choice values. Only applicable if the create option is set to true.
createboolean <optional>
false Specifies whether custom choices may be entered into the dropdown widget.
create_querystring <optional>
.create-item-input Specifies a CSS selector expression used to find the input element which is used to enter custom choice values. This should not normally be used except by widgets derived from the Dropdown class.
create_templatestring <optional>
"script[type='item-template']" Specifies a CSS selector expression used to find an HTML element serving as template for newly added custom choice values.
Any {{value}} placeholder string within the template elements text content will be replaced by the user supplied choice value, the resulting string is parsed as HTML and appended to the end of the choice list. The template markup may specify one HTML element with a data-label-placeholder attribute which is replaced by a matching label value from the choices object or with the user supplied value itself in case choices contains no matching choice label.
If the template element is not found or if no create_template selector expression is specified, the default markup for newly created elements is <li data-value="{{value}}"><span data-label-placeholder="true" /></li>.
create_markupstring <optional>
This property allows specifying the markup for custom choices directly instead of referring to a template element through CSS selectors.
Apart from that it works exactly like create_template.
display_itemsnumber <optional>
3 Specifies the maximum amount of choice labels that should be shown in collapsed dropdown state before further selected choices are cut off.
Only applicable when multiple is true.
dropdown_itemsnumber <optional>
-1 Specifies the maximum amount of choices that should be shown when the dropdown is open. If the amount of available choices exceeds this number, the dropdown area must be scrolled to reach further items.
If set to -1, the dropdown menu will attempt to show all choice values and only resort to scrolling if the amount of choices exceeds the available screen space above and below the dropdown widget.
placeholderstring <optional>
This property serves as a shortcut to set both select_placeholder and custom_placeholder. Either of these properties will fallback to placeholder if not specified.
readonlyboolean <optional>
false Specifies whether the custom choice input field should be rendered readonly. Only applicable when create is true.
maxlengthnumber <optional>
Specifies the HTML maxlength attribute to set on the custom choice <input> element. Note that this a legacy property that exists for compatibility reasons. It is usually better to maxlength(N) validation expression. Only applicable when create is true.
Class: DynamicList On this pageLuCI.ui. DynamicList
The DynamicList class implements a widget which allows the user to specify an arbitrary amount of input values, either from free formed text input or from a set of predefined choices.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.DynamicList. To import it in external JavaScript, use L.require("ui").then(...) and access the DynamicList property of the class instance value.
Constructor
new DynamicList(valueopt, choicesopt, optionsopt)
Instantiate a dynamic list widget.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value(s).
choicesObject.<string, *> <optional>
Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels. If omitted, no default choices are presented to the user, instead a plain text input field is rendered allowing the user to add arbitrary values to the dynamic list.
optionsLuCI.ui.DynamicList.InitOptions <optional>
Object describing the widget specific options to initialize the dynamic list.
Extends
Methods
addChoices(values, labels)
Add new suggested choices to the dynamic list.
This function adds further choices to an existing dynamic list, ignoring choice values which are already present.
Parameters:Name Type Description valuesArray.<string> The choice values to add to the dynamic lists suggestion dropdown.
labelsObject.<string, *> The choice label values to use when adding suggested choices. If no label is found for a particular choice value, the value itself is used as label text. Choice labels may be any valid value accepted by LuCI.dom#content.
clearChoices()
Remove all existing choices from the dynamic list.
This function removes all preexisting suggested choices from the widget.
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In case choices are passed to the dynamic list constructor, the widget supports the same properties as Dropdown.InitOptions but enforces specific values for some dropdown properties.
PropertiesName Type Attributes Default Description multipleboolean <optional>
false Since dynamic lists never allow selecting multiple choices when adding another list item, this property is forcibly set to false.
optionalboolean <optional>
true Since dynamic lists use an embedded dropdown to present a list of predefined choice values, the dropdown must be made optional to allow it to remain unselected.
Class: FileUpload On this pageLuCI.ui. FileUpload
The FileUpload class implements a widget which allows the user to upload, browse, select and delete files beneath a predefined remote directory.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.FileUpload. To import it in external JavaScript, use L.require("ui").then(...) and access the FileUpload property of the class instance value.
Constructor
new FileUpload(valueopt, optionsopt)
Instantiate a file upload widget.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value.
optionsLuCI.ui.DynamicList.InitOptions <optional>
Object describing the widget specific options to initialize the file upload control.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description browserboolean <optional>
false Use a file browser mode.
show_hiddenboolean <optional>
false Specifies whether hidden files should be displayed when browsing remote files. Note that this is not a security feature, hidden files are always present in the remote file listings received, this option merely controls whether they're displayed or not.
enable_uploadboolean <optional>
true Specifies whether the widget allows the user to upload files. If set to false, only existing files may be selected. Note that this is not a security feature. Whether file upload requests are accepted remotely depends on the ACL setup for the current session. This option merely controls whether the upload controls are rendered or not.
enable_removeboolean <optional>
true Specifies whether the widget allows the user to delete remove files. If set to false, existing files may not be removed. Note that this is not a security feature. Whether file delete requests are accepted remotely depends on the ACL setup for the current session. This option merely controls whether the file remove controls are rendered or not.
directory_createboolean <optional>
false Specifies whether the widget allows the user to create directories.
directory_selectboolean <optional>
false Specifies whether the widget shall select directories only instead of files.
enable_downloadboolean <optional>
false Specifies whether the widget allows the user to download files.
root_directorystring <optional>
/etc/luci-uploads Specifies the remote directory the upload and file browsing actions take place in. Browsing to directories outside the root directory is prevented by the widget. Note that this is not a security feature. Whether remote directories are browsable or not solely depends on the ACL setup for the current session.
Class: Hiddenfield On this pageLuCI.ui. Hiddenfield
The Hiddenfield class implements an HTML <input type="hidden"> field which allows to store form data without exposing it to the user.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Hiddenfield. To import it in external JavaScript, use L.require("ui").then(...) and access the Hiddenfield property of the class instance value.
Constructor
new Hiddenfield(valueopt, optionsopt)
Instantiate a hidden input field widget.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value.
optionsLuCI.ui.AbstractElement.InitOptions <optional>
Object describing the widget specific options to initialize the hidden input.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Class: RangeSlider On this pageLuCI.ui. RangeSlider
The RangeSlider class implements a widget which allows the user to set a value from a predefined range.
UI widget instances are usually not supposed to be created by view code directly. Instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.RangeSlider. To import it in external JavaScript, use L.require("ui").then(...) and access the RangeSlider property of the class instance value.
Constructor
new RangeSlider(valueopt, optionsopt)
Instantiate a range slider widget.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial value to set the slider handle position.
optionsLuCI.ui.RangeSlider.InitOptions <optional>
Object describing the widget specific options to initialize the range slider.
Extends
Methods
getCalculatedValue() → {number}
Return the value calculated by the calculate function.
Returns:- Type:
- number
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description minnumber <optional>
1 Specifies the minimum value of the range.
maxnumber <optional>
100 Specifies the maximum value of the range.
stepstring <optional>
1 Specifies the step value of the range slider handle. Use "any" for arbitrary precision floating point numbers.
calcunitsstring <optional>
null Specifies a suffix string to append to the calculated value output.
disabledboolean <optional>
false Specifies whether the the widget is disabled.
Class: Select On this pageLuCI.ui. Select
The Select class implements either a traditional HTML <select> element or a group of checkboxes or radio buttons, depending on whether multiple values are enabled or not.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Select. To import it in external JavaScript, use L.require("ui").then(...) and access the Select property of the class instance value.
Constructor
new Select(valueopt, choices, optionsopt)
Instantiate a select dropdown or checkbox/radiobutton group.
Parameters:Name Type Attributes Default Description valuestring | Array.<string> <optional>
null The initial input value(s).
choicesObject.<string, string> Object containing the selectable choices of the widget. The object keys serve as values for the different choices while the values are used as choice labels.
optionsLuCI.ui.Select.InitOptions <optional>
Object describing the widget specific options to initialize the inputs.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description multipleboolean <optional>
false Specifies whether multiple choice values may be selected.
widget"select" | "individual" <optional>
select Specifies the kind of widget to render. May be either select or individual. When set to select an HTML <select> element will be used, otherwise a group of checkbox or radio button elements is created, depending on the value of the multiple option.
orientationstring <optional>
horizontal Specifies whether checkbox / radio button groups should be rendered in a horizontal or vertical manner. Does not apply to the select widget type.
sortboolean | Array.<string> <optional>
false Specifies if and how to sort choice values. If set to true, the choice values will be sorted alphabetically. If set to an array of strings, the choice sort order is derived from the array.
sizenumber <optional>
Specifies the HTML size attribute to set on the <select> element. Only applicable to the select widget type.
placeholderstring <optional>
-- Please choose -- Specifies a placeholder text which is displayed when no choice is selected yet. Only applicable to the select widget type.
Class: Textarea On this pageLuCI.ui. Textarea
The Textarea class implements a multiline text area input field.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Textarea. To import it in external JavaScript, use L.require("ui").then(...) and access the Textarea property of the class instance value.
Constructor
new Textarea(valueopt, optionsopt)
Instantiate a textarea widget.
Parameters:Name Type Attributes Default Description valuestring <optional>
null The initial input value.
optionsLuCI.ui.Textarea.InitOptions <optional>
Object describing the widget specific options to initialize the input.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description readonlyboolean <optional>
false Specifies whether the input widget should be rendered readonly.
placeholderstring <optional>
Specifies the HTML placeholder attribute which is displayed when the corresponding <textarea> element is empty.
monospaceboolean <optional>
false Specifies whether a monospace font should be forced for the textarea contents.
colsnumber <optional>
Specifies the HTML cols attribute to set on the corresponding <textarea> element.
rowsnumber <optional>
Specifies the HTML rows attribute to set on the corresponding <textarea> element.
wrapboolean <optional>
false Specifies whether the HTML wrap attribute should be set.
Class: Textfield On this pageLuCI.ui. Textfield
The Textfield class implements a standard single line text input field.
UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by LuCI.form when instantiating CBI forms.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.Textfield. To import it in external JavaScript, use L.require("ui").then(...) and access the Textfield property of the class instance value.
Constructor
new Textfield(valueopt, optionsopt)
Instantiate a text input widget.
Parameters:Name Type Attributes Default Description valuestring <optional>
null The initial input value.
optionsLuCI.ui.Textfield.InitOptions <optional>
Object describing the widget specific options to initialize the input.
Extends
Methods
getValidationError() → {string}
Returns the current validation error
- Inherited From
Returns:The validation error at this time
- Type:
- string
getValue() → {string|Array.<string>|null}
Read the current value of the input widget.
- Overrides
Returns:The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as DynamicList instances may result in an array of strings or null for unset values.
- Type:
- string |
Array.<string> | null
isChanged() → {boolean}
Check whether the input value was altered by the user.
- Inherited From
Returns:Returns true if the input value has been altered by the user or false if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.
- Type:
- boolean
isValid() → {boolean}
Check whether the current input value is valid.
- Inherited From
Returns:Returns true if the current input value is valid or false if it does not meet the validation constraints.
- Type:
- boolean
registerEvents(targetNode, synevent, events)
Dispatch a custom (synthetic) event in response to received events.
Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.
The primary purpose of this function is to set up a series of custom uniform standard events such as widget-update, validation-success, validation-failure etc. which are triggered by various different widget specific native DOM events.
Parameters:Name Type Description targetNodeNode Specifies the DOM node on which the native event listeners should be registered.
syneventstring The name of the custom event to dispatch to the widget root DOM node.
eventsArray.<string> The native DOM events for which event handlers should be registered.
- Inherited From
render() → {Node}
Render the widget, set up event listeners and return resulting markup.
- Overrides
Returns:Returns a DOM Node or DocumentFragment containing the rendered widget markup.
- Type:
- Node
setChangeEvents(targetNode, …events)
Set up listeners for native DOM events that may change the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as change events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setPlaceholder(value)
Set the current placeholder value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.
- Inherited From
setUpdateEvents(targetNode, …events)
Set up listeners for native DOM events that may update the widget value.
Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as keyup or onclick events. In contrast to change events, such update events will trigger input value validation.
Parameters:Name Type Attributes Description targetNodeNode Specifies the DOM node on which the event listeners should be registered.
eventsstring <repeatable>
The DOM events for which event handlers should be registered.
- Inherited From
setValue(value)
Set the current value of the input widget.
Parameters:Name Type Description valuestring | Array.<string> | null The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as DynamicList instances may accept string array or null values.
- Overrides
triggerValidation() → {boolean}
Force validation of the current input value.
Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.
- Inherited From
Returns:- Type:
- boolean
Type Definitions
InitOptions
In addition to the AbstractElement.InitOptions the following properties are recognized:
PropertiesName Type Attributes Default Description passwordboolean <optional>
false Specifies whether the input should be rendered as concealed password field.
readonlyboolean <optional>
false Specifies whether the input widget should be rendered readonly.
maxlengthnumber <optional>
Specifies the HTML maxlength attribute to set on the corresponding <input> element. Note that this a legacy property that exists for compatibility reasons. It is usually better to maxlength(N) validation expression.
placeholderstring <optional>
Specifies the HTML placeholder attribute which is displayed when the corresponding <input> element is empty.
Class: changes On this pageLuCI.ui. changes
The changes class encapsulates logic for visualizing, applying, confirming and reverting staged UCI changesets.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.changes. To import it in external JavaScript, use L.require("ui").then(...) and access the changes property of the class instance value.
Methods
apply(checkedopt)
Apply the staged configuration changes.
Start applying staged configuration changes and open a modal dialog with a progress indication to prevent interaction with the view during the apply process. The modal dialog will be automatically closed and the current view reloaded once the apply process is complete.
Parameters:Name Type Attributes Default Description checkedboolean <optional>
false Whether to perform a checked (true) configuration apply or an unchecked (false) one.
In case of a checked apply, the configuration changes must be confirmed within a specific time interval, otherwise the device will begin to roll back the changes in order to restore the previous settings.
displayChanges()
Display the current changelog.
Open a modal dialog visualizing the currently staged UCI changes and offer options to revert or apply the shown changes.
renderChangeIndicator(changes)
Update the change count indicator.
This function updates the UCI change count indicator from the given UCI changeset structure.
Parameters:Name Type Description changesObject.<string, Array.<LuCI.uci.ChangeRecord>> The UCI changeset to count.
revert()
Revert the staged configuration changes.
Start reverting staged configuration changes and open a modal dialog with a progress indication to prevent interaction with the view during the revert process. The modal dialog will be automatically closed and the current view reloaded once the revert process is complete.
setIndicator(n)
Set the change count indicator.
This function updates or hides the UCI change count indicator, depending on the passed change count. When the count is greater than 0, the change indicator is displayed or updated, otherwise it is removed.
Parameters:Name Type Description nnumber The number of changes to indicate.
Class: ui On this pageLuCI. ui
Provides high level UI helper functionality. To import the class in views, use 'require ui', to import it in external JavaScript, use L.require("ui").then(...).
Classes
- AbstractElement
- Checkbox
- ComboButton
- Combobox
- Dropdown
- DynamicList
- FileUpload
- Hiddenfield
- RangeSlider
- Select
- Textarea
- Textfield
- changes
- menu
- tabs
Methods
addNotification(titleopt, children, …classesopt) → {Node}
Add a notification banner at the top of the current view.
A notification banner is an alert message usually displayed at the top of the current view, spanning the entire available width. Notification banners will stay in place until dismissed by the user. Multiple banners may be shown at the same time.
Additional CSS class names may be passed to influence the appearance of the banner. Valid values for the classes depend on the underlying theme.
Parameters:Name Type Attributes Description titlestring <optional>
The title of the notification banner. If null, no title element will be rendered.
children* The contents to add to the notification banner. This should be a DOM node or a document fragment in most cases. The value is passed as-is to the dom.content() function - refer to its documentation for applicable values.
classesstring <optional>
<repeatable>
A number of extra CSS class names which are set on the notification banner element.
- See
- LuCI.dom.content
Returns:Returns a DOM Node representing the notification banner element.
- Type:
- Node
addTimeLimitedNotification(titleopt, children, timeoutopt, …classesopt) → {Node}
Add a time-limited notification banner at the top of the current view.
A notification banner is an alert message usually displayed at the top of the current view, spanning the entire available width. Notification banners will stay in place until dismissed by the user, or it has expired. Multiple banners may be shown at the same time.
Additional CSS class names may be passed to influence the appearance of the banner. Valid values for the classes depend on the underlying theme.
Parameters:Name Type Attributes Description titlestring <optional>
The title of the notification banner. If null, no title element will be rendered.
children* The contents to add to the notification banner. This should be a DOM node or a document fragment in most cases. The value is passed as-is to the dom.content() function - refer to its documentation for applicable values.
timeoutnumber <optional>
A millisecond value after which the notification will disappear automatically. If omitted, the notification will remain until it receives the click event.
classesstring <optional>
<repeatable>
A number of extra CSS class names which are set on the notification banner element.
- See
- LuCI.dom.content
Returns:Returns a DOM Node representing the notification banner element.
- Type:
- Node
addValidator(field, type, optionalopt, vfuncopt, …eventsopt) → {function}
Add validation constraints to an input element.
Compile the given type expression and optional validator function into a validation function and bind it to the specified input element events.
Parameters:Name Type Attributes Default Description fieldNode The DOM input element node to bind the validation constraints to.
typestring The datatype specification to describe validation constraints. Refer to the LuCI.validation class documentation for details.
optionalboolean <optional>
false Specifies whether empty values are allowed (true) or not (false). If an input element is not marked optional it must not be empty, otherwise it will be marked as invalid.
vfuncfunction | Array.<function()> <optional>
Specifies a custom validation function or an array of validation functions which are invoked after the other validation constraints are applied. Each function must return true to accept the passed value. When multiple functions are provided as an array, they are executed serially and validation stops at the first function that returns a non-true value. Any non-true return type is converted to a string and treated as validation error message.
eventsstring <optional>
<repeatable>
blur, keyup The list of events to bind. Each received event will trigger a field validation. If omitted, the keyup and blur events are bound by default.
Returns:Returns the compiled validator function which can be used to trigger field validation manually or to bind it to further events.
- Type:
- function
awaitReconnect(…hostsopt)
Wait for device to come back online and reconnect to it.
Poll each given hostname or IP address and navigate to it as soon as one of the addresses becomes reachable.
Parameters:Name Type Attributes Default Description hostsstring <optional>
<repeatable>
[window.location.host] The list of IP addresses and host names to check for reachability. If omitted, the current value of window.location.host is used by default.
createHandlerFn(ctx, fn, …args) → (nullable) {function}
Create a pre-bound event handler function.
Generate and bind a function suitable for use in event handlers. The generated function automatically disables the event source element and adds an active indication to it by adding appropriate CSS classes.
It will also await any promises returned by the wrapped function and re-enable the source element after the promises ran to completion.
Parameters:Name Type Attributes Description ctx* The this context to use for the wrapped function.
fnfunction | string Specifies the function to wrap. In case of a function value, the function is used as-is. If a string is specified instead, it is looked up in ctx to obtain the function to wrap. In both cases the bound function will be invoked with ctx as this context
args* <repeatable>
Any further parameter as passed as-is to the bound event handler function in the same order as passed to createHandlerFn().
Returns:Returns the pre-bound handler function which is suitable to be passed to addEventListener(). Returns null if the given fn argument is a string which could not be found in ctx or if ctx[fn] is not a valid function value.
- Type:
- function
hideIndicator(id) → {boolean}
Remove a header area indicator.
This function removes the given indicator label from the header indicator area. When the given indicator is not found, this function does nothing.
Parameters:Name Type Description idstring The ID of the indicator to remove.
Returns:Returns true when the indicator has been removed or false when the requested indicator was not found.
- Type:
- boolean
hideModal()
Close the open modal overlay dialog.
This function will close an open modal dialog and restore the normal view behaviour. It has no effect if no modal dialog is currently open.
Note that this function is stand-alone, it does not rely on this and will not invoke other class functions so it is suitable to be used as event handler as-is without the need to bind it first.
instantiateView(path) → {Promise.<LuCI.view>}
Load specified view class path and set it up.
Transforms the given view path into a class name, requires it using LuCI.require() and asserts that the resulting class instance is a descendant of LuCI.view.
By instantiating the view class, its corresponding contents are rendered and included into the view area. Any runtime errors are caught and rendered using LuCI.error().
Parameters:Name Type Description pathstring The view path to render.
Returns:Returns a promise resolving to the loaded view instance.
- Type:
- Promise.<LuCI.view>
itemlist(node, items, separatorsopt) → {Node}
Formats a series of label/value pairs into list-like markup.
This function transforms a flat array of alternating label and value elements into a list-like markup, using the values in separators as separators and appends the resulting nodes to the given parent DOM node.
Each label is suffixed with : and wrapped into a <strong> tag, the <strong> element and the value corresponding to the label are subsequently wrapped into a <span class="nowrap"> element.
The resulting <span> element tuples are joined by the given separators to form the final markup which is appended to the given parent DOM node.
Parameters:Name Type Attributes Default Description nodeNode The parent DOM node to append the markup to. Any previous child elements will be removed.
itemsArray.<*> An alternating array of labels and values. The label values will be converted to plain strings, the values are used as-is and may be of any type accepted by LuCI.dom.content().
separators* | Array.<*> <optional>
[E('br')] A single value or an array of separator values to separate each label/value pair with. The function will cycle through the separators when joining the pairs. If omitted, the default separator is a sole HTML <br> element. Separator values are used as-is and may be of any type accepted by LuCI.dom.content().
Returns:Returns the parent DOM node the formatted markup has been added to.
- Type:
- Node
pingDevice(protoopt, ipaddropt) → {Promise.<Event>}
Perform a device connectivity test.
Attempt to fetch a well known resource from the remote device via HTTP in order to test connectivity. This function is mainly useful to wait for the router to come back online after a reboot or reconfiguration.
Parameters:Name Type Attributes Default Description protostring <optional>
http The protocol to use for fetching the resource. May be either http (the default) or https.
ipaddrstring <optional>
window.location.host Override the host address to probe. By default the current host as seen in the address bar is probed.
Returns:Returns a promise resolving to a load event in case the device is reachable or rejecting with an error event in case it is not reachable or rejecting with null when the connectivity check timed out.
- Type:
- Promise.<Event>
showIndicator(id, label, handleropt, styleopt) → {boolean}
Display or update a header area indicator.
An indicator is a small label displayed in the header area of the screen providing few amounts of status information such as item counts or state toggle indicators.
Multiple indicators may be shown at the same time and indicator labels may be made clickable to display extended information or to initiate further actions.
Indicators can either use a default active or a less accented inactive style which is useful for indicators representing state toggles.
Parameters:Name Type Attributes Default Description idstring The ID of the indicator. If an indicator with the given ID already exists, it is updated with the given label and style.
labelstring The text to display in the indicator label.
handlerfunction <optional>
A handler function to invoke when the indicator label is clicked/touched by the user. If omitted, the indicator is not clickable/touchable.
Note that this parameter only applies to new indicators, when updating existing labels it is ignored.
style"active" | "inactive" <optional>
active The indicator style to use. May be either active or inactive.
Returns:Returns true when the indicator has been updated or false when no changes were made.
- Type:
- boolean
showModal(titleopt, children, …classesopt) → {Node}
Display a modal overlay dialog with the specified contents.
The modal overlay dialog covers the current view preventing interaction with the underlying view contents. Only one modal dialog instance can be opened. Invoking showModal() while a modal dialog is already open will replace the open dialog with a new one having the specified contents.
Additional CSS class names may be passed to influence the appearance of the dialog. Valid values for the classes depend on the underlying theme.
Parameters:Name Type Attributes Description titlestring <optional>
The title of the dialog. If null, no title element will be rendered.
children* The contents to add to the modal dialog. This should be a DOM node or a document fragment in most cases. The value is passed as-is to the dom.content() function - refer to its documentation for applicable values.
classesstring <optional>
<repeatable>
A number of extra CSS class names which are set on the modal dialog element.
- See
- LuCI.dom.content
Returns:Returns a DOM Node representing the modal dialog element.
- Type:
- Node
uploadFile(path, progressStatusNodeopt) → {Promise.<LuCI.ui.FileUploadReply>}
Display a modal file upload prompt.
This function opens a modal dialog prompting the user to select and upload a file to a predefined remote destination path.
Parameters:Name Type Attributes Description pathstring The remote file path to upload the local file to.
progressStatusNodeNode <optional>
An optional DOM text node whose content text is set to the progress percentage value during file upload.
Returns:Returns a promise resolving to a file upload status object on success or rejecting with an error in case the upload failed or has been cancelled by the user.
- Type:
- Promise.<LuCI.ui.FileUploadReply>
Type Definitions
FileUploadReply
Type:- Object
PropertiesName Type Description namestring Name of the uploaded file without directory components
sizenumber Size of the uploaded file in bytes
checksumstring The MD5 checksum of the received file data
sha256sumstring The SHA256 checksum of the received file data
Class: menu On this pageLuCI.ui. menu
Handles menus.
Methods
flushCache()
Flush the internal menu cache to force loading a new structure on the next page load.
getChildren(nodeopt) → {Array.<LuCI.ui.menu.MenuNode>}
Parameters:Name Type Attributes Description nodeLuCI.ui.menu.MenuNode <optional>
The menu node to retrieve the children for. Defaults to the menu's internal root node if omitted.
Returns:Returns an array of child menu nodes.
- Type:
- Array.<LuCI.ui.menu.MenuNode>
load() → {Promise.<LuCI.ui.menu.MenuNode>}
Load and cache current menu tree.
Returns:Returns a promise resolving to the root element of the menu tree.
- Type:
- Promise.<LuCI.ui.menu.MenuNode>
Type Definitions
MenuNode
Type:- Object
PropertiesName Type Attributes Description namestring The internal name of the node, as used in the URL.
ordernumber The sort index of the menu node
titlestring <optional>
The title of the menu node, null if the node should be hidden.
satisfiedboolean Boolean indicating whether the menu entries dependencies are satisfied.
readonlyboolean <optional>
Boolean indicating whether the menu entries underlying ACLs are readonly.
childrenArray.<LuCI.ui.menu.MenuNode> <optional>
Array of child menu nodes.
Class: tabs On this pageLuCI.ui. tabs
The tabs class handles tab menu groups used throughout the view area. It takes care of setting up tab groups, tracking their state and handling related events.
This class is automatically instantiated as part of LuCI.ui. To use it in views, use 'require ui' and refer to ui.tabs. To import it in external JavaScript, use L.require("ui").then(...) and access the tabs property of the class instance value.
Methods
initTabGroup(panes)
Initializes a new tab group from the given tab pane collection.
This function cycles through the given tab pane DOM nodes, extracts their tab IDs, titles and active states, renders a corresponding tab menu and prepends it to the tab panes common parent DOM node.
The tab menu labels will be set to the value of the data-tab-title attribute of each corresponding pane. The last pane with the data-tab-active attribute set to true will be selected by default.
If no pane is marked as active, the first one will be preselected.
Parameters:Name Type Description panesArray.<Node> | NodeList A collection of tab panes to build a tab group menu for. May be a plain array of DOM nodes or a NodeList collection, such as the result of a querySelectorAll() call or the .childNodes property of a DOM node.
isEmptyPane(pane) → {boolean}
Checks whether the given tab pane node is empty.
Parameters:Name Type Description paneNode The tab pane to check.
Returns:Returns true if the pane is empty, else false.
- Type:
- boolean
Class: Validator On this pageLuCI.validation. Validator
new Validator(field, type, optional, function, validatorFactory) → {Validator}
Parameters:Name Type Description fieldstring the UI field to validate.
typestring type of validator.
optionalboolean set the validation result as optional.
functionvfunc validation function.
validatorFactoryValidatorFactory a ValidatorFactory instance.
- Source
Returns:a Validator instance.
- Type:
- Validator
Methods
apply(name, value, args) → {*}
Apply a validation function by name or directly via function reference. If a name is provided it resolves it via the factory's registered types.
Parameters:Name Type Description namestring | function Validator name or function.
value* Value to validate (optional; defaults to field value).
argsArray Arguments passed to the validator function.
- Source
Returns:Validator result.
- Type:
- *
assert(condition, message) → {boolean}
Assert a condition and update field error state.
Parameters:Name Type Description conditionboolean Condition that must be true.
messagestring Error message when assertion fails.
- Source
Returns:True when assertion is true, false otherwise.
- Type:
- boolean
validate() → {boolean}
Validate the associated field value using the compiled validator stack and any additional validators provided at construction time. Emits 'validation-failure' or 'validation-success' CustomEvents on the field.
- Source
Returns:True if validation succeeds, false otherwise.
- Type:
- boolean
Class: ValidatorFactory On this pageLuCI.validation. ValidatorFactory
Factory to create Validator instances and compile validation expressions.
- Source
Namespaces
Methods
compile(code) → {Array}
Compile a validator expression string into an internal stack representation.
Parameters:Name Type Description codestring Validator expression string (e.g. or(ipaddr,port)).
- Source
Returns:Compiled token stack used by validators.
- Type:
- Array
create(field, type, optional, vfunc) → {Validator}
Compile a validator expression string into an internal stack representation.
Parameters:Name Type Description fieldstring field name
typestring validator type
optionalboolean whether the field is optional
vfuncstring a validator function
- Source
Returns:Compiled token stack used by validators.
- Type:
- Validator
parseDecimal(x) → {number}
Parse a decimal number string. Returns NaN when not a valid number.
Parameters:Name Type Description xstring
- Source
Returns:Decimal number or NaN
- Type:
- number
parseIPv4(x) → {Array.<number>|null}
Parse IPv4 address into an array of 4 octets or return null on failure.
Parameters:Name Type Description xstring IPv4 address string
- Source
Returns:Array of 4 octets or null.
- Type:
- Array.<number> |
null
parseIPv6(x) → {Array.<number>|null}
Parse IPv6 address into an array of 8 16-bit words or return null on failure. Supports IPv4-embedded IPv6 (::ffff:a.b.c.d) and zero-compression.
Parameters:Name Type Description xstring IPv6 address string
- Source
Returns:Array of 8 16-bit words or null.
- Type:
- Array.<number> |
null
parseInteger(x) → {number}
Parse an integer string. Returns NaN when not a valid integer.
Parameters:Name Type Description xstring
- Source
Returns:Integer or NaN
- Type:
- number
Namespace: types On this pageLuCI.validation.ValidatorFactory. types
Collection of type handlers. Each function consumes this.value and returns this.assert to report errors.
All functions return the result of assert().
- Source
Methods
and() → {boolean}
Logical AND && to build more complex expressions. Enforces all types on the input string.
See also or
Parameters:Name Type Description ...argsstring
- Source
Returns:- Type:
- boolean
Examplecidr(negativeopt) → {boolean}
Assert a IPv4/6 CIDR.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-... to mark negation of the range.
- Source
Returns:- Type:
- boolean
cidr4(negativeopt) → {boolean}
Assert a IPv4 CIDR.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-.... E.g. 192.0.2.1/-24 to mark negation of the range.
- Source
Returns:- Type:
- boolean
cidr6(negativeopt) → {boolean}
Assert a IPv6 CIDR.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-.... E.g. 2001:db8:dead:beef::/-64 to mark negation of the range.
- Source
Returns:- Type:
- boolean
dateyyyymmdd() → {boolean}
Assert a string of the form YYYY-MM-DD.
- Source
Returns:- Type:
- boolean
device() → {boolean}
Assert a device string. This is a hold-over from Lua to maintain compatibility and is a stub function.
- Source
Returns:Always returns true.
- Type:
- boolean
directory() → {boolean}
Assert a directory string. This is a hold-over from Lua to maintain compatibility and is a stub function.
- Source
Returns:Always returns true.
- Type:
- boolean
file() → {boolean}
Assert a file string. This is a hold-over from Lua to maintain compatibility and is a stub function.
- Source
Returns:Always returns true.
- Type:
- boolean
float() → {boolean}
Assert a signed float value (+/-).
- Source
Returns:- Type:
- boolean
hexstring() → {boolean}
Assert a hexadecimal string.
- Source
Returns:- Type:
- boolean
ExampleFFFE // valid
FFF // invalid
host(ipv4onlyopt) → {boolean}
Assert a valid hostname or IP address.
Parameters:Name Type Attributes Description ipv4onlyboolean <optional>
enforce IPv4 IPs only.
- Source
Returns:- Type:
- boolean
hostname(strictopt) → {boolean}
Validate hostname according to common rules.
Parameters:Name Type Attributes Description strictboolean <optional>
reject leading underscores.
- Source
Returns:- Type:
- boolean
hostport(ipv4onlyopt) → {boolean}
Assert a valid host:port.
Parameters:Name Type Attributes Description ipv4onlyboolean <optional>
restrict to IPv4 IPs only.
- Source
Returns:- Type:
- boolean
integer() → {boolean}
Assert a signed integer value (+/-).
- Source
Returns:- Type:
- boolean
ip4addr(nomaskopt) → {boolean}
Assert an IPv4 address.
Parameters:Name Type Attributes Description nomaskstring <optional>
reject a /x netmask.
- Source
Returns:- Type:
- boolean
ip4addrport(ipv4onlyopt) → {boolean}
Assert a valid IPv4 address:port. E.g. 192.0.2.10:80
Parameters:Name Type Attributes Description ipv4onlyboolean <optional>
restrict to IPv4 IPs only.
- Source
Returns:- Type:
- boolean
ip4prefix() → {boolean}
Assert an IPv4 prefix.
- Source
Returns:- Type:
- boolean
ip6addr(nomaskopt) → {boolean}
Assert an IPv6 address.
Parameters:Name Type Attributes Description nomaskstring <optional>
reject a /x netmask.
- Source
Returns:- Type:
- boolean
ip6hostid() → {boolean}
Assert a IPv6 host ID.
- Source
Returns:- Type:
- boolean
ip6ll(nomaskopt) → {boolean}
Assert an IPv6 Link Local address.
Parameters:Name Type Attributes Description nomaskstring <optional>
reject a /x netmask.
- Source
Returns:- Type:
- boolean
ip6prefix() → {boolean}
Assert an IPv6 prefix.
- Source
Returns:- Type:
- boolean
ip6ula(nomaskopt) → {boolean}
Assert an IPv6 UL address.
Parameters:Name Type Attributes Description nomaskstring <optional>
reject a /x netmask.
- Source
Returns:- Type:
- boolean
ipaddr(nomaskopt) → {boolean}
Assert an IPv4/6 address.
Parameters:Name Type Attributes Description nomaskstring <optional>
reject a /x netmask.
- Source
Returns:- Type:
- boolean
ipaddrport(bracketopt) → {boolean}
Assert a valid IPv4/6 address:port. E.g. 192.0.2.10:80 or [2001:db8:f00d:cafe::1]:8080
Parameters:Name Type Attributes Description bracketboolean <optional>
mandate bracketed [IPv6] URI form IPs.
- Source
Returns:- Type:
- boolean
ipmask(negativeopt) → {boolean}
Assert an IPv4/6 network in address/netmask (CIDR or mask) notation.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-... to mark negation of the range.
- Source
Returns:- Type:
- boolean
ipmask4(negativeopt) → {boolean}
Assert an IPv4 network in address/netmask (CIDR or mask) notation.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-... to mark negation of the range.
- Source
Returns:- Type:
- boolean
ipmask6(negativeopt) → {boolean}
Assert an IPv6 network in address/netmask (CIDR or mask) notation.
Parameters:Name Type Attributes Description negativeboolean <optional>
allow netmask forms with /-... to mark negation of the range.
- Source
Returns:- Type:
- boolean
ipnet4() → {boolean}
Assert an IPv4 network in address/netmask notation. E.g. 192.0.2.1/255.255.255.0
- Source
Returns:- Type:
- boolean
ipnet6() → {boolean}
Assert an IPv6 network in address/netmask notation. E.g. 2001:db8:dead:beef::0001/ffff:ffff:ffff:ffff::
- Source
Returns:- Type:
- boolean
iprange() → {boolean}
Assert a valid IPv4/6 address range.
- Source
Returns:- Type:
- boolean
iprange4() → {boolean}
Assert a valid IPv4 address range. E.g. 192.0.2.1-192.0.2.254.
- Source
Returns:- Type:
- boolean
iprange6() → {boolean}
Assert a valid IPv6 address range. E.g. 2001:db8:0f00:0000::-2001:db8:0f00:0000:ffff:ffff:ffff:ffff.
- Source
Returns:- Type:
- boolean
length(len) → {boolean}
Assert a string of bytelen length len characters.
Parameters:Name Type Description lenstring set the length.
- Source
Returns:- Type:
- boolean
list(subvalidator, subargs) → {boolean}
Assert a list of a type.
Parameters:Name Type Description subvalidatorstring subargsstring arguments to pass to the subvalidator
- Source
Returns:- Type:
- boolean
Examplelist(string)
macaddr(multicastopt) → {boolean}
Assert a valid (multicast) MAC address.
Parameters:Name Type Attributes Description multicastboolean <optional>
enforce a multicast MAC address.
- Source
Returns:- Type:
- boolean
max(max) → {boolean}
Assert a decimal value lesser or equal to max.
Parameters:Name Type Description maxstring set end of range.
- Source
Returns:- Type:
- boolean
maxlength(max) → {boolean}
Assert a value of bytelen with at most max characters.
Parameters:Name Type Description maxstring set the max length.
- Source
Returns:- Type:
- boolean
min(min) → {boolean}
Assert a decimal value greater or equal to min.
Parameters:Name Type Description minstring set start of range.
- Source
Returns:- Type:
- boolean
minlength(min) → {boolean}
Assert a value of bytelen with at least min characters.
Parameters:Name Type Description minstring set the min length.
- Source
Returns:- Type:
- boolean
neg() → {boolean}
Assert any type, optionally preceded by !.
Example:list(neg(macaddr)) mandates a list of MAC values, which may also be prefixed with a single !; the MAC strings are validated after ! are removed from all entries.
01:02:03:04:05:06
diff --git a/LuCI.validation.html b/jsapi/LuCI.validation.html
similarity index 99%
rename from LuCI.validation.html
rename to jsapi/LuCI.validation.html
index 7fe90188a2..99591025c9 100644
--- a/LuCI.validation.html
+++ b/jsapi/LuCI.validation.html
@@ -1,3 +1,3 @@
-Namespace: validation On this pageLuCI. validation
- Source
Classes
Methods
(static) arrayle(a, b) → {boolean}
Compare two arrays element-wise: return true if a < b in lexicographic element comparison.
Parameters:Name Type Description aArray.<number> First array.
bArray.<number> Second array.
- Source
Returns:True if arrays compare as a < b, false otherwise.
- Type:
- boolean
(static) bytelen(x) → {number}
Return byte length of a string using Blob (UTF-8 byte count).
Parameters:Name Type Description xstring Input string.
- Source
Returns:Byte length of the string.
- Type:
- number
Class: view On this pageLuCI. view
The view class forms the basis of views and provides a standard set of methods to inherit from.
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.
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:Name Type Description evEvent The DOM event that triggered the function.
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:Name Type Description evEvent The DOM event that triggered the function.
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:Name Type Description evEvent The DOM event that triggered the function.
modenumber Whether to apply the changes checked.
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.
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:Name Type Description load_results* | null This function will receive the return value of the view.load() function as first argument.
Returns:Should return a DOM Node value or a Promise resolving to a Node value.
- Type:
- Node |
Promise.<Node>
Class: xhr On this pageLuCI. 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.
Methods
abort()
Ignored for backwards compatibility.
This function does nothing.
- Deprecated
- Yes
busy() → {boolean}
Checks the running state of the request.
- Deprecated
- Yes
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
get(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.get().
Parameters:Name Type Attributes Description 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
Returns:- Type:
- Promise.<null>
post(url, dataopt, callbackopt, timeoutopt) → {Promise.<null>}
This function is a legacy wrapper around LuCI.post().
Parameters:Name Type Attributes Description 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
Returns:- Type:
- Promise.<null>
send_form()
Existing for backwards compatibility.
This function simply throws an InternalError when invoked.
- Deprecated
- Yes
Throws:Throws an InternalError with the message Not implemented when invoked.
- Type
- InternalError
Source: cbi.js On this pagecbi.js
/*
LuCI - Lua Configuration Interface
diff --git a/data/search.json b/jsapi/data/search.json
similarity index 100%
rename from data/search.json
rename to jsapi/data/search.json
diff --git a/external-String.html b/jsapi/external-String.html
similarity index 99%
rename from external-String.html
rename to jsapi/external-String.html
index 3576a34981..06756cd851 100644
--- a/external-String.html
+++ b/jsapi/external-String.html
@@ -1,3 +1,3 @@
-External: String On this pageLuCI.cbi~ String
Methods
format(…args) → {string}
Format a string using positional arguments.
Parameters:Name Type Attributes Description argsstring <repeatable>
Returns:- Type:
- string
nobr(…args) → {string}
Format a string using positional arguments.
Parameters:Name Type Attributes Description argsstring <repeatable>
Returns:- Type:
- string
(static) format(…args) → {string}
Format a string using positional arguments.
Parameters:Name Type Attributes Description argsstring <repeatable>
Returns:- Type:
- string
(static) nobr(…args) → {string}
Format a string using positional arguments.
Parameters:Name Type Attributes Description argsstring <repeatable>
Returns:- Type:
- string
Source: firewall.js On this pagefirewall.js
'use strict';
'require uci';
diff --git a/fonts/Inconsolata-Regular.ttf b/jsapi/fonts/Inconsolata-Regular.ttf
similarity index 100%
rename from fonts/Inconsolata-Regular.ttf
rename to jsapi/fonts/Inconsolata-Regular.ttf
diff --git a/fonts/OpenSans-Regular.ttf b/jsapi/fonts/OpenSans-Regular.ttf
similarity index 100%
rename from fonts/OpenSans-Regular.ttf
rename to jsapi/fonts/OpenSans-Regular.ttf
diff --git a/fonts/WorkSans-Bold.ttf b/jsapi/fonts/WorkSans-Bold.ttf
similarity index 100%
rename from fonts/WorkSans-Bold.ttf
rename to jsapi/fonts/WorkSans-Bold.ttf
diff --git a/form.js.html b/jsapi/form.js.html
similarity index 99%
rename from form.js.html
rename to jsapi/form.js.html
index 99be387741..f18bb63991 100644
--- a/form.js.html
+++ b/jsapi/form.js.html
@@ -1,4 +1,4 @@
-Source: form.js On this pageform.js
'use strict';
'require ui';
diff --git a/fs.js.html b/jsapi/fs.js.html
similarity index 99%
rename from fs.js.html
rename to jsapi/fs.js.html
index 49b695673e..92b67533ef 100644
--- a/fs.js.html
+++ b/jsapi/fs.js.html
@@ -1,4 +1,4 @@
-Source: fs.js On this pagefs.js
'use strict';
'require rpc';
diff --git a/global.html b/jsapi/global.html
similarity index 99%
rename from global.html
rename to jsapi/global.html
index 7033f0bfda..764233d482 100644
--- a/global.html
+++ b/jsapi/global.html
@@ -1,3 +1,3 @@
-Global On this pageMethods
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:Name Type Description 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:Name Type Description 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:Name Type Description 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:Name Type Attributes Default Description 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:Name Type Attributes Description forNamestring <nullable>
- Source
Returns:- Type:
- string
getDevices(network) → {Array.<string>}
Get bridge devices or Layer 3 devices of a network object.
Parameters:Name Type Description 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:Name Type Description resobject
Throws:ErrorReturns:- Type:
- string
handleRpcReply(expect, rc) → {number}
Handle an RPC reply.
Parameters:Name Type Description expectobject rcnumber
Throws:ErrorReturns:- 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:Name Type Description 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:Name Type Description x* y*
Returns:- Type:
- boolean
isEmpty(object, ignore) → {boolean}
Determine whether an object is empty.
Parameters:Name Type Description objectobject object to enumerate.
ignorestring property to ignore.
Returns:- Type:
- boolean
isEqual(x, y) → {boolean}
Determines equality of two provided parameters. Can be arrays or objects.
Parameters:Name Type Description x* y*
Returns:- Type:
- boolean
lookupZone(namenullable) → (nullable) {Zone}
Look up a firewall zone.
Parameters:Name Type Attributes Description 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:Name Type Description 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:Name Type Attributes Description sstring <nullable>
valuesArray.<string>
- Source
Returns:- Type:
- string
parsePolicy(snullable, defaultValueopt) → (nullable) {string}
Parse a policy value, or defaultValue if not found.
Parameters:Name Type Attributes Default Description sstring <nullable>
defaultValueArray.<string> <optional>
['DROP', 'REJECT', 'ACCEPT']
- Source
Returns:- Type:
- string
scrubMenu(node) → {Node}
Erase the menu node
Parameters:Name Type Description nodeNode
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:Name Type Description 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:Name Type Description 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:Name Type Description section_idstring valuestring
- Source
Returns:- Type:
- boolean
LuCI - Reference Documentation On this pageLuCI Documentation
Start with the LuCI Client side JavaScript APIs
Historical
The older Lua API docs are available for historical reference.
Source: luci.js On this pageluci.js
/**
*
diff --git a/network.js.html b/jsapi/network.js.html
similarity index 99%
rename from network.js.html
rename to jsapi/network.js.html
index d641f77341..c14bb9d7b9 100644
--- a/network.js.html
+++ b/jsapi/network.js.html
@@ -1,4 +1,4 @@
-Source: network.js On this pagenetwork.js
'use strict';
'require uci';
diff --git a/protocol_static.js.html b/jsapi/protocol_static.js.html
similarity index 99%
rename from protocol_static.js.html
rename to jsapi/protocol_static.js.html
index 51d823d590..511e193570 100644
--- a/protocol_static.js.html
+++ b/jsapi/protocol_static.js.html
@@ -1,4 +1,4 @@
-Source: protocol/static.js On this pageprotocol_static.js
'use strict';
'require form';
diff --git a/rpc.js.html b/jsapi/rpc.js.html
similarity index 99%
rename from rpc.js.html
rename to jsapi/rpc.js.html
index 8d3df4f707..f750caa9d0 100644
--- a/rpc.js.html
+++ b/jsapi/rpc.js.html
@@ -1,4 +1,4 @@
-Source: rpc.js On this pagerpc.js
'use strict';
'require baseclass';
diff --git a/scripts/core.js b/jsapi/scripts/core.js
similarity index 100%
rename from scripts/core.js
rename to jsapi/scripts/core.js
diff --git a/scripts/core.min.js b/jsapi/scripts/core.min.js
similarity index 100%
rename from scripts/core.min.js
rename to jsapi/scripts/core.min.js
diff --git a/scripts/resize.js b/jsapi/scripts/resize.js
similarity index 100%
rename from scripts/resize.js
rename to jsapi/scripts/resize.js
diff --git a/scripts/search.js b/jsapi/scripts/search.js
similarity index 100%
rename from scripts/search.js
rename to jsapi/scripts/search.js
diff --git a/scripts/search.min.js b/jsapi/scripts/search.min.js
similarity index 100%
rename from scripts/search.min.js
rename to jsapi/scripts/search.min.js
diff --git a/scripts/third-party/Apache-License-2.0.txt b/jsapi/scripts/third-party/Apache-License-2.0.txt
similarity index 100%
rename from scripts/third-party/Apache-License-2.0.txt
rename to jsapi/scripts/third-party/Apache-License-2.0.txt
diff --git a/scripts/third-party/fuse.js b/jsapi/scripts/third-party/fuse.js
similarity index 100%
rename from scripts/third-party/fuse.js
rename to jsapi/scripts/third-party/fuse.js
diff --git a/scripts/third-party/hljs-line-num-original.js b/jsapi/scripts/third-party/hljs-line-num-original.js
similarity index 100%
rename from scripts/third-party/hljs-line-num-original.js
rename to jsapi/scripts/third-party/hljs-line-num-original.js
diff --git a/scripts/third-party/hljs-line-num.js b/jsapi/scripts/third-party/hljs-line-num.js
similarity index 100%
rename from scripts/third-party/hljs-line-num.js
rename to jsapi/scripts/third-party/hljs-line-num.js
diff --git a/scripts/third-party/hljs-original.js b/jsapi/scripts/third-party/hljs-original.js
similarity index 100%
rename from scripts/third-party/hljs-original.js
rename to jsapi/scripts/third-party/hljs-original.js
diff --git a/scripts/third-party/hljs.js b/jsapi/scripts/third-party/hljs.js
similarity index 100%
rename from scripts/third-party/hljs.js
rename to jsapi/scripts/third-party/hljs.js
diff --git a/scripts/third-party/popper.js b/jsapi/scripts/third-party/popper.js
similarity index 100%
rename from scripts/third-party/popper.js
rename to jsapi/scripts/third-party/popper.js
diff --git a/scripts/third-party/tippy.js b/jsapi/scripts/third-party/tippy.js
similarity index 100%
rename from scripts/third-party/tippy.js
rename to jsapi/scripts/third-party/tippy.js
diff --git a/scripts/third-party/tocbot.js b/jsapi/scripts/third-party/tocbot.js
similarity index 100%
rename from scripts/third-party/tocbot.js
rename to jsapi/scripts/third-party/tocbot.js
diff --git a/scripts/third-party/tocbot.min.js b/jsapi/scripts/third-party/tocbot.min.js
similarity index 100%
rename from scripts/third-party/tocbot.min.js
rename to jsapi/scripts/third-party/tocbot.min.js
diff --git a/styles/clean-jsdoc-theme-base.css b/jsapi/styles/clean-jsdoc-theme-base.css
similarity index 100%
rename from styles/clean-jsdoc-theme-base.css
rename to jsapi/styles/clean-jsdoc-theme-base.css
diff --git a/styles/clean-jsdoc-theme-dark.css b/jsapi/styles/clean-jsdoc-theme-dark.css
similarity index 100%
rename from styles/clean-jsdoc-theme-dark.css
rename to jsapi/styles/clean-jsdoc-theme-dark.css
diff --git a/styles/clean-jsdoc-theme-light.css b/jsapi/styles/clean-jsdoc-theme-light.css
similarity index 100%
rename from styles/clean-jsdoc-theme-light.css
rename to jsapi/styles/clean-jsdoc-theme-light.css
diff --git a/styles/clean-jsdoc-theme-scrollbar.css b/jsapi/styles/clean-jsdoc-theme-scrollbar.css
similarity index 100%
rename from styles/clean-jsdoc-theme-scrollbar.css
rename to jsapi/styles/clean-jsdoc-theme-scrollbar.css
diff --git a/styles/clean-jsdoc-theme-without-scrollbar.min.css b/jsapi/styles/clean-jsdoc-theme-without-scrollbar.min.css
similarity index 100%
rename from styles/clean-jsdoc-theme-without-scrollbar.min.css
rename to jsapi/styles/clean-jsdoc-theme-without-scrollbar.min.css
diff --git a/styles/clean-jsdoc-theme.min.css b/jsapi/styles/clean-jsdoc-theme.min.css
similarity index 100%
rename from styles/clean-jsdoc-theme.min.css
rename to jsapi/styles/clean-jsdoc-theme.min.css
diff --git a/tools_prng.js.html b/jsapi/tools_prng.js.html
similarity index 99%
rename from tools_prng.js.html
rename to jsapi/tools_prng.js.html
index d6640f5083..2884610015 100644
--- a/tools_prng.js.html
+++ b/jsapi/tools_prng.js.html
@@ -1,4 +1,4 @@
-Source: tools/prng.js On this pagetools_prng.js
'use strict';
diff --git a/tools_views.js.html b/jsapi/tools_views.js.html
similarity index 99%
rename from tools_views.js.html
rename to jsapi/tools_views.js.html
index 019fe37ecc..4b0b3eb078 100644
--- a/tools_views.js.html
+++ b/jsapi/tools_views.js.html
@@ -1,4 +1,4 @@
-Source: tools/views.js On this pagetools_views.js
'use strict';
'require poll';
diff --git a/tools_widgets.js.html b/jsapi/tools_widgets.js.html
similarity index 99%
rename from tools_widgets.js.html
rename to jsapi/tools_widgets.js.html
index 2701c83a4a..e93e0fb53a 100644
--- a/tools_widgets.js.html
+++ b/jsapi/tools_widgets.js.html
@@ -1,4 +1,4 @@
-Source: tools/widgets.js On this pagetools_widgets.js
'use strict';
'require ui';
diff --git a/tutorial-JsonRpcHowTo.html b/jsapi/tutorial-JsonRpcHowTo.html
similarity index 99%
rename from tutorial-JsonRpcHowTo.html
rename to jsapi/tutorial-JsonRpcHowTo.html
index 5ba3db2340..9186fd4062 100644
--- a/tutorial-JsonRpcHowTo.html
+++ b/jsapi/tutorial-JsonRpcHowTo.html
@@ -1,4 +1,4 @@
-Tutorial: Using JSON RPC daemon On this pageUsing JSON RPC daemon
Using the JSON-RPC API
LuCI provides some of its libraries to external applications through a JSON-RPC API. This Howto shows how to use it and provides information about available functions.
See also
Basics
The API is installed by default.
LuCI comes with an efficient JSON De-/Encoder together with a JSON-RPC-Server which implements the JSON-RPC 1.0 and 2.0 (partly) specifications. The LuCI JSON-RPC server offers several independent APIs. Therefore you have to use different URLs for every exported library. Assuming your LuCI-Installation can be reached through /cgi-bin/luci, any exported library can be reached via /cgi-bin/luci/rpc/LIBRARY.
Authentication
Most exported libraries will require a valid authentication to be called with. If you get an HTTP 403 Forbidden status code you are probably missing a valid authentication token. To get such a token you have to call the login method of the RPC-Library auth. Following our example from above this login function would be provided at /cgi-bin/luci/rpc/auth. The function accepts 2 parameters: username and password (of a valid user account on the host system) and returns an authentication token.
Example:
curl http://<hostname>/cgi-bin/luci/rpc/auth --data '
{
diff --git a/tutorial-Modules.html b/jsapi/tutorial-Modules.html
similarity index 99%
rename from tutorial-Modules.html
rename to jsapi/tutorial-Modules.html
index d02fdb98e5..52a1db2c5f 100644
--- a/tutorial-Modules.html
+++ b/jsapi/tutorial-Modules.html
@@ -1,4 +1,4 @@
-Tutorial: Modules On this pageModules
Authoring LuCI Modules
Categories
The LuCI modules are divided into several category directories, namely:
- applications - Single applications or plugins for other modules
- i18n - Translation files
- libs - libraries of Luci
- modules - main modules of Luci itself
- protocols - network related plugins
- themes - Frontend themes
Each module goes into a subdirectory of its respective category-directories.
Module directory
The contents of a module directory are as follows:
Makefile
This is the module's makefile. If the module just contains JS sourcecode or resources then the following Makefile should suffice.
include $(TOPDIR)/rules.mk
diff --git a/tutorial-ThemesHowTo.html b/jsapi/tutorial-ThemesHowTo.html
similarity index 99%
rename from tutorial-ThemesHowTo.html
rename to jsapi/tutorial-ThemesHowTo.html
index c081091e4a..d7568ee23a 100644
--- a/tutorial-ThemesHowTo.html
+++ b/jsapi/tutorial-ThemesHowTo.html
@@ -1,4 +1,4 @@
-Tutorial: Making Themes On this pageMaking Themes
Creating Themes
Note: You have already read the Module Reference.
We assume you want to call your new theme mytheme. Replace mytheme with your module name every time this is mentioned in this Howto.
Creating the structure
At first create a new theme directory themes/luci-theme-mytheme.
Create a Makefile inside your theme directory with the following content:
include $(TOPDIR)/rules.mk
diff --git a/tutorial-i18n.html b/jsapi/tutorial-i18n.html
similarity index 99%
rename from tutorial-i18n.html
rename to jsapi/tutorial-i18n.html
index ccba1db9b4..44afd68ae5 100644
--- a/tutorial-i18n.html
+++ b/jsapi/tutorial-i18n.html
@@ -1,4 +1,4 @@
-Tutorial: Internationalisation - i18n On this pageInternationalisation - i18n
Internationalisation (i18n)
Use translation function
Translations in JavaScript
Wrap translatable strings with _() e.g. _('string to translate') and the i18n-scan.pl and friends will correctly identify these strings for translation.
If you have multi line strings you can split them with concatenation:
var mystr = _('this string will translate ' +
'correctly even though it is ' +
diff --git a/uci.js.html b/jsapi/uci.js.html
similarity index 99%
rename from uci.js.html
rename to jsapi/uci.js.html
index e4a15ddf29..433e670286 100644
--- a/uci.js.html
+++ b/jsapi/uci.js.html
@@ -1,4 +1,4 @@
-Source: uci.js On this pageuci.js
'use strict';
'require rpc';
diff --git a/ui.js.html b/jsapi/ui.js.html
similarity index 99%
rename from ui.js.html
rename to jsapi/ui.js.html
index 3ddaac85de..96a100a810 100644
--- a/ui.js.html
+++ b/jsapi/ui.js.html
@@ -1,4 +1,4 @@
-Source: ui.js On this pageui.js
'use strict';
'require validation';
diff --git a/validation.js.html b/jsapi/validation.js.html
similarity index 99%
rename from validation.js.html
rename to jsapi/validation.js.html
index 2ba975b9f1..8ea56372aa 100644
--- a/validation.js.html
+++ b/jsapi/validation.js.html
@@ -1,4 +1,4 @@
-Source: validation.js On this pagevalidation.js
'use strict';
'require baseclass';