CustomControl

Overview

The CustomControl class in MonsterJS extends the CustomElement class, offering additional capabilities specific to form-associated custom elements. It leverages the ElementInternals API to integrate custom elements into HTML forms, enabling them to participate in form submission, validation, and other form-related behaviors.

Key Features

  • Form Association: Integrates custom elements with forms using attachInternals(), enabling them to behave like standard form elements.
  • Validation: Supports standard HTML validation mechanisms and custom validation logic through the ElementInternals API.
  • Value Handling: Provides a framework for getting and setting the value of the control, which is essential for form elements.
  • Form Lifecycle Callbacks: Reacts to form-related events like reset and restore, allowing for custom behavior in response to form interactions.

Methods and Properties

Constructor

Initializes the custom control, setting up internals for form association and observing attribute changes.

Lifecycle Callbacks

Inherits all lifecycle callbacks from CustomElement and introduces form-associated callbacks:

  • formAssociatedCallback(form): Invoked when the element is associated with a form.
  • formDisabledCallback(disabled): Invoked when the associated form’s disabled state changes.
  • formStateRestoreCallback(state, mode): Invoked during state restoration, such as when navigating back to a form with preserved state.
  • formResetCallback(): Invoked when the form is reset.

Form Integration

  • value: Gets or sets the value of the control. Must be overridden in derived classes.
  • labels: Provides access to associated label elements.
  • name: Reflects the name attribute, used for form submission.
  • type: Returns the type of control, typically the tag name.
  • validity: Returns the ValidityState object for the control, indicating its validation state.
  • validationMessage: Provides a localized message describing validation errors.
  • willValidate: Indicates whether the control will be validated.
  • form: References the associated form element.
  • setFormValue(value, state): Sets the value of the control for form submission.
  • setValidity(flags, message, anchor): Sets custom validity messages for the control.
  • checkValidity(): Checks whether the control satisfies its constraints.
  • reportValidity(): Displays the validation message to the user if the control is invalid.

Utility Methods

  • formAssociatedCallback(form): Associates or dissociates the control with a form.
  • formDisabledCallback(disabled): Enables or disables the control based on the form’s state.
  • formStateRestoreCallback(state, mode): Handles state restoration for the control.
  • formResetCallback(): Resets the control’s value during form reset.

Examples

Creating a new custom control:

class MyCustomControl extends CustomControl {
    static getTag() {
        return 'my-custom-control';
    }

    get value() {
        // Custom logic to retrieve the control's value
    }

    set value(value) {
        // Custom logic to set the control's value
    }
}

registerCustomElement(MyCustomControl);

Using the control in an HTML form:

<form>
    <my-custom-control name="myControl"></my-custom-control>
</form>

The CustomControl class empowers developers to create complex, form-associated custom elements, enhancing the capabilities of web forms with custom logic and behaviors.