Class: CustomControl

Constructor

new CustomControl()

A base class for custom controls based on CustomElement.

The constructor method of CustomControl, which is called when creating a new instance. It checks whether the element supports attachInternals() and initializes an internal form-associated element if supported. Additionally, it initializes a MutationObserver to watch for attribute changes.

See the links below for more information: CustomElementRegistry.define() CustomElementRegistry.get() and ElementInternals

Since: 1.14.0
Copyright: schukai GmbH
License: AGPLv3

Throws:

the ElementInternals is not supported and a polyfill is necessary
Type Error

Extends

Monster.DOM.CustomElement

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

Name Type Default Description

disabled

boolean

false

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

shadowMode

string

open

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.

delegatesFocus

Boolean

true

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.

templates

Object

Specifies the templates used by the control.

Properties

Name	Type	Description
`main`	string	Specifies the main template used by the control.

templateMapping

Object

Specifies the mapping of templates.

Since: 1.8.0
Overrides: Monster.DOM.CustomElement#defaults

form

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/form

formAssociated

Adding a static formAssociated property, with a true value, makes an autonomous custom element a form-associated custom element.

Since: 1.14.0
See: attachInternals()
Custom Elements Face Example

labels

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/labels

name

This is a method of internal api

states

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states

type

This is a method of internal api

validationMessage

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage

validity

This is a method of internal api

See: ValidityState
validity

value

Must be overridden by a derived class and return the value of the control.

This is a method of internal API, which is a part of the web standard for custom elements.

Since: 1.14.0

value

Must be overridden by a derived class and set the value of the control.

This is a method of internal API, which is a part of the web standard for custom elements.

Since: 1.14.0

willValidate

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

(static) instanceSymbol

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

Since: 1.15.0

Methods

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

Parameters:

Name	Type	Description
`attribute`
`callback`

Overrides: Monster.DOM.CustomElement#addAttributeObserver

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
Overrides: Monster.DOM.CustomElement#adoptedCallback

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:

Extracts the options from the attributes and the script tag of the element and sets them.
Initializes the shadow root and its CSS stylesheet (if specified).
Initializes the HTML content of the element.
Initializes the custom elements inside the shadow root and the slotted elements.
Attaches a mutation observer to observe changes to the attributes of the element.

Since: 1.8.0
Overrides: Monster.DOM.CustomElement#assembleMethodSymbol

Returns:

The updated custom element.

Type:: CustomElement

attachObserver(observer) → {CustomElement}

attach a new observer

Parameters:

Name	Type	Description
`observer`	Observer

Overrides: Monster.DOM.CustomElement#attachObserver

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:

Name	Type	Description
`attrName`	string
`oldVal`	string
`newVal`	string

Since: 1.15.0
Overrides: Monster.DOM.CustomElement#attributeChangedCallback

Returns:

Type:: void

callCallback(name, args) → {*}

Calls a callback function if it exists.

Parameters:

Name	Type	Description
`name`	string
`args`	*

Overrides: Monster.DOM.CustomElement#callCallback

Returns:

Type:: *

checkValidity() → {boolean}

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity

Throws:

NotSupportedError
Type
DOMException
the ElementInternals is not supported and a polyfill is necessary
Type
Error

Returns:

Type:: boolean

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
Overrides: Monster.DOM.CustomElement#connectedCallback
See: https://developer.mozilla.org/en-US/docs/Web/API/Element/connectedCallback

Returns:

Type:: void

containsObserver(observer) → {ProxyObserver}

Parameters:

Name	Type	Description
`observer`	Observer

Overrides: Monster.DOM.CustomElement#containsObserver

Returns:

Type:: ProxyObserver

detachObserver(observer) → {CustomElement}

detach a observer

Parameters:

Name	Type	Description
`observer`	Observer

Overrides: Monster.DOM.CustomElement#detachObserver

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
Overrides: Monster.DOM.CustomElement#disconnectedCallback

Returns:

Type:: void

formAssociatedCallback(form)

