Vue implements a complete process record of a single file component

Preface

Front-end developers who have learned about the vue.js framework may know about single-file components. Single file components in Vue.js allow all the content of a component to be defined in a single file. This is a very useful solution and has already been advocated in browser web pages. But unfortunately, since this concept was proposed in August 2017, there has been no progress so far, and it seems to be dying out. However, it is interesting and worthwhile to delve deeper into the topic and try to implement single-file components using existing technologies.

Single file components

Front-end developers who know the concept of "progressive enhancement" must have also heard of the concept of "layering". In components, there is also such a concept. In fact, every component has at least 3 layers, or even more: content/template, presentation, and behavior. Or to be conservative, each component will be divided into at least 3 files. For example, the file structure of a button component may be as follows:

Button/
|--Button.html
|--Button.css
|--Button.js

Layering in this way is equivalent to separation of technologies (content/template: use HTML, presentation: use CSS, behavior: use JavaScript). If no build tool is used for bundling, this means that the browser needs to get these 3 files. Therefore, an idea is: a technology that separates component codes without separating technologies (files) is urgently needed to solve this problem. This is what this article is about — single-file components.

In general, I am skeptical of “technology layering”. It comes from the fact that component layering is often abandoned as a way of getting around "technology layering", which are completely separate.

Back to the topic, implementing a button with a single-file component might look like this:

<template>
  <!-- Button.html contents go here. -->
</template>

<style>
  /* Button.css contents go here. */
</style>

<script>
  // Button.js contents go here.
</script>

You can see that this single-file component is very similar to the HTML document in the initial front-end development. It has its own style tag and script tag, but the presentation layer uses a template tag. Thanks to the simple approach, you get a powerful layered component (content/template: <template>, presentation: <style>, behavior: <script>) without having to use 3 separate files.

Basic Concepts

First, we create a global function loadComponent() to load the component.

window.loadComponent = (function() {
  function loadComponent( URL ) {}
  return loadComponent;
}());

The JavaScript module pattern is used here. It allows to define all necessary helper functions, but only exposes the loadComponent() function externally. Of course, this function is empty right now.

Later, we will create a <hello-world> component to display the following content.

Hello, world! My name is <given name>.

In addition, click on this component and a message pops up:

Don't touch me!

The component code is saved as a file HelloWorld.wc (here .wc stands for Web Component). The initial code is as follows:

<template>
  <div class="hello">
    <p>Hello, world! My name is <slot></slot>.</p>
  </div>
</template>
<style>
  div {
    background: red;
    border-radius: 30px;
    padding: 20px;
    font-size: 20px;
    text-align: center;
    width: 300px;
    margin: 0 auto;
  }
</style>
<script></script>

Currently, no behavior has been added to the component, only the template and styles have been defined. In the template, you can use common HTML tags, such as <div>. In addition, the <slot> element appears in the template to indicate that the component will implement shadow DOM. And by default, all styles and templates of this DOM itself are hidden in this DOM.

The way components are used in web pages is very simple.

<hello-world>Comandeer</hello-world>
<script src="loader.js"></script>
<script>
  loadComponent( 'HelloWorld.wc' );
</script>

Components can be used like standard custom elements. The only difference is that you need to load it before using the loadComponent() method (this method is placed in loader.js). The loadComponent() method does all the heavy lifting like fetching the component and registering it with customElements.define().

Now that you have understood all the concepts, it's time to get hands-on.

Simple loader

If you want to load files from external files, you need to use the universal ajax. But it’s 2020 now, and in most browsers, you can safely use the Fetch API.

function loadComponent( URL ) {
  return fetch( URL );
}

However, this only gets the file without doing any processing on it. The next thing to do is to convert the ajax return content into text, as follows:

function loadComponent( URL ) {
  return fetch( URL ).then( ( response ) => {
    return response.text();
  } );
}

Since the loadComponent() function returns the execution result of the fetch function, it is a Promise object. You can check in the then method whether the file (HelloWorld.wc) is actually loaded and whether it is converted to text:

The results are as follows:

In the Chrome browser, using the console() method, we can see that the content of HelloWorld.wc is converted to text and output, so it seems to work!

Parsing component content

