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:
Name Type Attributes Description
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:
Name Type Attributes 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 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:
Name Type Description
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:
Name Type Attributes 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.
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:
Name Type Attributes Description
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:
Name Type Attributes 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 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:
Name Type Attributes 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.
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:
Name Type Description
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:
Name Type Description
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:
Name Type Attributes 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.
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:
Name Type Attributes Description
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:
Name Type Attributes Description
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:
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.
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:
Name Type Description
node Node

The child node to test.
Source:
Returns:

Boolean indicating whether to ignore the node or not.

Type
boolean