Sets the form attribute of the custom control to the id of the passed form element.

Sets the form attribute of the custom control to the id of the passed form element. If no form element is passed, removes the form attribute.

Parameters:

Name	Type	Description
`form`	HTMLFormElement	The form element to associate with the control

formDisabledCallback(disabled)

Sets or removes the disabled attribute of the custom control based on the passed value.

Parameters:

Name	Type	Description
`disabled`	boolean	Whether or not the control should be disabled

formResetCallback()

formStateRestoreCallback(state, mode)

Parameters:

Name	Type	Description
`state`	string
`mode`	string

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.

Overrides: Monster.DOM.CustomElement#getInternalUpdateCloneData

Returns:

Type:: *

getOption(path, defaultValue) → {*}

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

Parameters:

Name	Type	Description
`path`	string
`defaultValue`	*

Since: 1.10.0
Overrides: Monster.DOM.CustomElement#getOption

Returns:

Type:: *

hasNode(node) → {boolean}

Parameters:

Name	Type	Description
`node`	Node

Since: 1.19.0
Overrides: Monster.DOM.CustomElement#hasNode

Throws:

value is not an instance of
Type TypeError

Returns:

Type:: boolean

initMethodSymbol() → {CustomElement}

Is called once via the constructor

Since: 1.8.0
Overrides: Monster.DOM.CustomElement#initMethodSymbol

Returns:

Type:: CustomElement

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

Parameters:

Name	Type	Description
`attribute`

Overrides: Monster.DOM.CustomElement#removeAttributeObserver

Returns:

Type:: Monster.DOM.CustomElement

reportValidity() → {boolean}

This is a method of internal api

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity

Throws:

the ElementInternals is not supported and a polyfill is necessary
Type
Error
NotSupportedError
Type
DOMException

Returns:

Type:: boolean

setFormValue(value, state) → {undefined}

This is a method of internal api

// Use the control's name as the base name for submitted data
const n = this.getAttribute('name');
const entries = new FormData();
entries.append(n + '-first-name', this.firstName_);
entries.append(n + '-last-name', this.lastName_);
this.setFormValue(entries);

This is a method of internal api

// Use the control's name as the base name for submitted data
const n = this.getAttribute('name');
const entries = new FormData();
entries.append(n + '-first-name', this.firstName_);
entries.append(n + '-last-name', this.lastName_);
this.setFormValue(entries);

Parameters:

Name	Type	Description
`value`	File \| string \| FormData
`state`	File \| string \| FormData

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue

Throws:

NotSupportedError
Type
DOMException
the ElementInternals is not supported and a polyfill is necessary
Type
Error

Returns:

Type:: undefined

setOption(path, value) → {CustomElement}

Set option and inform elements

Parameters:

Name	Type	Description
`path`	string
`value`	*

Since: 1.14.0
Overrides: Monster.DOM.CustomElement#setOption

Returns:

Type:: CustomElement

setOptions(options) → {CustomElement}

Parameters:

Name	Type	Description
`options`	string \| object

Since: 1.15.0
Overrides: Monster.DOM.CustomElement#setOptions

Returns:

Type:: CustomElement

setValidity(flags, message, anchor) → {undefined}

Parameters:

Name	Type	Description
`flags`	object
`message`	string \| undefined
`anchor`	HTMLElement

Since: 1.14.0
See: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity

Throws:

NotSupportedError
Type
DOMException
the ElementInternals is not supported and a polyfill is necessary
Type
Error

Returns:

Type:: undefined

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.

Overrides: Monster.DOM.CustomElement#updateI18n

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
Overrides: Monster.DOM.CustomElement#updaterTransformerMethodsSymbol

Returns:

Type:: object

Example

[updaterTransformerMethodsSymbol]() {
   return {
      "my-transformer": (value) => {
          switch (typeof Wert) {
          case "string":
              return value + "!";
          case "Zahl":
              return value + 1;
          default:
              return value;
          }
   }
   };
 };