However, simply outputting the text does not achieve our goal. Ultimately, it needs to be converted into DOM for display and can actually interact with the user.

In the browser environment, there is a very practical class DOMParser, which can be used to create a DOM parser. Instantiate a DOMParser class to get an object, which can be used to convert component text into DOM:

window.loadComponent = (function () {
    function loadComponent(URL) {
        return fetch(URL).then((response) => {
            return response.text();
        }).then((html) => {
            const parser = new DOMParser(); // 1
            return parser.parseFromString(html, 'text/html'); // 2
        });
    }
    return loadComponent;
}());

First, a DOMParser instance parser is created (1), and then this instance is used to convert the component content into DOM (2). It is worth noting that the HTML mode ('text/html') is used here. If you want your code to better conform to the JSX standard or the original Vue.js component, you can use XML mode ('text/XML'). However, in this case, the structure of the component itself needs to be changed (for example, adding a main element that can hold other elements).

This is the return result of the loadComponent() function, which is a DOM tree.

In the Chrome browser, console.log() outputs the parsed HelloWorld.wc file, which is a DOM tree.

Note that the parser.parseFromString method automatically adds <html>, <head>, and <body> tag elements to the component. This is due to how the HTML parser works. The algorithm for building the DOM tree is described in detail in the HTML LS specification. This is a long article and will take some time to read, but the simple understanding is that the parser will default to putting all content in the <head> element until it encounters a DOM element that can only be placed inside a <body> tag. Therefore, all elements in the component code (<element>, <style>, <script>) are allowed to be placed in <head>. If you wrap a <p> element inside a <template>, the parser will put it inside the <body>.

There is another problem. After the component is parsed, there is no <!DOCTYPE html> declaration, so this is an abnormal HTML document, so the browser will use a method called quirks mode to render this HTML document. Fortunately, it doesn't have any negative effects here, because the DOM parser is only used here to split the component into appropriate parts.

After we have the DOM tree, we can extract only the part we need.

return fetch(URL).then((response) => {
    return response.text();
}).then((html) => {
    const parser = new DOMParser();
    const document = parser.parseFromString(html, 'text/html');
    const head = document.head;
    const template = head.querySelector('template');
    const style = head.querySelector('style');
    const script = head.querySelector('script');

    return {
        template,
        style,
        script
    };
});

Finally, let's organize the code. The loadComponent method is as follows.

window.loadComponent = (function () {
    function fetchAndParse(URL) {
        return fetch(URL).then((response) => {
            return response.text();
        }).then((html) => {
            const parser = new DOMParser();
            const document = parser.parseFromString(html, 'text/html');
            const head = document.head;
            const template = head.querySelector('template');
            const style = head.querySelector('style');
            const script = head.querySelector('script');

            return {
                template,
                style,
                script
            };
        });
    }

    function loadComponent(URL) {
        return fetchAndParse(URL);
    }

    return loadComponent;
}());

The Fetch API is not the only way to get component code from external files. XMLHttpRequest has a dedicated document mode that allows you to skip the entire parsing step. But XMLHttpRequest does not return a Promise, so you need to wrap it yourself.

Registering Components

Now that we have a component layer, we can create a registerComponent() method to register new custom components.

window.loadComponent = (function () {
    function fetchAndParse(URL) {
        […]
    }
    function registerComponent() {
    }
    function loadComponent(URL) {
        return fetchAndParse(URL).then(registerComponent);
    }
    return loadComponent;
}());

It should be noted that the custom component must be a class that inherits from HTMLElement. Additionally, each component will use a shadow DOM for storing styles and template content. So every time this component is referenced, it has the same style. Here’s how:

function registerComponent({template, style, script}) {
    class UnityComponent extends HTMLElement {
        connectedCallback() {
            this._upcast();
        }

        _upcast() {
            const shadow = this.attachShadow({mode: 'open'});
            shadow.appendChild(style.cloneNode(true));
            shadow.appendChild(document.importNode(template.content, true));
        }
    }
}

The UnityComponent class should be created inside the registerComponent() method because this class will use the parameters passed to registerComponent(). This class implements Shadow DOM using a slightly modified mechanism that I describe in detail in this article about Shadow DOM (in Polish).

