JSDoc: Module: kongUtilDom

Methods

(inner) $(s, bopt) → {null|Element|Array.<(null|Element)>|Object.<(null|Element|Object)>}

Shortcut to querySelector, but different if not given a string.

Parameters:

Name	Type	Attributes	Default	Description
`s`	string \| Array.<string> \| Object \| Element			`string`: leads this function works exactly as `querySelector`. The result would be `Element \| null`. `Array.<string>`: Each selector string in the array would be corresponding to the result `Array.<Element\|null>`. `Object.<string\|Object>`: Each property would be corresponding to the result object, recursively. `Element`: just returns itself.
`b`	Element \| Document	<optional>	document	If not having `querySelector` method, then `document` is used. This is useful if you wanna pass this function as the argument in `Array.map`.

Source:

dom.mjs, line 35

Returns:

if s is a string or Element

Type

null | Element
if s is an Array

Type

Array.<(null|Element)>
if s is an Object

Type

Object.<(null|Element|Object)>

Examples

/// get the first button by a string
    $("button, [type=button], [type=submit]");

/// assign elements by respective selectors
    const [myForm, myTable, myTextArea] = $(["#myForm", ".myTable", "textarea"]);

/// safe to use in `Array.map()`
    const [myForm, myTable, myTextArea] = ["#myForm", ".myTable", "textarea"].map($);

/// nested object
    $({form: 'form', inputs: {text: '[type=text]', password: '[type=password]'}});

(inner) $$(s, baseopt) → {Array|Object}

Shortcut to querySelectorAll but returns an array instead of NodeList. Different if not given a string, like $ differs from querySelector; however, for selectors have no matches, empty array is returned instead of null.

Parameters:

Name	Type	Attributes	Default	Description
`s`	string \| Array.<string> \| Object			one or more CSS selector string
`base`	Element \| Document	<optional>	document	if not an object having `querySelector` method, then it's ignored and `document` is used.

Source:

dom.mjs, line 77

Returns:

Type: Array | Object

Example

/// returns all trimmed values of <input>'s in `.myForm`.
    $$(".myForm input").map(input => input.value.trim());

(inner) clearElement(elemopt) → {void}

call Element.replaceChildren() without any argument specified.

Parameters:

Name	Type	Attributes	Default	Description
`elem`	Element	<optional>	this

Deprecated:

Source:

dom.mjs, line 306

See:

https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren#emptying_a_node

Returns:

Type: void

(inner) createElement()

my old JSON format to represent DOM; shall be replaced by createElementFromJsonML.

Deprecated:

Source:

dom.mjs, line 295

See:

https://github.com/kong0107/jsml

(inner) createElementFromJsonML(jsonml, namespaceopt) → {Element|TextNode}

Use JsonML to create an HTML element. For attributes setting, see setAttributes.

Parameters:

Name	Type	Attributes	Description
`jsonml`	JsonML
`namespace`	string	<optional>	set this to use `createElementNS()`

Source:

dom.mjs, line 212

See:

setAttributes

Returns:

Type: Element | TextNode

(inner) createElementFromTemplate(template) → {Node}

Use HTMLTemplateElement to create an HTML element.

Parameters:

Name	Type	Description
`template`	string \| Node \| HTMLTemplateElement	string: selector of the template element Node: the node to be cloned HTMLTemplateElement: the template where the first element is to be cloned

Source:

dom.mjs, line 266

See:

https://developer.mozilla.org/zh-TW/docs/Web/HTML/Element/template

Returns:

Type: Node

(inner) downloadData(data, filename, mimeTypeopt) → {string}

Download the given data.

Parameters:

Name	Type	Attributes	Default
`data`	string \| ArrayBuffer \| TypedArray \| DataView \| Blob
`filename`	string
`mimeType`	string	<optional>	''

Source:

dom.mjs, line 352

Returns:

Type: string

(inner) downloadURL(href, filename) → {undefined}

Make the borowser download the given URL to the local filesystem.

Parameters:

Name	Type	Description
`href`	URL \| string
`filename`	string

Source:

dom.mjs, line 338

Returns:

Type: undefined

(inner) extendElementPrototype()

Add some methods to Element class.

Source:

dom.mjs, line 592

(inner) getNodes(acceptopt, rejectopt, baseopt) → {Array.<Node>}

Get nodes within the specified node.

Parameters:

Name	Type	Attributes	Default	Description
`accept`	string \| Array.<string> \| function	<optional>	()=>true	fit nodes are included
`reject`	string \| Array.<string> \| function	<optional>	()=>false	fit nodes are excluded
`base`	Element \| Document	<optional>	document	root of the DOM tree to travere

Source:

dom.mjs, line 149

Returns:

nodes which fit accept but not within those fit reject

Type: Array.<Node>

(inner) isEventInElement(event, elemopt) → {boolean}

Check wheather a mouse event happens inside an element, even its target is not the element. Could be assign to Element.prototype.

