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
the options attribute does not contain a valid json definition.
- Type
- Error
import {getDocumentTheme} from '@schukai/monster/source/dom/theme.mjs';
const theme = getDocumentTheme();
console.log(theme.getName());
// ↦ monster
Extends
Members
defaults
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.
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 | ||||||
delegatesFocus | Boolean | true | Specifies the behavior of the control with respect to focusability. When set to | ||||||
templates | Object | Specifies the templates used by the control. Properties
| |||||||
templateMapping | Object | Specifies the mapping of templates. |
- Since
- 1.8.0
(static) instanceSymbol
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}
Name | Type | Description |
---|---|---|
attribute | ||
callback |
adoptedCallback() → {void}
The custom element has been moved into a new document (e.g. someone called document.adoptNode(el)).
- Since
- 1.7.0
- Type:
- void
assembleMethodSymbol() → {CustomElement}
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
- The updated custom element.
- Type:
- CustomElement
attachObserver(observer) → {CustomElement}
attach a new observer
.attach a new observer
Name | Type | Description |
---|---|---|
observer | Observer |
- Type:
- CustomElement
attributeChangedCallback(attrName, oldVal, newVal) → {void}
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.
Name | Type | Description |
---|---|---|
attrName | string | |
oldVal | string | |
newVal | string |
- Since
- 1.15.0
- Type:
- void
callCallback(name, args) → {*}
Calls a callback function if it exists.
Name | Type | Description |
---|---|---|
name | string | |
args | * |
- Type:
- *
connectedCallback() → {void}
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
- Type:
- void
containsObserver(observer) → {ProxyObserver}
Name | Type | Description |
---|---|---|
observer | Observer |
- Type:
- ProxyObserver
detachObserver(observer) → {CustomElement}
detach a observer
.detach a observer
Name | Type | Description |
---|---|---|
observer | Observer |
- Type:
- CustomElement
disconnectedCallback() → {void}
Called every time the element is removed from the DOM. Useful for running clean up code.
- Since
- 1.7.0
- Type:
- void
getOption(path, defaultValue) → {*}
nested options can be specified by path a.b.c
nested options can be specified by path a.b.c
Name | Type | Description |
---|---|---|
path | string | |
defaultValue | * |
- Since
- 1.10.0
- Type:
- *
hasNode(node) → {boolean}
Name | Type | Description |
---|---|---|
node | Node |
- Since
- 1.19.0
value is not an instance of
- Type
- TypeError
- Type:
- boolean
initMethodSymbol() → {CustomElement}
Is called once via the constructor
.Is called once via the constructor
- Since
- 1.8.0
- Type:
- CustomElement
removeAttributeObserver(attribute) → {Monster.DOM.CustomElement}
Name | Type | Description |
---|---|---|
attribute |
setOption(path, value) → {CustomElement}
Set option and inform elements
.Set option and inform elements
Name | Type | Description |
---|---|---|
path | string | |
value | * |
- Since
- 1.14.0
- Type:
- CustomElement
setOptions(options) → {CustomElement}
Name | Type | Description |
---|---|---|
options | string | |
- Since
- 1.15.0
- Type:
- CustomElement
updateI18n() → {Monster.DOM.CustomElement}
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.
Cannot find element with translations. Add a translations object to the document.
- Type
- Error
(static) getCSSStyleSheet() → {CSSStyleSheet|Array.<CSSStyleSheet>|string|undefined}
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];
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}
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
This method must be overridden by the derived class.
- Type
- Error
The tag name associated with the custom element.
- Type:
- string