Now there’s only one thing left to register the component: give the single-file component a name and add it to the DOM of the current page.

function registerComponent({ template, style, script }) {
  class UnityComponent extends HTMLElement {
    [...]
  }

  return customElements.define( 'hello-world', UnityComponent );
}

Now you can open it and take a look, as follows:

In Chrome, this button component has a red rectangle with the text: Hello, world! My name is Comandeer.

Get the script content

Now a simple button component has been implemented. Now comes the hard part, adding the behavior layer and customizing the content inside the button. In the above steps, we should use the content passed into the button instead of hard-coding the text content in the button in the component code. Similarly, we also need to handle event listeners bound within components. Here we use a convention similar to Vue.js, as follows:

<template>
  […]
</template>

<style>
  […]
</style>

<script>
  export default { // 1
    name: 'hello-world', // 2
    onClick() { // 3
      alert( `Don't touch me!` );
    }
  }
</script>

You can assume that the content inside a <script> tag within a component is a JavaScript module that exports content (1). The object exported by a module contains the name of the component (2) and an event listener method that starts with "on.." (3).

This looks neat, and nothing is exposed outside the module (because modules are not in the global scope in JavaScript). There is a problem here: there is no standard for handling objects exported from internal modules (those defined directly in the HTML document). The import statement assumes that a module identifier is obtained and imports according to this identifier. The most common is from a URL path to a file containing code. A component is not a js file and does not have such an identifier. The internal module does not have such an identifier.

Before you surrender, there's a super dirty hack you can use. There are at least two ways for a browser to treat a piece of text as if it were a file: Data URI and Object URI. There are also some suggestions to use Service Worker. But it seems a bit overkill here.

Data URI and Object URI

Data URI is an old, primitive method. It is based on converting the file contents into a URL, removing unnecessary spaces, and then encoding everything using Base64. Suppose there is a JavaScript file with the following content:

export default true; 

Converted to Data URI as follows:

data:application/javascript;base64,ZXhwb3J0IGRlZmF1bHQgdHJ1ZTs= 

You can then import this URI just like you would import a file:

import test from 'data:application/javascript;base64,ZXhwb3J0IGRlZmF1bHQgdHJ1ZTs=';
console.log( test ); 

An obvious disadvantage of the Data URI approach is that as the content of the JavaScript file increases, the length of the URL will become very long. Also, putting binary data in a Data URI is very difficult.

