From 40982927c6b54e950be19aceeb93fe56f6d8ab29 Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Tue, 7 Apr 2020 16:34:58 +0200 Subject: docs: update js api docs Signed-off-by: Jo-Philipp Wich --- docs/jsapi/LuCI.form.JSONMap.html | 5540 +++++++++++++++++++++++++++++++++++++ 1 file changed, 5540 insertions(+) create mode 100644 docs/jsapi/LuCI.form.JSONMap.html (limited to 'docs/jsapi/LuCI.form.JSONMap.html') diff --git a/docs/jsapi/LuCI.form.JSONMap.html b/docs/jsapi/LuCI.form.JSONMap.html new file mode 100644 index 0000000000..da1d72f90a --- /dev/null +++ b/docs/jsapi/LuCI.form.JSONMap.html @@ -0,0 +1,5540 @@ + + + + + Class: JSONMap + + + + + + + + + + + + + + + + + +
+ +
+

+ +
+ +
+ +
+
+

Class: JSONMap

+ + + + +
+ +
+

+ LuCI.form. + + JSONMap +

+ +

A JSONMap class functions similar to LuCI.form.Map +but uses a multidimensional JavaScript object instead of UCI configuration +as data source.

+ +
+ +
+
+ + + + +
+
+

+ + new LuCI.form.JSONMap(data, title, description) +

+ + +
+ form.js, line 730 +
+ +
+ + +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
data + + +Object.<string, (Object.<string, *>|Array.<Object.<string, *>>)> + + + + + + + + + + +

The JavaScript object to use as data source. Internally, the object is +converted into an UCI-like format. Its toplevel 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 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

+ + + + + + + + + + + + + + + +

Methods

+ +
+ +
+
+

+ + inherited + + append(element) +

+ + +
+ form.js, line 202 +
+ +
+ + +
+
+ + +
+

Add another form element as children to this element.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
element + + +AbstractElement + + + + + +

The form element to add.

+ + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ + + +
+
+

+ + inherited + + chain(config) +

+ + +
+ form.js, line 457 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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.

+ + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ + + +
+
+

+ + inherited + + findElement(selector_or_attrname, attrvalue){Node|null} +

+ + +
+ form.js, line 439 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + Node + | + + null + + + Returns the first found DOM node or null if no element matched.
+ + + + +
+ + + +
+
+

+ + inherited + + findElements(selector_or_attrname, attrvalue){NodeList} +

+ + +
+ form.js, line 396 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + NodeList + + + Returns a (possibly empty) DOM NodeList containing the found DOM nodes.
+ + + + +
+ + + +
+
+

+ + inherited + + load(){Promise.<void>} +

+ + +
+ form.js, line 511 +
+ +
+ + +
+
+ + +
+

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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + 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.
+ + + + +
+ + + +
+
+

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

+ + +
+ form.js, line 661 +
+ +
+ + +
+
+ + +
+

Find a form option element instance.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + 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.
+ + + + +
+ + + +
+
+

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

+ + +
+ form.js, line 529 +
+ +
+ + +
+
+ + +
+

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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + 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.
+ + + + +
+ + + +
+
+

+ + inherited + + render(){Promise.<Node>} +

+ + +
+ form.js, line 593 +
+ +
+ + +
+
+ + +
+

Render the form markup.

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

+ + inherited + + reset(){Promise.<Node>} +

+ + +
+ form.js, line 582 +
+ +
+ + +
+
+ + +
+

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

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

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

+ + +
+ form.js, line 559 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefaultDescription
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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + 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.
+ + + + +
+ + + +
+
+

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

+ + +
+ form.js, line 489 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + LuCI.form.AbstractSection + + + Returns the instantiated section class instance.
+ + + + +
+ + + +
+
+

+ + inherited + + stripTags(input){string} +

+ + +
+ form.js, line 278 +
+ +
+ + +
+
+ + +
+

Strip any HTML tags from the given input string.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
input + + +string + + + + + +

The input string to clean.

+ + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
Returns:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + string + + + The cleaned input string with HTML removes removed.
+ + + + +
+ + + +
+
+

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

+ + +
+ form.js, line 312 +
+ +
+ + +
+
+ + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
property + + +string + + + + + + + + + + +

The name of the element property to use.

fmt_args + + +* + + + + + + + + + + repeatable + + +

Extra values to format the title string with.

+ + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
Returns:
+ + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ + string + | + + null + + + The formatted title string or null if the property did not exist or +was neither a string nor a function.
+ + + + +
+ +
+ + + + + + + +
+ +
+ + + + + + + +
+ Documentation generated by JSDoc 3.6.3 on Tue Apr 07 2020 16:33:40 GMT+0200 (Central European Summer Time) +
+
+
+ + + + \ No newline at end of file -- cgit v1.2.3