Class: Map

LuCI.form. Map

The Map class represents one complete form. A form usually maps one UCI configuraton file and is divided into multiple sections containing multiple fields each.

It serves as main entry point into the LuCI.form for typical view code.

new LuCI.form.Map(config, title, description)

form.js, line 338
Name Type Description
config string

The UCI configuration to map. It is automatically loaded along when the resulting map instance.
title string optional

The title caption of the form. A form title is usually rendered as 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 text paragraph below the form title and before the actual form conents. If omitted, the corresponding paragraph element will not be rendered.

Extends

Members

readonlyboolean

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.

Methods

inherited append(element)

form.js, line 210

Add another form element as children to this element.

Name Type Description
element AbstractElement

The form element to add.

chain(config)

form.js, line 479

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 already is in the list of required files, it will be ignored.

findElement(selector_or_attrname, attrvalue){Node|null}

form.js, line 461

Find 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 attribute name, the second one as 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 Description
selector_or_attrname string

If invoked with only one parameter, this argument is a querySelector() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.
attrvalue string optional

In case the function is invoked with two parameters, this argument specifies the attribute value to match.
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:
Type Description
Node | null Returns the first found DOM node or null if no element matched.

findElements(selector_or_attrname, attrvalue){NodeList}

form.js, line 418

Find 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 attribute name, the second one as 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 Description
selector_or_attrname string

If invoked with only one parameter, this argument is a querySelectorAll() compatible selector expression. If invoked with two parameters, this argument is the attribute name to filter for.
attrvalue string optional

In case the function is invoked with two parameters, this argument specifies the attribute value to match.
Throws:

Throws an InternalError if more than two function parameters are passed.

Type
InternalError
Returns:
Type Description
NodeList Returns a (possibly empty) DOM NodeList containing the found DOM nodes.

load(){Promise.<void>}

form.js, line 533

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:
Type Description
Promise.<void> 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 rejected with an error.

lookupOption(name_or_id, section_id, config){Array.<LuCI.form.AbstractValue, string>|null}

form.js, line 699

Find a form option element instance.

Name Type Description
name_or_id string

The name or the full ID of the option element to look up.
section_id string optional

The ID of the UCI section containing the option to look up. May be omitted if a full ID is passed as first argument.
config string optional

The name of the UCI configuration the option instance is belonging to. Defaults to the main UCI configuration of the map if omitted.
Returns:
Type Description
Array.<LuCI.form.AbstractValue, string> | null Returns a two-element array containing the form option instance as first item and the corresponding UCI section ID as second item. Returns null if the option could not be found.

parse(){Promise.<void>}

form.js, line 560

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 unsatisified dependencies are skipped.

Returns:
Type Description
Promise.<void> Returns a promise resolving once the entire form completed parsing all input values. The returned promise is rejected if any parsed values are not meeting the validation constraints of their respective elements.

render(){Promise.<Node>}

form.js, line 631

Render the form markup.

Returns:
Type Description
Promise.<Node> Returns a promise resolving to the toplevel form DOM node once the rendering is complete.

reset(){Promise.<Node>}

form.js, line 620

Reset the form by re-rendering its contents. This will revert all unsaved user inputs to their initial form state.

Returns:
Type Description
Promise.<Node> Returns a promise resolving to the toplevel form DOM node once the re-rendering is complete.

save(cb, silent){Promise.<void>}

form.js, line 590

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

If set to true, trigger an alert message to the user in case saving the form data failes. Otherwise fail silently.
Returns:
Type Description
Promise.<void> Returns a promise resolving once the entire save operation is complete. The returned promise is rejected if any step of the save operation failed.

section(sectionclass, classargs){LuCI.form.AbstractSection}

form.js, line 511

Add a configuration section to the map.

LuCI forms follow the structure of the underlying UCI configurations, 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 Description
sectionclass LuCI.form.AbstractSection

The section class to use for rendering the configuration section. Note that this value must be the class itself, not a class instance obtained from calling new. It must also be a class dervied from LuCI.form.AbstractSection.
classargs string repeatable

Additional arguments which are passed as-is to the contructor of the given section class. Refer to the class specific constructor documentation for details.
Returns:
Type Description
LuCI.form.AbstractSection Returns the instantiated section class instance.

inherited stripTags(input){string}

form.js, line 286

Strip any HTML tags from the given input string.

Name Type Description
input string

The input string to clean.
Returns:
Type Description
string The cleaned input string with HTML removes removed.

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

form.js, line 320

Format the given named property as title string.

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

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

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

In all other cases, null is returned.

Name Type Description
property string

The name of the element property to use.
fmt_args * repeatable

Extra values to format the title string with.
Returns:
Type Description
string | null The formatted title string or null if the property did not exist or was neither a string nor a function.