From 3942789dc62d6a0e7fcfb0a935bfe5c8d372245b Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Tue, 5 Nov 2019 09:33:40 +0100 Subject: documentation: add JS api docs Signed-off-by: Jo-Philipp Wich (cherry picked from commit d9452d1157aef6b8752fac0f4ed1e0b9221abb31) --- documentation/jsapi/LuCI.dom.html | 3135 +++++++++++++++++++++++++++++++++++++ 1 file changed, 3135 insertions(+) create mode 100644 documentation/jsapi/LuCI.dom.html (limited to 'documentation/jsapi/LuCI.dom.html') diff --git a/documentation/jsapi/LuCI.dom.html b/documentation/jsapi/LuCI.dom.html new file mode 100644 index 0000000000..b98c8f0a66 --- /dev/null +++ b/documentation/jsapi/LuCI.dom.html @@ -0,0 +1,3135 @@ + + + + + JSDoc: Class: dom + + + + + + + + + + +
+ +

Class: dom

+ + + + + + +
+ +
+ +

+ LuCI.dom

+ +

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

+ + +
+ +
+
+ + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + +

Methods

+ + + + + + + +

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

+ + + + + + +
+

Appends the given children data to the given node.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +* + + + + + + + + + +

The Node argument to append the children to.

children + + +* + + + + + + <optional>
+ + + + + +

The childrens to append to the given node.

+

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

+

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

+

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

+

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +Node +| + +null + + +
+
+ + + + + + + + + + + + + +

attr(node, key, valopt)

+ + + + + + +
+

Sets attributes or registers event listeners on element nodes.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +* + + + + + + + + + +

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

key + + +string +| + +Object.<string, *> + + + + + + + + + +

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

val + + +* + + + + + + <optional>
+ + + + + +

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

+

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

+

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

+

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +

bindClassInstance(node, inst) → {Class}

+ + + + + + +
+

Binds the given class instance ot the specified DOM Node.

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
node + + +Node + + + +

The DOM Node instance to bind the class to.

inst + + +Class + + + +

The Class instance to bind to the node.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

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

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Returns the bound class instance.

+
+ + + +
+
+ Type +
+
+ +Class + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +Node + + + + + + + + + +

The DOM Node instance to start from.

method + + +string + + + + + + + + + +

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

params + + +* + + + + + + + + + + <repeatable>
+ +

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +* +| + +null + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

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

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +* + + + + + + + + + +

The Node argument to replace the children of.

children + + +* + + + + + + <optional>
+ + + + + +

The childrens to replace into the given node.

+

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

+

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

+

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

+

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +Node +| + +null + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

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

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
html + + +* + + + + + + + + + +

Describes the node to create.

+

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

+

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

+

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

+

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

attr + + +Object.<string, *> + + + + + + <optional>
+ + + + + +

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

data + + +* + + + + + + <optional>
+ + + + + +

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

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

+
+
+
+
+
+
+ Type +
+
+ +InvalidCharacterError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Returns the newly created Node.

+
+ + + +
+
+ Type +
+
+ +Node + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

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

+

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

+

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

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

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

key + + +string +| + +null + + + + + + <optional>
+ + + + + +

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

val + + +* +| + +null + + + + + + <optional>
+ + + + + +

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +* + + +
+
+ + + + + + + + + + + + + +

elem(e) → {boolean}

+ + + + + + +
+

Tests whether the given argument is a valid DOM Node.

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
e + + +* + + + +

The value to test.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +boolean + + +
+
+ + + + + + + + + + + + + +

findClassInstance(node) → {Class|null}

+ + + + + + +
+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
node + + +Node + + + +

The DOM Node instance to start from.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +Class +| + +null + + +
+
+ + + + + + + + + + + + + +

isEmpty(node, ignoreFnopt) → {boolean}

+ + + + + + +
+

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

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +Node + + + + + + + + + +

The DOM Node instance to test.

ignoreFn + + +LuCI.dom~ignoreCallbackFn + + + + + + <optional>
+ + + + + +

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

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +boolean + + +
+
+ + + + + + + + + + + + + +

matches(node, selectoropt) → {boolean}

+ + + + + + +
+

Tests whether a given Node matches the given query selector.

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +* + + + + + + + + + +

The Node argument to test the selector against.

selector + + +string + + + + + + <optional>
+ + + + + +

The query selector expression to test against the given node.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +boolean + + +
+
+ + + + + + + + + + + + + +

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

+ + + + + + +
+

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

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
node + + +* + + + + + + + + + +

The Node argument to find the closest parent for.

selector + + +string + + + + + + <optional>
+ + + + + +

The query selector expression to test against each parent.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +Node +| + +null + + +
+
+ + + + + + + + + + + + + +

parse(s) → {Node}

+ + + + + + +
+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
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 <div>foo</div> <div>bar</div> will only return +the first div element node.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

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

+
+ + + +
+
+ Type +
+
+ +Node + + +
+
+ + + + + + + + + + + +

Type Definitions

+ + + + + + + +

ignoreCallbackFn(node) → {boolean}

+ + + + + + +
+

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

+

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

+
+ + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
node + + +Node + + + +

The child node to test.

+ + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Source:
+
+ + + + + + + +
+ + + + + + + + + + + + + + + +
Returns:
+ + +
+

Boolean indicating whether to ignore the node or not.

+
+ + + +
+
+ Type +
+
+ +boolean + + +
+
+ + + + + + + + + + + +
+ +
+ + + + +
+ + + +
+ +
+ Documentation generated by JSDoc 3.6.3 on Tue Nov 05 2019 09:33:05 GMT+0100 (Central European Standard Time) +
+ + + + + \ No newline at end of file -- cgit v1.2.3