Monster.DOM. CustomControl

This is a base class for creating custom controls using the power of CustomElement.

After defining a CustomElement, the registerCustomElement method must be called with the new class name. Only then will the tag defined via the getTag method be made known to the DOM.

This control uses attachInternals() to integrate the control into a form. If the target environment does not support this method, the polyfill can be used.

You can create the object using the function document.createElement().

This control uses attachInternals() to integrate the control into a form. If the target environment does not support this method, the Polyfill for attachInternals() can be used: element-internals-polyfill.

Learn more about WICG Web Components: WICG Web Components.

Read the HTML specification for Custom Elements: Custom Elements.

Read the HTML specification for Custom Element Reactions: Custom Element Reactions.

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
License
  • AGPLv3
Throws:

the ElementInternals is not supported and a polyfill is necessary

Type
Error

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

form

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0

formAssociated

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

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

Since
  • 1.14.0

labels

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0

name

This is a method of internal api

.

This is a method of internal api

states

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0

type

This is a method of internal api

.

This is a method of internal api

validationMessage

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0

validity

This is a method of internal api

.

This is a method of internal api

value

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

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.

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

.

This is a method of internal api

Since
  • 1.14.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().

Since
  • 1.15.0

Methods

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

Parameters:
NameTypeDescription
attribute
callback

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

checkValidity() → {boolean}

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0
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
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

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:
NameTypeDescription
formHTMLFormElement

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.

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

Parameters:
NameTypeDescription
disabledboolean

Whether or not the control should be disabled

formResetCallback()

formStateRestoreCallback(state, mode)

Parameters:
NameTypeDescription
statestring
modestring

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

reportValidity() → {boolean}

This is a method of internal api

.

This is a method of internal api

Since
  • 1.14.0
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:
NameTypeDescription
valueFile | string | FormData
stateFile | string | FormData
Since
  • 1.14.0
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

.

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

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

Parameters:
NameTypeDescription
flagsobject
messagestring | undefined
anchorHTMLElement
Since
  • 1.14.0
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.

Throws:

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

Type
Error