Monster.DOM. CustomElement

The CustomElement class provides a way to define a new HTML element using the power of Custom Elements.

IMPORTANT: After defining a CustomElement, the registerCustomElement method must be called with the new class name to make the tag defined via the getTag method known to the DOM.

You can create an instance of the object via the document.createElement() function.

Interaction

Styling

To display custom elements optimally, the :defined pseudo-class can be used. To prevent custom elements from being displayed and flickering until the control is registered, it is recommended to create a CSS directive.

In the simplest case, you can simply hide the control:

<style>
my-custom-element:not(:defined) {
    display: none;
}

my-custom-element:defined {
    display: flex;
}
</style>

Alternatively, you can display a loader:

my-custom-element:not(:defined) {
    display: flex;
    box-shadow: 0 4px 10px 0 rgba(33, 33, 33, 0.15);
    border-radius: 4px;
    height: 200px;
    position: relative;
    overflow: hidden;
}

my-custom-element:not(:defined)::before {
    content: '';
    display: block;
    position: absolute;
    left: -150px;
    top: 0;
    height: 100%;
    width: 150px;
    background: linear-gradient(to right, transparent 0%, #E8E8E8 50%, transparent 100%);
    animation: load 1s cubic-bezier(0.4, 0.0, 0.2, 1) infinite;
}

Constructor

new CustomElement()

A base class for HTML5 custom controls.

A new object is created. First the initOptions method is called. Here the options can be defined in derived classes. Subsequently, the shadowRoot is initialized.

IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via document.createElement().

Since
  • 1.7.0
Copyright
  • schukai GmbH
License
  • AGPLv3
Throws:

the options attribute does not contain a valid json definition.

Type
Error
Example
import {getDocumentTheme} from '@schukai/monster/source/dom/theme.mjs';

const theme = getDocumentTheme();
console.log(theme.getName());
// ↦ monster

Extends

Members

defaults

The defaults property defines the default values for a control.

The defaults property defines the default values for a control. If you want to override these, you can use various methods, which are described in the documentation available at https://monsterjs.orgendocconfigurate-a-monster-control.

The individual configuration values are listed below:

More information about the shadowRoot can be found in the MDN Web Docs, in the HTML Standard or in the WHATWG Wiki.

More information about the template element can be found in the MDN Web Docs.

More information about the slot element can be found in the MDN Web Docs.

Properties
NameTypeDefaultDescription
disabledbooleanfalse

Specifies whether the control is disabled. When present, it makes the element non-mutable, non-focusable, and non-submittable with the form.

shadowModestringopen

Specifies the mode of the shadow root. When set to open, elements in the shadow root are accessible from JavaScript outside the root, while setting it to closed denies access to the root's nodes from JavaScript outside it.

delegatesFocusBooleantrue

Specifies the behavior of the control with respect to focusability. When set to true, it mitigates custom element issues around focusability. When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available :focus styling.

templatesObject

Specifies the templates used by the control.

Properties
NameTypeDescription
mainstring

Specifies the main template used by the control.

templateMappingObject

Specifies the mapping of templates.

Since
  • 1.8.0

(static) instanceSymbol

This method is called by the instanceof operator.

This method is called by the instanceof operator.

Since
  • 2.1.0

(static) observedAttributes

This method determines which attributes are to be monitored by attributeChangedCallback().

This method determines which attributes are to be monitored by attributeChangedCallback(). Unfortunately, this method is static. Therefore, the observedAttributes property cannot be changed during runtime.

Since
  • 1.15.0

Methods

addAttributeObserver(attribute, callback) → {Monster.DOM.CustomElement}

Parameters:
NameTypeDescription
attribute
callback
Returns:
Type: 
Monster.DOM.CustomElement

adoptedCallback() → {void}

The custom element has been moved into a new document (e.g.

The custom element has been moved into a new document (e.g. someone called document.adoptNode(el)).

Since
  • 1.7.0
Returns:
Type: 
void

assembleMethodSymbol() → {CustomElement}

This method is called once when the object is included in the DOM for the first time.

This method is called once when the object is included in the DOM for the first time. It performs the following actions:

  1. Extracts the options from the attributes and the script tag of the element and sets them.
  2. Initializes the shadow root and its CSS stylesheet (if specified).
  3. Initializes the HTML content of the element.
  4. Initializes the custom elements inside the shadow root and the slotted elements.
  5. Attaches a mutation observer to observe changes to the attributes of the element.
Since
  • 1.8.0
Returns:
  • The updated custom element.
Type: 
CustomElement

attachObserver(observer) → {CustomElement}

attach a new observer

.

attach a new observer

Parameters:
NameTypeDescription
observerObserver
Returns:
Type: 
CustomElement

attributeChangedCallback(attrName, oldVal, newVal) → {void}

Called when an observed attribute has been added, removed, updated, or replaced.

Called when an observed attribute has been added, removed, updated, or replaced. Also called for initial values when an element is created by the parser, or upgraded. Note: only attributes listed in the observedAttributes property will receive this callback.

Parameters:
NameTypeDescription
attrNamestring
oldValstring
newValstring
Since
  • 1.15.0
Returns:
Type: 
void

callCallback(name, args) → {*}

Calls a callback function if it exists.

Calls a callback function if it exists.

Parameters:
NameTypeDescription
namestring
args*
Returns:
Type: 
*

connectedCallback() → {void}

This method is called every time the element is inserted into the DOM.

This method is called every time the element is inserted into the DOM. It checks if the custom element has already been initialized and if not, calls the assembleMethod to initialize it.

Since
  • 1.7.0
See
Returns:
Type: 
void

containsObserver(observer) → {ProxyObserver}

Parameters:
NameTypeDescription
observerObserver
Returns:
Type: 
ProxyObserver

detachObserver(observer) → {CustomElement}

detach a observer

.

detach a observer

Parameters:
NameTypeDescription
observerObserver
Returns:
Type: 
CustomElement

disconnectedCallback() → {void}

Called every time the element is removed from the DOM.

Called every time the element is removed from the DOM. Useful for running clean up code.

Since
  • 1.7.0
Returns:
Type: 
void

getInternalUpdateCloneData() → {*}

You know what you are doing? This function is only for advanced users.

You know what you are doing? This function is only for advanced users. The result is a clone of the internal data.

Returns:
Type: 
*

getOption(path, defaultValue) → {*}

nested options can be specified by path a.b.c

.

nested options can be specified by path a.b.c

Parameters:
NameTypeDescription
pathstring
defaultValue*
Since
  • 1.10.0
Returns:
Type: 
*

hasNode(node) → {boolean}

Parameters:
NameTypeDescription
nodeNode
Since
  • 1.19.0
Throws:

value is not an instance of

Type
TypeError
Returns:
Type: 
boolean

initMethodSymbol() → {CustomElement}

Is called once via the constructor

.

Is called once via the constructor

Since
  • 1.8.0
Returns:
Type: 
CustomElement

removeAttributeObserver(attribute) → {Monster.DOM.CustomElement}

Parameters:
NameTypeDescription
attribute
Returns:
Type: 
Monster.DOM.CustomElement

setOption(path, value) → {CustomElement}

Set option and inform elements

.

Set option and inform elements

Parameters:
NameTypeDescription
pathstring
value*
Since
  • 1.14.0
Returns:
Type: 
CustomElement

setOptions(options) → {CustomElement}

Parameters:
NameTypeDescription
optionsstring | object
Since
  • 1.15.0
Returns:
Type: 
CustomElement

updateI18n() → {Monster.DOM.CustomElement}

This method updates the labels of the element.

This method updates the labels of the element. The labels are defined in the options object. The key of the label is used to retrieve the translation from the document. If the translation is different from the label, the label is updated.

Before you can use this method, you must have loaded the translations.

Throws:

Cannot find element with translations. Add a translations object to the document.

Type
Error
Returns:
Type: 
Monster.DOM.CustomElement

updaterTransformerMethodsSymbol() → {object}

This method is called once when the object is equipped with update for the dynamic change of the dom.

This method is called once when the object is equipped with update for the dynamic change of the dom. The functions returned here can be used as pipe functions in the template.

In the example, the function my-transformer is defined. In the template you can use it as follows:

<my-element data-monster-option-transformer="path:my-value | call:my-transformer"></my-element>
Since
  • 2.43.0
Returns:
Type: 
object
Example
[updaterTransformerMethodsSymbol]() {
   return {
      "my-transformer": (value) => {
          switch (typeof Wert) {
          case "string":
              return value + "!";
          case "Zahl":
              return value + 1;
          default:
              return value;
          }
   }
   };
 };

(static) getCSSStyleSheet() → {CSSStyleSheet|Array.<CSSStyleSheet>|string|undefined}

The getCSSStyleSheet() method returns a CSSStyleSheet object that defines the styles for the custom element.

The getCSSStyleSheet() method returns a CSSStyleSheet object that defines the styles for the custom element. If the environment does not support the CSSStyleSheet constructor, then an object can be built using the provided detour.

If undefined is returned, then the shadow root does not receive a stylesheet.

Example usage:

static getCSSStyleSheet() {
    const sheet = new CSSStyleSheet();
    sheet.replaceSync("p { color: red; }");
    return sheet;
}

If the environment does not support the CSSStyleSheet constructor, you can use the following workaround to create the stylesheet:

const doc = document.implementation.createHTMLDocument('title');
let style = doc.createElement("style");
style.innerHTML = "p { color: red; }";
style.appendChild(document.createTextNode(""));
doc.head.appendChild(style);
return doc.styleSheets[0];
Returns:

A CSSStyleSheet object or an array of such objects that define the styles for the custom element, or undefined if no stylesheet should be applied.

Type: 
CSSStyleSheet | Array.<CSSStyleSheet> | string | undefined

(static) getTag() → {string}

The getTag() method returns the tag name associated with the custom element.

The getTag() method returns the tag name associated with the custom element. This method should be overwritten by the derived class.

Note that there is no check on the name of the tag in this class. It is the responsibility of the developer to assign an appropriate tag name. If the name is not valid, the registerCustomElement() method will issue an error.

Since
  • 1.7.0
See
Throws:

This method must be overridden by the derived class.

Type
Error
Returns:

The tag name associated with the custom element.

Type: 
string