Namespace: DOM

In this namespace you will find classes and methods for handling the DOM.

Author: schukai GmbH

Classes

Assembler: Allows you to build an html fragment
CustomControl: A base class for custom controls based on CustomElement.
CustomElement: A base class for HTML5 custom controls.
FocusManager: Handle the focus
Resource: A Resource class
ResourceManager: A Resource class
Template: A template class
Theme: A theme class
Updater: The updater class connects an object with the dom

Namespaces

Resource: In this namespace you will find classes and methods for handling resources.
Worker: In this namespace you will find classes and methods for handling the DOM.

Members

(static, constant) ATTRIBUTEPREFIX :string

attribute prefix

Type:

string

(static, constant) ATTRIBUTE_ACCESSKEY :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_AUTOCAPITALIZE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_AUTOFOCUS :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_CLASS :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_CONTENTEDITABLE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_DIR :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_DISABLED :string

Type:

string

Since: 1.24.0
License: AGPLv3

(static, constant) ATTRIBUTE_DRAGGABLE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ENTERKEYHINT :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ERRORMESSAGE :string

Type:

string

Since: 1.24.0
License: AGPLv3

(static, constant) ATTRIBUTE_EXPORTPARTS :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_HIDDEN :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_HREF :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ID :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_INIT_CALLBACK :string

This is the name of the attribute to pass the callback to a control

Type:

string

Since: 3.48.0
License: AGPLv3

(static, constant) ATTRIBUTE_INPUTMODE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_IS :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ITEMID :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ITEMPROP :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ITEMREF :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ITEMSCOPE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_ITEMTYPE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_LANG :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_NONCE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_OBJECTLINK :string

Type:

string

Since: 1.9.0
License: AGPLv3

(static, constant) ATTRIBUTE_OPTIONS :string

This is the name of the attribute to pass options to a control

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_OPTIONS_SELECTOR :string

This is the name of the attribute to pass options to a control

Type:

string

Since: 1.30.0
License: AGPLv3

(static, constant) ATTRIBUTE_PART :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_PREFIX :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_ROLE :string

Type:

string

Since: 1.14.0
License: AGPLv3

(static, constant) ATTRIBUTE_SCRIPT_HOST :string

This is name of the attribute to pass the script host to a control

Type:

string

Since: 3.48.0
License: AGPLv3

(static, constant) ATTRIBUTE_SLOT :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_SPELLCHECK :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_SRC :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_TABINDEX :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_TEMPLATE_PREFIX :string

Type:

string

Since: 1.27.0
License: AGPLv3

(static, constant) ATTRIBUTE_THEME_NAME :string

Type:

string

(static, constant) ATTRIBUTE_THEME_PREFIX :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_TITLE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_TRANSLATE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_TYPE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_ATTRIBUTES :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_BIND :string

Type:

string

Since: 1.9.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_INSERT :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_INSERT_REFERENCE :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_REMOVE :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_REPLACE :string

Type:

string

Since: 1.8.0
License: AGPLv3

(static, constant) ATTRIBUTE_UPDATER_SELECT_THIS :string

Type:

string

Since: 1.27.1
License: AGPLv3

(static, constant) ATTRIBUTE_VALUE :string

Type:

string

Since: 1.24.0
License: AGPLv3

(static, constant) DEFAULT_THEME :string

default theme

Type:

string

(static, constant) TAG_LINK :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) TAG_SCRIPT :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) TAG_STYLE :string

Type:

string

Since: 1.25.0
License: AGPLv3

(static, constant) assembleMethodSymbol :symbol

Type:

symbol

(static, constant) attributeObserverSymbol :symbol

this symbol holds the attribute observer callbacks.

this symbol holds the attribute observer callbacks. The key is the attribute name.

Type:

symbol

(static, constant) customElementUpdaterLinkSymbol :symbol

Type:

symbol

Since: 1.24.0
License: AGPLv3

(static, constant) domReady :Promise

variable to check if dom is ready

This variable is a promise that is fulfilled as soon as the dom is available.

The DOMContentLoaded event is fired when the original HTML document is fully loaded and parsed without waiting for stylesheets, images, and subframes to finish loading.

document.readyState changes to interactive window's DOMContentLoaded event gets fired document.readyState changes to complete window's load event gets fired load

Type:

Promise

Since: 1.31.0
License: AGPLv3
See: https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState

(static, constant) initControlCallbackName :string

This is the name of the callback to pass the callback to a control

Type:

string

Since: 3.48.0
License: AGPLv3

(static, constant) initMethodSymbol :symbol

Type:

symbol

(static, constant) objectUpdaterLinkSymbol :symbol

