JSDoc: Class: dom

Source:

luci.js, line 2065

Methods

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

Appends the given children data to the given node.

Parameters:

Name Type Attributes Description

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

node

The Node argument to append the children to.

children

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:

luci.js, line 2216

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

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.

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

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:

luci.js, line 2331

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:

luci.js, line 2565

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:

luci.js, line 2619

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

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

node

The Node argument to replace the children of.

children

The childrens to replace into the given node.

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:

luci.js, line 2283

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

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.

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, *>

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

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

Source:

luci.js, line 2409

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:

luci.js, line 2485

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:

luci.js, line 2079

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:

luci.js, line 2585

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:

luci.js, line 2665

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:

luci.js, line 2140

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:

luci.js, line 2167

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:

luci.js, line 2098

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:

luci.js, line 2628

Returns:

Boolean indicating whether to ignore the node or not.

Type: boolean