DEV Community: Tebin Raouf

Building Web Components 101 - Part 4

Tebin Raouf — Mon, 26 Sep 2022 04:52:56 +0000

Part 3 covers how to create custom attributes. Let's continue in this article on how to create custom events for our custom web components.

I will start with where we left off in Part 3. To access the source code in this article, you can clone the project at https://github.com/tebinraouf/learning-fast/tree/building-web-components-101-part-4

or you can use Stackblitz

stackblitz.com

We use attributes to send/pass data to the web component. Events are useful to get data or send data to the consumer of the web component so that they can use it to build application logic.

To create a custom event, there are two steps:

Identify the element in the web component template to receive the custom event.
Emit the event so that users can add the custom event and get any data.

Here, we want to add onClick to the h1 element so that every time we click, we send new data to the customer. In this case, when we click, we send back a new Albert Einstein quote. It's up to the user how to handle this new quote. In our example, we update the quote.

Steps in detail:

Update h1.template.ts and add an onClick event listener. In FAST, the syntax to add an event listener is @click="${x => x.handler()}" where @click is the event name, which is onClick, and x.handler() is the handler/controller on the element class, which will be defined in h1.ts where the custom element class is created.

import { html } from "@microsoft/fast-element";


export const template = html`
-    <h1 style="color: ${x => x.color}">
+    <h1 style="color: ${x => x.color}" @click="${x => x.handler()}">
        <slot></slot>
    </h1>

Update h1.ts to include a private method handler. This could be any name.

    private handler() {
        this.$emit('colorhandler')
    };

By doing so, now our web component consumer can add a custom event colorhandler to the web component like below:

We added an id to the custom element.

<tebin-h1 color="blue" id="blue-title">Albert Einstein</tebin-h1>

We then use addEventListener to add a custom event, which is named colorhandler.

    <script>
        document.getElementById("blue-title").addEventListener('colorhandler', function (e) {
//business logic
        });
    </script>

How to send data to the web element consumer?

In this example, we are randomly sending a new quote through our custom event colorhandler. To do so, when we emit the colorhandler, we send the data with it like below:

    private handler() {
        const quotes = ["We cannot solve our problems with the same thinking we used when we created them", "The true sign of intelligence is not knowledge but imagination.", "I have no special talent. I am only passionately curious.", "The only reason for time is so that everything doesn't happen at once.", "Only a life lived for others is a life worthwhile."];
        const random = Math.floor(Math.random() * quotes.length);

        this.$emit('colorhandler', quotes[random])
    };

The data can be anything. In this case, we send back a string.

Lastly, the web element consumer can get the quote through the event detail i.e. e.detail like below.

    <script>
        document.getElementById("blue-title").addEventListener('colorhandler', function (e) {
            document.getElementById("ae-quote").innerText = e.detail;
        });
    </script>

Now, every time someone clicks on the custom web element title, the description changes with a new quote.

Building Web Components 101 - Part 3

Tebin Raouf — Mon, 26 Sep 2022 02:52:15 +0000

In Part 2, I went through the fundamentals of FAST and created a custom component using FAST Element. In this article, I will explain how to create custom attributes in FAST.

I will start with where we left off in Part 2. To access the source code in this article, you can clone the project at https://github.com/tebinraouf/learning-fast/tree/building-web-components-101-part-3

or you can use Stackblitz

stackblitz.com

How to create a custom attribute?

In Part 2, we create a custom <tebin-h1> component where we hard coded the heading colour. In this article, we will create a custom attribute so that we can define the custom attribute value when the component is used.

Code:

<tebin-h1>Albert Einstein</tebin-h1>

Result:

By default, the title is brown since we defined it.

//h1.style.ts
import { css } from "@microsoft/fast-element";

export const styles = css`
    :host {
        display: block;
    }
    h1 {
        color: brown
    }
`;

We want to create a color attribute so that we can set it when the component is used like below:

<tebin-h1 color="yellow">Albert Einstein</tebin-h1>
<tebin-h1 color="#41aea9">Albert Einstein</tebin-h1>
<tebin-h1 color="blue">Albert Einstein</tebin-h1>

How to create custom attributes in FAST?

FAST offers @attr decorator to create attributes. Let's go through the steps required to use @attr decorator:

Create a property on the custom component class. In this case, the class for tebin-h1 component is defined in h1.ts.

import { FASTElement, attr } from "@microsoft/fast-element";
import { styles } from "./h1.style.js";
import { template } from "./h1.template.js";


export class H1Component extends FASTElement {
+    @attr color: string = 'brown'
}

export const h1component = H1Component.compose({
    name: "tebin-h1",
    template,
    styles,
});

By default the value is set to brown.

The next step is to update the template so that the value is set to the h1 tag. We are going to use inline style for this demo. However, you would normally use the the css tag or scss to style your components.

h1.template.ts now looks like the following:

import { html } from "@microsoft/fast-element";

export const template = html`
-    <h1>
+    <h1 style="color: ${x => x.color}">
        <slot></slot>
    </h1>
