CustomElement

Overview

The CustomElement class in MonsterJS is a foundational class for creating new HTML elements using the Web Components Custom Elements API. It enables developers to define new HTML tags with custom behavior and appearance, encapsulating functionality in a reusable component.

Key Features

Easy Element Creation: Create instances of custom elements using document.createElement() or by including the tag directly in HTML.
Lifecycle Callbacks: Utilize standard custom element lifecycle callbacks like connectedCallback, disconnectedCallback, etc., to manage the element’s lifecycle effectively.
Attribute Observers: Monitor changes to attributes and react accordingly using the attributeChangedCallback method.
Shadow DOM Support: Encapsulate your element’s styles and markup using the shadow DOM, with support for open and closed shadow modes.
Styling Integration: Integrate CSS styling directly into your custom elements, ensuring encapsulation and avoiding style leakage.
Event Handling: Define and handle custom events, making your element interactive and responsive to user actions.
Extensibility: Extend from HTMLElement to create complex controls with rich functionality.
Declarative Configuration: Configure elements declaratively using HTML attributes or programmatically via JavaScript.

Methods and Properties

Constructor

The constructor initializes the element, setting up options and the shadow root if necessary. It is not intended to be called directly but is triggered when an instance of the element is created.

Lifecycle Callbacks

connectedCallback(): Invoked when the element is added to the DOM.
disconnectedCallback(): Invoked when the element is removed from the DOM.
adoptedCallback(): Invoked when the element is moved to a new document.
attributeChangedCallback(attrName, oldVal, newVal): Invoked when one of the element’s attributes is changed.

Observers

addAttributeObserver(attribute, callback): Adds an observer for an attribute.
removeAttributeObserver(attribute): Removes an observer for an attribute.

Options Management

getOption(path, defaultValue): Retrieves an option value.
setOption(path, value): Sets an option value.
setOptions(options): Sets multiple options.

Update and Rendering

updateI18n(): Updates the internationalization labels for the element.
getInternalUpdateCloneData(): Returns a clone of the internal data for advanced manipulation.
[updaterPipeCallbacksSymbol](): Integrates custom functions with Element Updaters.

[updaterPipeCallbacksSymbol]()

To integrate custom functions with Element Updaters, a control must implement the [updaterPipeCallbacksSymbol] method. This method should return an object containing key-value pairs, where the key is a unique name for the callback, and the value is the function itself.

Example Implementation

Here’s an example of how you can define a custom function within a control using [updaterPipeCallbacksSymbol]:

class MyClass extends CustomElement {
    [updaterPipeCallbacksSymbol]() {
        return {
            "my-callback-doing": (value) => {
                switch (typeof value) {
                    case "string":
                        return value + "!";
                    case "number":
                        return value + 1;
                    default:
                        return value;
                }
            }
        }
    }
}

In this example, the my-callback-doing function checks the type of the input value and modifies it based on its type:

If the value is a string, it appends an exclamation mark.
If the value is a number, it increments the value by one.
For other types, it returns the value unmodified.

Using Custom Functions in Templates

Once you’ve defined your custom functions, you can invoke them in your control’s template using the call command within the data binding expression.

Template Integration Example

Here’s how you can incorporate the my-callback-doing function into a control’s template:

<div data-monster-replace="path:options | index:label | call:my-callback-doing" 
     part="option-label"></div>

In this template snippet, the data-monster-replace attribute is used to dynamically update the content of the <div>. The call:my-callback-doing part specifies that the my-callback-doing function should be applied to the value obtained from path:options | index:label.

Utility Methods

hasNode(node): Checks if a node is a child of the element.
callCallback(name, args): Calls a defined callback function.

Static Methods

getTag(): Returns the tag name for the element.
getCSSStyleSheet(): Returns the CSS styles for the element.

Examples

Creating a new custom element:

class MyElement extends CustomElement {
    static getTag() {
        return 'my-element';
    }

    connectedCallback() {
        super.connectedCallback();
        console.log('MyElement added to the page.');
    }
}

registerCustomElement(MyElement);

Using the element in HTML:

<my-element></my-element>

Monster Manual