Class: dom

Methods

append(node, children){Node|null}

luci.js, line 2216

Appends the given children data to the given node.

Name	Type	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.

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 2331

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

bindClassInstance(node, inst){Class}

luci.js, line 2565

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.

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 2619

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 2283

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.

Name	Type	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.

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 2409

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 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 2485

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 2079

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 2585

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 2665

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 2140

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 2167

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 2098

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 2628

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.