Parameters:

Name	Type	Attributes	Default	Description
`event`	MouseEvent
`elem`	Element \| string	<optional>	this	the Element or the query selector to it

Source:

dom.mjs, line 320

Returns:

Type: boolean

(inner) parseHTML(html, selectorsopt) → {HTMLDocument|Element|null}

Shortcut to DOMParser.parseFromString but returns the first element in HTMLBodyElement by default.

Parameters:

Name	Type	Attributes	Default	Description
`html`	string
`selectors`	*	<optional>	body > *	If given but not a string or array of strings, the whole `HTMLDocument` is returned. Otherwise, the first element in the DOM tree matching `selectors` is returned; if no such elements, `null` is returned. Defaults to return the first element in `document.body`.

Source:

dom.mjs, line 101

Returns:

Incomplete HTML string may lead to unexpected result. Browsers may unexpectedly add essential tags such as <html>, <head>, and <body>, even given html string contains no such tags.

It may also omit tags if the structure is not complete. For example, <tr> as the root node of the html string may cause browsers not creating elements but only the text nodes within them.

Type: HTMLDocument | Element | null

Examples

/// returns an `Element` whose `tagName` is "em" and has string "hi!" as its text content.
    parseHTML("<EM>hi!</em>");

/// returns an `HTMLDocument` which could be represented by "<html><head></head><body><em>HI</em></body></html>".
    parseHTML("<EM>hi!</em>", null);

/// returns an `HTMLDocument` which could be represented by "<html><head><title>title</title></head><body><p>paragraph</p></body></html>".
    parseHTML("<title>title</title><p>paragraph</p>", {});

/// returns null because `<title>` is automatically inserted into `<head>` and thus nothing in `<body>`.
    parseHTML("<title>my title</title>");

/// returns null because `<tr>` is not allowed to exist outsied `<table>` and thus there is only a text node (which isn't an `Element`) in `<body>`.
    parseHTML("<tr><td>QQ</td></tr>");

(inner) setAria(s, attr, valueopt) → {null|Element}

Set ARIA attribute of the first Element, if found any.

Parameters:

Name	Type	Attributes	Default	Description
`s`	string \| Element			CSS selector string, or an Element
`attr`	string			ARIA attribute name, `aria-` is auto-prefixed.
`value`	NullLike \| true \| string	<optional>	null	NullLike value removes the attribute; true set it as empty string; others treated as string value.

Source:

dom.mjs, line 411

Returns:

the first found Element, or null.

Type: null | Element

(inner) setAttributes(s, attributes) → {null|Element}

Set attributes of an Element by an object as a map.

Attributes with namespace prefix are also supported.

Attributes with undefined, null, or false value in the first argument would be removed in the Element, except event listeners.

Event listeners are added by "on*"" such as "onclick" (case-insensitive).

CSS class could be assigned by string or Array.<string>.

Inline style could be assigned by string or Object.<string>.

Set text property of the first argument would assign the element's textContent, though it's not an attribute.

Parameters:

Name Type Description

s

string | Element

CSS selector string, or an Element

attributes

Object

Properties

Name	Type	Attributes
`onClick`	function	<optional>
`class`	NullLike \| string \| Array.<string>	<optional>
`style`	NullLike \| string \| Object.<string, (string\|NullLike)>	<optional>
`data`	NullLike \| Object.<string, (string\|NullLike)>	<optional>
`aria`	NullLike \| Object.<string, (string\|NullLike)>	<optional>

Source:

dom.mjs, line 537

Returns:

the first found Element, or null if not found.

Type: null | Element

Examples

/// set body background to red
    setAttributes('#some-input', {
        type: 'text',
        value: 'my string'
    });

/// set body background to red and text to white
    setAttributes('body', {style: 'background-color: red; color: white'});

/// set body background to red
    setAttributes('body', {style: {
        backgroundColor: 'red',
        color: 'white'
    }});

/// set body class
    setAttributes('body', {class: 'my-class your-class'});

/// set body class
    setAttributes('body', {class: ['my-class', 'your-class']});

(inner) setText(s, textopt) → {null|Element}

Set textContent of the first Element, if found any. Useful if you are not sure about its existence.

Parameters:

Name	Type	Attributes	Default	Description
`s`	string \| Element			CSS selector string, or an Element
`text`	string	<optional>	''

Source:

dom.mjs, line 381

Returns:

the first found Element, or null if not found.

Type: null | Element

Type Definitions

JsonML

JSON Markup Language structure

Type:

Array

Properties:

Name	Type	Attributes	Description
`0`	string		HTML tag to create
`1`	Object		attributes those to be set to the HTML element
`2`	JsonML \| string	<optional>	first child of the element created
`3`	JsonML \| string	<optional>	second child of the element created

Source:

dom.mjs, line 10

See:

http://www.jsonml.org/

NullLike

Type:

undefined | null | false

Source:

dom.mjs, line 20