So, now there is a new kind of Object URI. It is derived from several standards, including the File API and the <video> and <audio> tags in HTML5. The purpose of Object URIs is simple: create a "pseudo-file" from given binary data, given a unique URI in the current context. To put it simply, it creates a file with a unique name in memory. Object URI has all the advantages of Data URI (a way to create a "file"), but without its disadvantages (it doesn't matter even if the file is 100M).

Object URIs are typically created from multimedia streams (such as in <video> or <audio> contexts) or from files sent via input [type=file] and drag-and-drop mechanisms. You can also use the File and Blob classes to create them manually. In this example, we use Bolb to first put the content in a module and then convert it into an Object URI:

const myJSFile = new Blob( [ 'export default true;' ], { type: 'application/javascript' } );
const myJSURL = URL.createObjectURL( myJSFile );

console.log( myJSURL ); // blob:https://blog.comandeer.pl/8e8fbd73-5505-470d-a797-dfb06ca71333 

Dynamic Import

There is one problem, though: the import statement does not accept variables as module identifiers. This means that apart from converting a module into a "file" using this method, there is no way to import it. Is there still no solution?

Not necessarily. This problem has been raised a long time ago and can be solved using a dynamic import mechanism. It is part of the ES2020 standard and has been implemented in Firefox, Safari, and Node.js 13.x. Using a variable as an identifier for a module to be dynamically imported is no longer a problem:

const myJSFile = new Blob( [ 'export default true;' ], { type: 'application/javascript' } );
const myJSURL = URL.createObjectURL( myJSFile );

import( myJSURL ).then( ( module ) => {
  console.log( module.default ); // true
});

As you can see from the above code, the import() command can be used like a method. It returns a Promise object, and the module object is obtained in the then method. Its default attribute contains all the exported objects defined in the module.

accomplish

Now that we have the idea, we can start implementing it. Add a tool method, getSetting(). Call it before the registerComponents() method to get all the information from the script code.

function getSettings({ template, style, script }) {
  return {
    template,
    style,
    script
  };
}
[...]
function loadComponent( URL ) {
  return fetchAndParse( URL ).then( getSettings ).then( registerComponent );
}

Now, this method returns all the parameters passed in. According to the logic described above, convert the script code into Object URI:

const jsFile = new Blob( [ script.textContent ], { type: 'application/javascript' } );
const jsURL = URL.createObjectURL( jsFile ); 

Next, use import to load the module, returning the name of the template, style, and component:

return import( jsURL ).then( ( module ) => {
  return {
    name: module.default.name,
    template,
    style
  }
} );

Because of this, registerComponent() still gets 3 arguments, but now it gets the name instead of the script. The correct code is as follows:

function registerComponent({ template, style, name }) {
  class UnityComponent extends HTMLElement {
    [...]
  }

  return customElements.define( name, UnityComponent );
}

Behavioral Layer

The component has one last layer left: the behavior layer, which is used to handle events. Now we just get the name of the component in the getSettings() method, and we also need to get the event listener. It can be obtained using the Object.entrie() method. Add the appropriate code to the getSettings() method:

function getSettings({ template, style, script }) {
  [...]

  function getListeners( settings ) { // 1
    const listeners = {};

    Object.entries( settings ).forEach( ( [ setting, value ] ) => { // 3
      if ( setting.startsWith( 'on' ) ) { // 4
        listeners[ setting[ 2 ].toLowerCase() + setting.substr( 3 ) ] = value; // 5
      }
    } );

    return listeners;
  }

  return import( jsURL ).then( ( module ) => {
    const listeners = getListeners( module.default ); // 2

    return {
      name: module.default.name,
      listeners, // 6
      template,
      style
    }
  } );
}

Now the method becomes a little more complicated. A new function getListeners() (1) has been added, which passes the module's output into this parameter.

Then use the Object.entries() (3) method to iterate over the exported modules. If the current attribute starts with "on" (4), it means it is a listening function. Add the value of this node (listening function) to the listeners object and use setting[2].toLowerCase()+setting.substr(3) (5) to get the key value.

The key value is formed by removing the leading "on" and converting the first letter of the following "Click" to lowercase (that is, getting click as the key value from onClick). Then pass in the isteners object (6).

You can use the [].reduce() method instead of the [].forEach() method, so that you can omit the listeners variable, as follows:

function getListeners( settings ) {
  return Object.entries( settings ).reduce( ( listeners, [ setting, value ] ) => {
    if ( setting.startsWith( 'on' ) ) {
      listeners[ setting[ 2 ].toLowerCase() + setting.substr( 3 ) ] = value;
    }

    return listeners;
  }, {} );
}

Now, you can bind the listener to the class inside the component:

function registerComponent({ template, style, name, listeners }) { // 1
  class UnityComponent extends HTMLElement {
    connectedCallback() {
      this._upcast();
      this._attachListeners(); // 2
    }
    [...]
    _attachListeners() {
      Object.entries( listeners ).forEach( ( [ event, listener ] ) => { // 3
        this.addEventListener( event, listener, false ); // 4
      } );
    }
  }
  return customElements.define( name, UnityComponent );
}

A parameter is added to the listeners method (1), and a new method _attachListeners() is added to the class (2). Here we can use Object.entries() again to iterate over the listeners (3) and bind them to the element (4).

Finally, clicking on the component will pop up “Don't touch me!” as shown below:

Compatibility issues and other issues

As you can see, in order to implement this single-file component, most of the work revolves around how to support basic Form. Many parts use dirty hacks (using Object URI to load modules in ES, which is meaningless without browser support). Fortunately, all the techniques work fine in major browsers, including Chrome, Firefox, and Safari.

Nevertheless, it was fun to create a project like this, which would allow you to work with many browser technologies and the latest web standards.

Finally, the code for this project is available online.

Summarize

This is the end of this article about implementing a single-file component in Vue. For more relevant Vue single-file component content, please search for previous articles on 123WORDPRESS.COM or continue to browse the following related articles. I hope everyone will support 123WORDPRESS.COM in the future!