wcb/README.md at bfacf84b455a6e700e21ceaada87df2bbb4539e4

ayo/wcb

2023-10-24 18:39:39 +02:00

6.8 KiB

Raw Blame History

>>> TL;DR: This provides a minimal vanilla JS base class that aims to reduce the complexity of creating reactive custom elements. See the Quick Start Example

Web Component Base

When you extend the WebComponent class for your component, you only have to define the template and properties. Any change in any property value will automatically cause just the component UI to render.

The result is a reactive UI on property changes.

Import via unpkg
Installation via npm
Usage
template vs render()
Prop access
Quick Start Example
Life-Cycle Hooks
1. onInit - the component is connected to the DOM, before view is initialized
2. afterViewInit - after the view is first initialized
3. onDestroy - the component is disconnected from the DOM
4. onChanges - every time an attribute value changes

Import via unpkg

Import using unpkg in your vanilla JS component. We will use this in the rest of our usage examples.

import WebComponent from "https://unpkg.com/web-component-base/index.js";

Installation via npm

Usable for projects using typescript, or with bundlers, or using import maps.

npm i web-component-base

Usage

In your component class:

// HelloWorld.mjs
import WebComponent from "https://unpkg.com/web-component-base/index.js";

class HelloWorld extends WebComponent {
  dataName = "World";
  emotion = "excited";

  static properties = ["data-name", "emotion"];

  get template() {
    return `
        <h1>Hello ${this.dataName}${this.emotion === "sad" ? ". 😭" : "! 🙌"}</h1>`;
  }
}

customElements.define('hello-world', HelloWorld);

In your HTML page:

<head>
  <script type="module" src="HelloWorld.mjs"></script>
</head>
<body>
  <hello-world name="Ayo" emotion="sad">
  <script>
      const helloWorld = document.querySelector('hello-world');

      setTimeout(() => {
        helloWorld.setAttribute('emotion', 'excited');
      }, 2500)
  </script>
</body>

The result is a reactive UI that updates on attribute changes:

UI showing feeling toward Web Components changing from SAD to EXCITED

`template` vs `render()`

This mental model attempts to reduce the cognitive complexity of authoring components:

The template is a read-only property (initialized with a get keyword) that represents how the component view is rendered.
There is a render() method that triggers a view render.
This render() method is automatically called under the hood every time an attribute value changed.
You can optionally call this render() method at any point to trigger a render if you need.

Prop Access

Attributes are generally in kebab-case. You can access attribute properties in two ways

Use the camelCase counterpart: this.myProp, which is automatically filled.
Or stick with kebab-case: this["my-prop"]

class HelloWorld extends WebComponent {
  static properties = ["my-prop"];

  get template() {
    return `
        <h1>Hello ${this.myProp}</h1>
        <h2>Hello ${this["my-prop"]}</h2>
    `;
  }
}

Quick Start Example

Here is an example of using a custom element in a single .html file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>WC Base Test</title>
    <script type="module">

      // import from unpkg
      import WebComponent from "https://unpkg.com/web-component-base/index.js";

      class HelloWorld extends WebComponent {
        static properties = ["data-name"];

        get template() {
          return `<h1>Hello ${this.dataName || 'World'}!</h1>`;
        }
      }

      customElements.define("hello-world", HelloWorld);

    </script>
  </head>
  <body>
    <hello-world data-name="Ayo"></hello-world>
    <script>
        const helloWorld = document.querySelector('hello-world');
        setTimeout(() => {
            helloWorld.setAttribute('data-name', 'Ayo zzzZzzz');
        }, 2500);
    </script>
  </body>
</html>

Life-Cycle Hooks

Define behavior when certain events in the component's life cycle is triggered by providing hook methods

onInit()

Triggered when the component is connected to the DOM
Best for setting up the component

import WebComponent from "https://unpkg.com/web-component-base/index.js";

class ClickableText extends WebComponent {
  // gets called when the component is used in an HTML document
  onInit() {
    this.onclick = () => console.log(">>> click!");
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

afterViewInit()

Triggered after the view is first initialized

class ClickableText extends WebComponent {
  // gets called when the component's innerHTML is first filled
  afterViewInit() {
    const footer = this.querySelector('footer');
    // do stuff to footer after view is initialized
  }

  get template() {
    return `<footer>Awesome site &copy; 2023</footer>`;
  }
}

onDestroy()

Triggered when the component is disconnected from the DOM
best for undoing any setup done in onInit()

import WebComponent from "https://unpkg.com/web-component-base/index.js";

class ClickableText extends WebComponent {
 
  clickCallback() {
    console.log(">>> click!");
  }

  onInit() {
    this.onclick = this.clickCallback;
  }

  onDestroy() {
    console.log(">>> removing event listener");
    this.removeEventListener("click", this.clickCallback);
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

onChanges()

Triggered when an attribute value changed

import WebComponent from "https://unpkg.com/web-component-base/index.js";

class ClickableText extends WebComponent {
  // gets called when an attribute value changes
  onChanges(changes) {
      const {property, previousValue, currentValue} = changes;
      console.log('>>> ', {property, previousValue, currentValue})
  }

  get template() {
    return `<span style="cursor:pointer">Click me!</span>`;
  }
}

6.8 KiB Raw Blame History