Class: dom

LuCI. dom

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

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

new LuCI.dom()

luci.js, line 1161

Methods

append(node, children){Node|null}

luci.js, line 1312

Appends the given children data to the given node.

Name Type Description
node *

The Node argument to append the children to.
children * optional

The children to append to the given node.

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

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

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

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.
Returns:
Type Description
Node | null 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.

attr(node, key, val)

luci.js, line 1427

Sets attributes or registers event listeners on element nodes.

Name Type Description
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 an event handler on the given node with the key parameter being the event name.

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

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

bindClassInstance(node, inst){Class}

luci.js, line 1664

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 Node instance to bind the class to.
inst Class

The Class instance to bind to the node.
Throws:

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

Type
TypeError
Returns:
Type Description
Class Returns the bound class instance.

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

luci.js, line 1718

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 Description
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.
Returns:
Type Description
* | null 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.

content(node, children){Node|null}

luci.js, line 1379

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 Description
node *

The Node argument to replace the children of.
children * optional

The children to replace into the given node.

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

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

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

When children is any other non-null value, it will be converted to a string and appended to the innerHTML property of the given node.
Returns:
Type Description
Node | null 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.

create(html, attr, data){Node}

luci.js, line 1505

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 Description
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 a child to the fragment.

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

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

When the value of html is any other string, it will be passed to document.createElement() for creating a new DOM Node of the given name.
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.
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:
Type Description
Node Returns the newly created Node.

data(node, key, val){*}

luci.js, line 1581

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 Description
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.
Returns:
Type Description
* Returns the get or set value, or null when no value could be found.

elem(e){boolean}

luci.js, line 1187

Tests whether the given argument is a valid DOM Node.

Name Type Description
e *

The value to test.
Returns:
Type Description
boolean Returns true if the value is a DOM Node, else false.

findClassInstance(node){Class|null}

luci.js, line 1684

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 Node instance to start from.
Returns:
Type Description
Class | null 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.

isEmpty(node, ignoreFn){boolean}

luci.js, line 1764

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 Description
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.
Returns:
Type Description
boolean 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.

matches(node, selector){boolean}

luci.js, line 1236

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 Description
node *

The Node argument to test the selector against.
selector string optional

The query selector expression to test against the given node.
Returns:
Type Description
boolean 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.

parent(node, selector){Node|null}

luci.js, line 1263

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 Description
node *

The Node argument to find the closest parent for.
selector string optional

The query selector expression to test against each parent.
Returns:
Type Description
Node | null 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.

parse(s){Node}

luci.js, line 1206

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 <div>foo</div> <div>bar</div> will only return the first div element node.
Returns:
Type Description
Node Returns the first DOM Node extracted from the HTML fragment or null on parsing failures or if no element could be found.

Type Definitions

ignoreCallbackFn(node){boolean}

luci.js, line 1727

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.
Returns:
Type Description
boolean Boolean indicating whether to ignore the node or not.