Type:

symbol

Since: 1.24.0
License: AGPLv3

(static, constant) windowReady :Promise

variable to check if window is ready

This variable is a promise that is fulfilled as soon as the windows is available.

The load event fires when the entire page is loaded, including all dependent resources such as stylesheets, assets, and images. Unlike DOMContentLoaded, which fires as soon as the DOM of the page is loaded, without waiting for the resources to finish loading.

Type:

Promise

Since: 1.31.0
License: AGPLv3
See: https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event
https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState

Methods

(static) addAttributeToken(element, key, token) → {HTMLElement}

This method can be used to add a token to an attribute.

This method can be used to add a token to an attribute. Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`token`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement

(static) addObjectWithUpdaterToElement(elements, symbol, object) → {Array.<Promise>}

Parameters:

Name	Type	Description
`elements`	NodeList \| HTMLElement \| Set.<HTMLElement>
`symbol`	Symbol
`object`	object

Since: 1.23.0
License: AGPLv3

Throws:

elements is not an instance of NodeList, HTMLElement or Set
Type
TypeError
the context of the function is not an instance of HTMLElement
Type
TypeError
symbol must be an instance of Symbol
Type
TypeError

Returns:

Type:: Array.<Promise>

(static) addToObjectLink(element, symbol, object) → {boolean}

Adds a class attribute to an element.

Parameters:

Name	Type	Description
`element`	HTMLElement
`symbol`	Symbol
`object`	Object

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: boolean

(static) clearAttributeTokens(element, key) → {HTMLElement}

Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement

(static) containsAttributeToken(element, key, token) → {boolean}

This method can be used to determine whether an attribute has a token.

Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`token`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: boolean

(static) convertToPixels(value, parentElementopt, fontSizeElementopt) → {number}

Converts a CSS value to pixels.

As Example:

convertToPixels('1em') // returns the current font size in pixels
convertToPixels('1rem') // returns the current root font size in pixels
convertToPixels('1px') // returns 1
convertToPixels('100%') // returns the current width of the parent element in pixels

Following units are supported:

Parameters:

Name	Type	Attributes	Default
`value`	string
`parentElement`	HTMLElement	<optional>	document.documentElement
`fontSizeElement`	HTMLElement	<optional>	document.documentElement

Since: 3.34.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

Unsupported unit
Type
Error
Invalid value format
Type
Error

Returns:

Type:: number

(static) exports.findDocumentTemplate(id, currentNode) → {Monster.DOM.Template}

This method loads a template with the given ID and returns it.

To do this, it first reads the theme of the document and looks for the data-monster-theme-name attribute in the HTML tag.

<html data-monster-theme-name="my-theme">

If no theme was specified, the default theme is monster.

Now it is looked if there is a template with the given ID and theme id-theme and if yes it is returned. If there is no template a search for a template with the given ID id is done. If this is also not found, an error is thrown.

You can call the method via the monster namespace Monster.DOM.findDocumentTemplate().

<script type="module">
import {findTemplate} from '@schukai/monster/source/dom/template.mjs';
findDocumentTemplate()
</script>

Parameters:

Name	Type	Description
`id`	string
`currentNode`	Node

Since: 1.7.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

template id not found.
Type
Error
value is not a string
Type
TypeError

Returns:

Type:: Monster.DOM.Template

Example

import { findDocumentTemplate } from "https://cdn.jsdelivr.net/npm/@schukai/[email protected]/source/dom/template.mjs";

const template = document.createElement("template");
template.id = "myTemplate";
template.innerHTML = "<p>my default template</p>";
document.body.appendChild(template);

const themedTemplate = document.createElement("template");
themedTemplate.id = "myTemplate-myTheme";
themedTemplate.innerHTML = "<p>my themed template</p>";
document.body.appendChild(themedTemplate);

// loads the temple and since no theme is set the default template
const template1 = findDocumentTemplate("myTemplate");
console.log(template1.createDocumentFragment());
// ↦ '<p>my default template</p>'

// now we set our own theme
document
.querySelector("html")
.setAttribute("data-monster-theme-name", "myTheme");

// now we don't get the default template,
// but the template with the theme in the id
const template2 = findDocumentTemplate("myTemplate");
console.log(template2.createDocumentFragment());
// ↦ '<p>my themed template</p>'

(static) findClosestByAttribute(element, key, value) → {HTMLElement|undefined}

find closest node

This function searches, starting from an HTMLElemement, for the next element that has a certain attribute.

<div data-my-attribute="2" id="2">
    <div id="1"></div>
</div>