`;

FAST uses MVVM - Model-View-ViewModel pattern. Since we defined the color property on the class, which is the Model, then we can bind it on the view by using ${x => x.color}.

Lastly, we will delete the style that we defined in the h1.style.ts file.

import { css } from "@microsoft/fast-element";

export const styles = css`
    :host {
        display: block;
    }
-    h1 {
-        color: brown
-    }
`;

With only a few changes, our custom element now has a custom attribute.

Markup:

    <tebin-h1 color="yellow">Albert Einstein</tebin-h1>
    <p>Life is like riding a bicycle. To keep your balance, you must keep moving.</p>

    <tebin-h1 color="#41aea9">Albert Einstein</tebin-h1>
    <p>Life is like riding a bicycle. To keep your balance, you must keep moving.</p>

    <tebin-h1 color="blue">Albert Einstein</tebin-h1>
    <p>Life is like riding a bicycle. To keep your balance, you must keep moving.</p>

Result:

In the next article, we will talk about how to bind events in FAST.

Building Web Components 101 - Part 2

Tebin Raouf — Wed, 14 Sep 2022 05:53:37 +0000

In Part 1, I went through the basics of Web Components and the problem it solves. In this article, I will explore FAST to create Web Components or custom elements.

As I stated in Part 1, there is no need for abstraction layers, however, abstraction layers provide patterns and best practices for engineers to follow. Patterns and best practices take time to learn but they will speed up developments and they will help to make our code more readable by ourselves in the future or by anyone else.

What is FAST?

According to https://www.fast.design/, FAST is

The adaptive interface system for modern web experiences

Let's clarify that. FAST is a system to build web experiences which include custom elements, design systems, single page applications, or any other front end sites. With FAST, we get to follow some basic patterns to build components and sites that scale easily.

FAST as a system includes the following:

FAST Element: an extension of HTMLElement to create custom elements. This is a thin layer of abstraction to make it easier to create custom elements.
FAST Foundations: a set of style-less web components such as Modal, button, badge, etc.
FAST Toolings: a set of tools/CLI help scaffold component creations and design system creations.
FAST Integrations and Utilities: additional and optional libraries to add even more functionalities to the FAST system such as Routing, SSR, Animations, Colors, React wrapper, Blazer wrapper, and more.

How to build a component with FAST?

In Part 1, we built a custom brown <h1> tag and we named it <tebin-h1>. Let's build the same component with FAST.

To create a custom element, we will be using fast-element@v2.0.0-beta.4 package.

To go through how to build with FAST, I've setup a basic project with Webpack. In the spirit of using as much as possible from FAST, I used FAST's ToDo's example to start with. Kudos to FAST team for providing these examples.

You can find the repository here (https://github.com/tebinraouf/learning-fast/tree/building-web-components-101-part-2) to follow up with the rest of this article.

git clone https://github.com/tebinraouf/learning-fast.git
cd learning-fast
yarn or npm install
yarn build
yarn dev

or use Stackblitz for the project.

The project structure is as follows:

.
├── README.md
├── index.html
├── package.json
├── src
│   ├── components
│   │   └── h1
│   │       ├── h1.style.ts
│   │       ├── h1.template.ts
│   │       ├── h1.ts
│   │       └── index.ts
│   └── index.ts
├── tsconfig.json
└── webpack.config.cjs

Let's focus on the component directory. FAST breaks down component creation into 4 pieces:

Component styles, which are defined in *.style.ts file. In this case, h1.style.ts file.
Component template, which is defined in *.template.ts file. In this case, h1.template.ts file.
Component composition, which is defined in *.ts file. In this case, h1.ts file.
Component definition or registration, which is defined in index.ts file. In this case, h1/index.ts file.

Note: these 4 separate files are not required. You can combine all four into one single file, which could be difficult to maintain in a large project. These 4 different files provide clear separation of concern.

Let's dive deep into each part of the component:

h1.style.ts holds all the styles for your component. Out of the box, we can provide CSS as string or CSS through FAST's css tag like below:

import { css } from "@microsoft/fast-element";

export const styles = css`
    :host {
        display: block;
    }
    h1 {
        color: brown;
    }
`;

Or CSS as string

export const styles = `
    :host {
        display: block;
    }
    h1 {
        color: brown;
    }
`;

or with some configurations, you could use SASS. For future articles,

I will write about how to configure SASS for FAST. However, the idea is to convert SASS to CSS string, which can then be used by the FAST component directly.

h1.template.ts holds the template for the custom component. Out of the box, FAST provides html tag build templates like below:

import { html } from "@microsoft/fast-element";

export const template = html`
    <h1>
            <slot></slot>
    </h1>
