Web Components in Aurelia

As stated in my last article, Web Components are a relative new way to build modern and reusable components. Even if the Web Components specifications are not implemented in some browsers like Firefox and Edge, there are ways to support them by using a polyfill. Aurelia itself is a single page application framework (SPA) which is based on the idea of Web Components. Some of you might ask: "Why do I need native Web Components when Aurelia provides the ability to use some of the main benefits out of the box?". The answer for this is pretty simple... Reusability

Since Web Components are native browser standards you can use them in general with any framework or library like Aurelia, Angular or even with React. This makes it easy for companies with multiple applications and frameworks to build components only once.

So how can we use Web Components in Aurelia?

In our example we will use one of the prepared aurelia skeletons ESNext + JSPM which you just can copy to have a ready to use project.

Important: The plugin aurelia-html-import-template-loader we will use later, just works with SystemJS.

Now we have a working Aurelia project and we can start with the integration. To ensure that all browsers can handle the Web Components in Aurelia, we have to install a Polyfill. For information about polyfills and how they work you can read more here.

To install the polyfill and the Aurelia HTML Imports loader with JSPM run:

Shell-Script

jspm install webcomponentsjs
jspm install aurelia-html-import-template-loader

Now we want to load the polyfill to ensure our Web Components can be loaded. But we don't just want to blindly load the polyfill because it introduces in the full minified version ~120kb of additional network traffic. To prevent this as much as we can, we gonna extend our index.html to check for the available browser features and conditionally load the polyfill. When the polyfill is ready or not needed an event WebComponentsReady is fired to start the bootstrapping of the Aurelia application.

HTML: index.html

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Aurelia</title>
<link rel="stylesheet" href="jspm_packages/npm/[email protected]/css/font-awesome.min.css">
<link rel="stylesheet" href="styles/styles.css">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body aurelia-app="main">
<div class="splash">
<div class="message">Aurelia Navigation Skeleton</div>
<i class="fa fa-spinner fa-spin"></i>
</div>
<script src="jspm_packages/system.js"></script>
<script src="config.js"></script>
<script>
var EVENT_NAME = 'WebComponentsReady';
window.addEventListener(EVENT_NAME, function wcReady() {
System.import('aurelia-bootstrapper');
});
var supports = [
('registerElement' in document), // Browser supports custom elements
('createShadowRoot' in Element.prototype), // Browser supports shadow root
('import' in document.createElement('link')) // Browser supports html imports
];
if (supports.indexOf(false) !== -1) {
System.normalize('webcomponents.js/webcomponents.js').then(function(path) {
var script = document.createElement('script');
script.src = path;
document.querySelector('head').appendChild(script);
});
}
else {
window.dispatchEvent(new Event(EVENT_NAME));
}
</script>
</body>
</html>

Alles anzeigen

Because Aurelia's default loader only would handle the template tag in an HTML file and ignore the script tag, we need the plugin aurelia-html-import-template-loader to work around this.

It will load the html files using HTML Imports feature and handle the script tag as well.

JavaScript: main.js

import 'bootstrap';
export function configure(aurelia) {
aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-html-import-template-loader');
aurelia.start().then(() => aurelia.setRoot());
}

Now we just need to require our Web Component in the Aurelia template and use it.

HTML: app.html

<template>
<require from="web-component.html"></require>
<web-component val.one-way="value" change.delegate="incrementValue()">
<button class="projected-content">Ok</button>
</web-component>
</template>

Now we're done and when you run gulp serve you should see the content of the component.

I would suggest everyone to pass data into with the one-way binding and handle changes via events which gives you a better and more understandable data flow.

If you want to test it by yourself I prepared the project and pushed it on GitHub.

Please feel free to comment or give constructive feedback on this

Teilen