// if no value is specified (undefined), then only the attribute is checked.
findClosestByAttribute(document.getElementById('1'),'data-my-attribute'); // ↦ node with id 2
findClosestByAttribute(document.getElementById('2'),'data-my-attribute'); // ↦ node with id 2

// if a value is specified, for example an empty string, then the name and the value are checked.
findClosestByAttribute(document.getElementById('1'),'data-my-attribute', '');  // ↦ undefined
findClosestByAttribute(document.getElementById('1'),'data-my-attribute', '2'); // ↦ node with id 2

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`value`	string \| undefined

Since: 1.14.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement | undefined

(static) findClosestByClass(element, className) → {HTMLElement|undefined}

find closest node

This function searches, starting from an HTMLElemement, for the next element that has a certain attribute.

<div class="myclass" id="2">
    <div id="1"></div>
</div>

// if no value is specified (undefined), then only the attribute is checked.
findClosestByClass(document.getElementById('1'),'myclass'); // ↦ node with id 2
findClosestByClass(document.getElementById('2'),'myclass'); // ↦ node with id 2

<script type="module">
import {findClosestByClass} from '@schukai/monster/source/dom/attributes.mjs';
findClosestByClass();
</script>

Parameters:

Name	Type	Description
`element`	HTMLElement
`className`	string

Since: 1.27.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement | undefined

(static) findClosestObjectLink(element) → {HTMLElement|undefined}

Get the closest object link of a node

if a node is specified without a object link, a recursive search upwards is performed until the corresponding object link is found, or undefined is returned.

Get the closest object link of a node

if a node is specified without a object link, a recursive search upwards is performed until the corresponding object link is found, or undefined is returned.

Parameters:

Name	Type	Description
`element`	HTMLElement

Since: 1.10.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

value is not an instance of HTMLElement
Type TypeError

Returns:

Type:: HTMLElement | undefined

(static) findElementWithIdUpwards(element, targetId) → {HTMLElement|null}

Recursively searches upwards from a given element to find an ancestor element with a specified ID, considering both normal DOM and shadow DOM.

Parameters:

Name	Type	Description
`element`	HTMLElement \| ShadowRoot	The starting element or shadow root to search from.
`targetId`	string	The ID of the target element to find.

Since: 3.29.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

The ancestor element with the specified ID, or null if not found.

Type:: HTMLElement | null

(static) findTargetElementFromEvent(event, attributeName, attributeValue)

Help function to find the appropriate control

This function gets the path Event.composedPath() from an event and tries to find the next element up the tree element.closest() with the attribute and value. If no value, or a value that is undefined or null, is specified, only the attribute is searched.

Parameters:

Name	Type	Description
`event`	Event
`attributeName`	string
`attributeValue`	string \| null \| undefined

Since: 1.14.0
License: AGPLv3

Throws:

unsupported event
Type
Error
value is not a string
Type
TypeError
value is not an instance of HTMLElement
Type
TypeError

(static) fireCustomEvent(element, type) → {void}

Construct and send and event

You can call the function via the monster namespace new Monster.DOM.fireCustomEvent().

Parameters:

Name	Type	Description
`element`	HTMLElement \| HTMLCollection \| NodeList
`type`	string

Since: 1.29.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

value is not an instance of HTMLElement or HTMLCollection
Type TypeError

Returns:

Type:: void

(static) fireEvent(element, type) → {void}

Construct and send and event

The function sends an event

Parameters:

Name	Type	Description
`element`	HTMLElement \| HTMLCollection \| NodeList
`type`	string

Since: 1.10.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

value is not an instance of HTMLElement or HTMLCollection
Type TypeError

Returns:

Type:: void

(static) getContainingDocument(element) → {*}

Recursively searches upwards from a given element to find an ancestor element

Parameters:

Name	Type	Description
`element`	HTMLElement

Since: 3.36.0

Throws:

Invalid argument. Expected an HTMLElement.
Type Error

Returns:

Type:: *

(static) getDeviceDPI() → {number}

Returns the DPI of the device.

Since: 3.34.0

Returns:

Type:: number

(static) getDocument() → {object}

This method fetches the document object

In nodejs this functionality can be performed with jsdom.

This method fetches the document object

In nodejs this functionality can be performed with jsdom.

import {JSDOM} from "jsdom"
if (typeof window !== "object") {
   const {window} = new JSDOM('', {
       url: 'http://example.com/',
       pretendToBeVisual: true
   });

   [
       'self',
       'document',
       'Document',
       'Node',
       'Element',
       'HTMLElement',
       'DocumentFragment',
       'DOMParser',
       'XMLSerializer',
       'NodeFilter',
       'InputEvent',
       'CustomEvent'
   ].forEach(key => (getGlobal()[key] = window[key]));
}