`;

slot is an HTML element. It allows us to provide dynamic content or markup to our custom element. We can think of slot as placeholder.

If there is one slot in the template, this is considered as the default slot. Text or mark up can be used in place of a slot.

If there are more than one slot, we would need to name them to identify the slot. To get more details, you can navigate to MDN.

h1.ts is used to compose or combine the template and the style. We also define the custom component name, which will be used when the web component is used.

*.compose({}) returns the custom element definition, which we will use to register the component.

import { FASTElement } from "@microsoft/fast-element";
import { styles } from "./h1.style.js";
import { template } from "./h1.template.js";


export class H1Component extends FASTElement {

}

export const h1component = H1Component.compose({
    name: "tebin-h1", //the component will be used like <tebin-h1></tebin-h1>
    template,
    styles,
});

components/index.ts is used to define/register the component based on the component definition that we get from *.compose().

import { h1component } from './h1.js';

h1component.define();

Lastly, to use the custom component, we will add the custom element to index.html

<tebin-h1>Albert Einstein</tebin-h1>
<p>Life is like riding a bicycle. To keep your balance, you must keep moving.</p>

<tebin-h1>Pablo Picasso</tebin-h1>
<p>Everything you can imagine is real.</p>

DOM Element:

Result:

To learn more, FAST provides excellent documentations on their official site at https://www.fast.design/. I will encourage you to check it out.

Lastly, by following a few simple patterns and structure, we were able to create a FAST custom element with ease. This article allows us to talk about more advance topics in the future such as directives, observables, and states. In future articles, I will talk about these and other FAST offerings.

Building Web Components 101 - Part 1

Tebin Raouf — Sat, 10 Sep 2022 05:50:01 +0000

Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps. ~ MDN

Let's clarify what that really means. Currently, there are many ways to build re-usable components such as using React, Vue, Angular, etc... However, if a component is built with React, it does not work in Angular, though there are some libraries to make it work. However, natively React components do not work in Angular and vice versa. Web Components addresses this challenge.

Since Web Component is an HTML standard, it can be understood or rendered by the browser without any libraries.

To better understand this, let's look at a standard HTML tag such as

<h1>Cool Title</h1>

For libraries and frameworks to render <h1>, as developers we do not need to load any scripts. We expect the library and framework to simply build the page and the browser to simply render it.

In React, we could use an <h1> tag like below:

import * as React from 'react';
import './style.css';

export default function App() {
  return <h1>Cool Title</h1>;
}

In Angular, we could use an <h1> tag like below:

import { Component, Input } from '@angular/core';

@Component({
  selector: 'hello',
  template: `<h1>Cool Title</h1>`,
  styles: [`h1 { font-family: Lato; }`],
})
export class HelloComponent {
  @Input() name: string;
}

And a browser will render it because it understands HTML standard <h1> tag.

What if we were able to build our own tags such as <tebin-h1>, <fancy-h1> tags, etc...and tell the browser to render them exactly as it would render <h1>?

Using Web Components, we can build custom tags or elements and then inform the browser to render them. These custom tags are called Web Components.

Web Components are re-usable. The same way an <h1> tag is re-usable, a custom web component is also re-usable because it is natively supported by the browser.

Browser compatibility of Web Components and its different feature compatibility can be found here

Since Web Components are supported natively by browsers, they can be used in any libraries and frameworks either directly or with configurations. https://custom-elements-everywhere.com/ is a great site to check custom elements support status by different libraries and frameworks.

How to build Web Components

Since Web Components are natively supported by browsers, we technically can write vanilla HTML, JavaScript, and CSS to build our custom web component. Below is a complete index.html page to create a custom tag that I named <tebin-h1>. This custom <h1> tag has a brown colour by default.

<html lang="en">

<head>
    <title>Web Component 101 - Part 1</title>
</head>

<body>
    <h1>Quotes</h1>

    <tebin-h1>Albert Einstein</tebin-h1>
    <p>Life is like riding a bicycle. To keep your balance, you must keep moving.</p>

    <tebin-h1>Pablo Picasso</tebin-h1>
    <p>Everything you can imagine is real.</p>
</body>

<script>
    // Create a class for the element
    class CustomTebinH1 extends HTMLElement {
        constructor() {
            // Always call super first in constructor
            super();

            // Create a style tag
            const style = document.createElement('style');
            style.textContent = 'h1 {color: brown}';

            // Create an h1 tag
            const h1 = document.createElement('h1');
            h1.textContent = this.textContent;
            this.textContent = '';

            // Create a shadow root
            const shadow = this.attachShadow({ mode: 'open' });

            // Append it to the shadow root
            shadow.append(style, h1);
        }
    }

    // Define the new element
    customElements.define('tebin-h1', CustomTebinH1);
</script>

</html>

Result:

Let's break it down.

Usage: <tebin-h1></tebin-h1> we use custom elements or web components the same way we use standard HTML elements.
Build: There are two steps:

Step 1: Create a JavaScript class for the custom component functionality.
Step 2: Define or register the custom element so that the browser understands how to render the custom element. This is done using customElements.define('tebin-h1', CustomTebinH1);

Obviously, this is a very simple custom element. When we add more functionalities, our class becomes more complex. As engineers, we like to define patterns or follow best practices to build software. This is where abstraction layers become very useful and saves a lot of time.

There are already great libraries that provide abstractions and good patterns to speed up development some of these libraries are FAST, Lit, Custom Element Builder, etc...

In future posts, I will dive deep into FAST and how it helps to build custom elements FASTer.