Since: 1.6.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

not supported environment
Type Error

Returns:

Type:: object

(static) getDocumentFragmentFromString() → {DocumentFragment}

This method fetches the document object

In nodejs this functionality can be performed with jsdom.

This method fetches the document object

In nodejs this functionality can be performed with jsdom.

import {JSDOM} from "jsdom"
if (typeof window !== "object") {
   const {window} = new JSDOM('', {
       url: 'http://example.com/',
       pretendToBeVisual: true
   });

   [
       'self',
       'document',
       'Document',
       'Node',
       'Element',
       'HTMLElement',
       'DocumentFragment',
       'DOMParser',
       'XMLSerializer',
       'NodeFilter',
       'InputEvent',
       'CustomEvent'
   ].forEach(key => (getGlobal()[key] = window[key]));
}

Since: 1.6.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

not supported environment
Type
Error
value is not a string
Type
TypeError

Returns:

Type:: DocumentFragment

(static) getDocumentTheme() → {Theme}

The theming used in the document can be defined via the html-tag.

The theming used in the document can be defined via the html-tag. The theming is specified via the attribute data-monster-theme-name.

As name for a theme all characters are valid, which are also allowed for a HTMLElement-ID.

<html data-monster-theme-name="my-theme">

the default theme name is monster.

Since: 1.7.0
License: AGPLv3

Returns:

Type:: Theme

(static) getLinkedObjects(element, symbol) → {Iterator}

The ObjectLink can be used to attach objects to HTMLElements.

The ObjectLink can be used to attach objects to HTMLElements. The elements are kept in a set under a unique symbol and can be read via an iterator {@see getLinkedObjects}.

In addition, elements with an objectLink receive the attribute data-monster-objectlink.

With the method {@see addToObjectLink} the objects can be added.

Parameters:

Name	Type	Description
`element`	HTMLElement
`symbol`	Symbol

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

there is no object link for symbol
Type Error

Returns:

Type:: Iterator

(static) getLocaleOfDocument()

Tries to determine the locale used

With this function you can read the language version set by the document. For this the attribute lang in the html tag is read. If no attribute is set, en is used as default. Alternatively, the language version of the browser is used.

<html lang="en">

You can call the function via getLocaleOfDocument().

Since: 1.13.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

value is not a string
Type
TypeError
unsupported locale
Type
Error

(static) getWindow() → {object}

This method fetches the window object

In nodejs this functionality can be performed with jsdom.

This method fetches the window object

In nodejs this functionality can be performed with jsdom.

import {JSDOM} from "jsdom"
if (typeof window !== "object") {
   const {window} = new JSDOM('', {
       url: 'http://example.com/',
       pretendToBeVisual: true
   });

   getGlobal()['window']=window;

   [
       'self',
       'document',
       'Document',
       'Node',
       'Element',
       'HTMLElement',
       'DocumentFragment',
       'DOMParser',
       'XMLSerializer',
       'NodeFilter',
       'InputEvent',
       'CustomEvent'
   ].forEach(key => (getGlobal()[key] = window[key]));
}

Since: 1.6.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

not supported environment
Type Error

Returns:

Type:: object

(static) hasObjectLink(element, symbol) → {boolean}

Checks if an element has an object link

Parameters:

Name	Type	Description
`element`	HTMLElement
`symbol`	Symbol

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: boolean

(static) registerCustomElement(element) → {void}

This method registers a new element.

This method registers a new element. The string returned by CustomElement.getTag() is used as the tag.

Parameters:

Name	Type	Description
`element`	CustomElement

Since: 1.7.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

Failed to execute 'define' on 'CustomElementRegistry': is not a valid custom element name
Type DOMException

Returns:

Type:: void

(static) removeAttributeToken(element, key, token) → {HTMLElement}

This function can be used to remove tokens from an attribute.

Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`token`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement

(static) removeObjectLink(element, symbol) → {boolean}

Removes an object from an element

Parameters:

Name	Type	Description
`element`	HTMLElement
`symbol`	Symbol

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: boolean

(static) replaceAttributeToken(element, key, from, to) → {HTMLElement}

Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`from`	string
`to`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement

(static) toggleAttributeToken(element, key, token) → {HTMLElement}

With this method tokens in an attribute can be switched on or off.

With this method tokens in an attribute can be switched on or off. For example, classes can be switched on and off in the elements class attribute.

Tokens are always separated by a space.

Parameters:

Name	Type	Description
`element`	HTMLElement
`key`	string
`token`	string

Since: 1.9.0
Copyright: schukai GmbH
License: AGPLv3

Returns:

Type:: HTMLElement