Sean Hunter - Blog

thoughts and code

Header Right

Main navigation

Content projection and templated lists in Aurelia

By Leave a Comment

As you may have read in one of my previous posts on using Aurelia’s Shadow DOM slots, I’m a big fan of using content projection to eliminate boilerplate code in component libraries. Shadow DOM slots allow you to create templated components which effectively allow you to create a blueprint high-level component which you can then project custom HTML into at various slots.

However, one drawback of slots is that they’re not supported inside of repeaters and other template controllers. This drawback is due to the way the standard is written, so we’re unlikely to see direct support for shadow DOM slots in repeaters anytime soon (unless or until the standard is modified to support this). Aurelia provides a workaround for this in the form of replaceable parts.

Replaceable parts allow you to define a replaceable attribute to indicate that a template has a replaceble part and the part attribute to indicate which part can be replaced. In the course of my investigation on this topic I found a really cool example of how you can create a templated list in Aurelia by creating a custom element which uses the processContent attribute to transform the template content into a replacement part. This allows the consumer of the templated element to use it without being aware that it is using the replaceable part API under the hood, leading to a much less intrusive developer experience for component consumers. In this blog post, we’ll implement a Bootstrap 4 list-group custom element which uses the replaceable part API to allow consumers to inject custom HTML for each list item. The custom HTML we’ll inject will be a pokemon custom element, which renders pokemon details such as name, image, and so on.


You can see this in action at this Gist.

Creating the list-group custom element

To begin, we’ll create a custom element which uses the processContent custom attribute to replace the custom element content, transforming it into a replaceable part. You’ll notice that we’re importing the {FEATURE} module from the aurelia-pal package to ensure that the <template> element exists (it doesn’t in IE). A cleaner way to do this would be to use the DOM.createTemplateElement introduced in the late August Aurelia release.The DOM.createTemplateElement method creates method polyfills this element type and creates one for you, returning a new element of type HTMLElement.

The processContent(processor: boolean | Function) decorator takes either a boolean (which can be used to tell the templating engine not to process the content of the template because you want to manage this yourself), or a function which can be used to process the content. In this case, we’re creating a makePartReplacementFromContent function which we’ll use to do the template transformation. This example custom element is taken pretty much verbatim from a Stack Overflow answer by Jeremy Danyow (the current owner of Aurelia’s binding engine).

list-group.js – (view-model)

Next, we need to create the corresponding HTML template for this custom element view-model. This is a basic Bootstrap 4 list-group, the secret sauce is this bit <template replaceable part="item-template">${defaultValue(item)}</template> which defines a replaceble template to be used for each list item. The part to be replaced is the item-template which as you’ll remember we referenced in the view-model. We’ve also defined a defaultValue method (passed by the consumer) which is used to specify a default value in case the consumer doesn’t include any element content ${defaultValue(item)}. We’ll use this to render the Pokemon’s name in the default case:

list-group.html – (view)

Creating the Pokemon custom element

For the custom element itself we’ll create an HTML only custom element <pokemon> which uses a surrogate behavior to create a model binding on the template element:

pokemon.html – (view)

Putting it all together

With the templated list-group custom element and the pokemon custom element defined we can now require both of these into the app.html root view. The list-group can either be templated (by injecting custom HTML into the <list-group> node), or non-templated (by specifying a function used to get the text representation of the item). It’s worth noting here that we could inject any HTML under the list-group element. For example we could do something like <h2>${item.name}</h2> to achieve a different effect.

app.html

In summary

You can use Aurelia’s content projection to create custom elements that feel just like native DOM elements and are flexible enough to use as blueprints to create more specific kinds of elements. Because of Aurelia’s extensibility, we were able to overcome what at first seemed a framework limitation by using the processContent attribute to override the default way that the templating engine processes template content. This is only one example of how you can override Aurelia’s default behavior. Using other decorators such as customElement, customAttribute, inlineView, and noView there is much more you can do.

5 techniques used by Aurelia to promote great code quality

By Leave a Comment

Let’s start with a fact: You can write great code in bad frameworks and terrible code in good frameworks. But, frameworks can do things to encourage certain styles of development that lead to better code quality. Some great examples of this are Angular’s adoption of RxJS to populate the UI with data asynchronously, or the UI state management patterns introduced by React and Redux which are now starting to filter into other frameworks. Many of the design choices made by the Aurelia core team when building framework help developers fall into the pit of success (a term coined by Rico Mariani in relation to language design). The techniques that I’ll cover in this post include Separation of Concerns, Dependency Injection & IOC, the Event Aggregator, Convention over Configuration, and modular design. Combine these techniques, and what you end up with is a framework that promotes the code quality attributes like reusability, testability, maintainability, and extensibility that we all want to see in our applications.

Separation of Concerns

In computer science, separation of concerns (SoC) is a design principle for separating a computer program into distinct sections, such that each section addresses a separate concern.
— Wikipedia

The concept of separation of concerns between your HTML file (which provides the structure of the page), your CSS file (which determines how the page looks), and your JavaScript (which determines how the page behaves) has been around in Web development for some time. The idea is that by splitting out these concerns and managing them separately, you should be able to work on any of these independently of the other. It also means that team members with the relevant skill set should be able to work on one piece of the picture without needing to know the in-depth details about the other pieces. For example, a developer should be able to put together the basic HTML structure and JavaScript behavior to then be styled by a team member with more of a focus on User Experience or Design.

Aurelia’s opinion on this is that that this concept of separation of concerns is no less important in the world of SPA development than it is in a more traditional server-centric web development approach. Aurelia achieves this by having a clearly defined view (an HTML template) and view-model (a JavaScript/Typescript file) as seen below.

Seperation of concerns in Aurelia

Building components in this way allows you to easily test the JavaScript view-model. Since it contains most (if not all) of the logic for the component you only have one place to test. Typically Aurelia view templates are kept clean and simple and can be covered with an end to end test instead. The HTML is then also easier to reason about and style, since it’s basically just a regular HTML file.

This approach gives you the maximum flexibility. You still have the option of having one person manage an entire vertical slice of the application – JavaScript, HTML, and CSS – but you also have the option of splitting these out if that’s the way you’d prefer to work within your team or company.

Dependency Injection / IoC

In software engineering, dependency injection is a technique whereby one object supplies the dependencies of another object
— Wikipedia

Traditionally, objects in a system are responsible for managing their own dependencies. This can become challenging as the application grows in scale, increasing the complexity of the relationships between these objects. Dependency injection simplifies this problem by moving the responsibility of creating objects away from the objects themselves and placing it in the hands of the dependency injection (DI) framework. This transition of responsibility is known as Inversion of Control (IoC). Typically, in an application using DI, an object declares which dependencies it requires (often as constructor parameters), and the DI framework provides the relevant implementation of these dependencies at run-time.

Aurelia uses Dependency Injection to simplify the way that components receive their dependencies. The simplest example of this is a JavaScript service class. Imagine the case where we have the app component wants to show greetings. To do this it brings in the greetings child-component using a require statement, as shown in the below example:

app.js – (main app view-model)

app.html – (main app view)

The view will require a greeter component, which it’ll then use to render greetings to the page.

Lifting the lid of the greeter component and looking down another level, we’ll see that the greeter component as an external dependency (the GreeterService class) which is actually responsible for retrieving the greeting to show to the user. In this case, the Aurelia framework will ask the DI container for an instance of the GreeterService class and inject it into the Greeter constructor. All injected instances in Aurelia are singleton by default within a given container where each component (such as a custom element or attribute) has its own container. It’s possible to override this convention if needed.

greeter.js

This greeter view-model would have a corresponding view greeter.html which simply renders the greetings to a list:

greeter.html

The greeting component uses a class called GreetingService to actually load the greetings, so let’s take a quick look at that to get the full picture:

greeting-service.js – (service class)

There are some major benefits of managing dependencies in this way including but not limited to the following:

  • Testability: It’s easier to swap out the implementation of the greeter service (which may, for example, be doing an HTTP call with a mock implementation of this service to quick and easy testing.
  • Another example of where I’ve found the Aurelia dependency injection system to be particularly useful is managing shared services like the Aurelia fetch client module (a simple but powerful abstraction over the Fetch API). By injecting this service into classes via the DI container it’s possible to configure common settings such as the base URL of the Web API and default headers that should be sent with each HTTP request in the app module once rather than configuring them separately in each service class.

To find out more about how Aurelia’s dependency injection system works, I’d recommend checking out this great page on the Aurelia docs authored by the Aurelia framework instigator Rob Eisenberg himself.

Event Aggregator

An Event Aggregator acts as a single source of events for many objects. It registers for all the events of the many objects allowing clients to register with just the aggregator.
— Martin Fowler

The Event Aggregator pattern is great for when you have a complex graph of objects that need to communicate with each other. Instead of each object needing a reference to every other object in the graph, you can centralize these connections in the Event Aggregator object, greatly reducing the level of coupling in the system.

How different does this use case sound from the component hierarchy present in Aurelia applications? Not much at all really, and hence it’s also a great solution for reducing coupling between components. In fact, the Aurelia core team had this idea and implemented this pattern in a framework module called the aurelia-event-aggregator.

The Aurelia Event Aggregator

To use the Aurelia event aggregator you simply import the EventAggregator class from the aurelia-event-aggregator package. If you’re using the Aurelia CLI as your project creation tool then this should be installed by default, if not then you can install this package using npm (npm install aurelia-event-aggregator). Once you’ve imported the event aggregator into a class in your application (typically a view-model) you can inject it using DI (which provides you with a shared instance). To demonstrate I’ve added the EventAggregator to the greeter view-model, to publish a greeting event whenever a user adds a new greeting to the list.

Event Aggregator

The EventAggregator class has three methods: publish, subscribe and subscribeOnce. To begin with, we’ll use the publish method, which we’ll pass the name of the event greeting-added and the data to be passed along with the event (the greeting). The name of the event is often described as a channel, because any event publisher publishing events with this name, will be passed through the Event Aggregator to any subscribers that are listening for events with this name, creating a virtual channel between the event publishers and subscribers.

greeter.js

For completeness, the view changes required to add greetings are as follows:

greeter.html

To make use of these messages published on the EventAggregator you need to use the second key method subscribe which takes the name of the channel you’re subscribing to greeting-added and a function to call when the event is received. One important thing to note here is that the subscribe method returns a subscription object which needs to be disposed of when you’re finished with it (for example when the user navigates away from a particular screen in the app), otherwise you’ll continue to receive zombie messages even when that screen is no longer active. This is not required on the subscribeOnce method since as the name suggests it will only listen for one message on the channel before closing up shop.

app.js – (main app view-model, EventAggregator added)

To read more about the Aurelia Event Aggregator, I’d recommend the article on the Aurelia Hub, and also just reading through the source code of the module itself. Like much of the Aurelia source code this module is simple, well structured, and easy to understand.

Convention over Configuration

Convention over configuration (also known as coding by convention) is a software design paradigm used by software frameworks that attempt to decrease the number of decisions that a developer using the framework is required to make without necessarily losing flexibility.
— Wikipedia

One aspect of Aurelia that differentiates it from similar frameworks is its use of conventions to minimize boilerplate code. Some of the conventions provided by the Aurelia framework include:

  • Custom element naming. To create a custom element, you create two files, one for the view, and one for the view-model. For example to create the <greeting> custom element you needed a JavaScript file greeting.js and a corresponding HTML template greeting.html. By convention creating a class named Greeting Aurelia will create a custom element for this class. You can also follow the {Name}CustomElement convention if you want to be more explicit with how this is named.
  • Databinding. Conventions are used extensively throughout Aurelia’s binding system. For example in the greeter component we used an input to allow the user to enter new greetings: <input value.bind="greeting"></input>. You’ll notice that we didn’t need to specify that this should be a two-way binding. By default, Aurelia has determined that this should be a two-way binding because we attached the binding expression to an input element. You can override these conventions if you need to. For example, if we for some reason wanted a one-way input binding we could use <input value.one-way="greeting"></input>. In that case, the value would be rendered into the input from the view-model, but no changes in the input would be reflected back into the view-model.
  • Custom attributes. Custom attributes allow you to create custom HTML attributes to augment the behavior of DOM elements. The convention for custom attribute class names is ${Name}CustomAttribute, which is then converted to kebab-case for use in HTML. For example, to add the ability to attach a tooltip to any HTML element, we could create a class TooltipCustomAttribute, which would have a name tooltip in the view (used like <button tooltip></button>. When you attach this attribute to an element in your view you instruct Aurelia to create a new instance of the class for the TooltipCustomAttribute. Again, this is handled for you via naming conventions so to avoid you needing to specify these mappings explicitly.

Modular approach

Modular programming is a software design technique that emphasizes separating the functionality of a program into independent, interchangeable modules, such that each contains everything necessary to execute only one aspect of the desired functionality.
— Wikipedia

The Aurelia framework consists of a small, light-weight core, combined with a suite of features provided by small well-defined modules. Some of the modules include:

  • The binding library, which implements Aurelia’s powerful data-binding system.
  • The template engine which supports custom elements, data-binding, view-slots, attached behaviors and more.
  • The dependency injection package, which provides an extensible DI container for JavaScript (which can work independently of the Aurelia framework
  • and much more

This means you can start an Aurelia project with the minimal set of packages (such as binding and templating), and bring in more as an when you need them. This has two major benefits: It keeps the framework footprint as small as possible, while at the same time making it easier for new team members to hit the ground running.

In summary

The Aurelia framework uses a number of techniques to encourage good code quality. Far from hindering development speed, these techniques (or framework design choices) actually improve development speed, by reducing boilerplate code, and adding simple patterns to solve common problems like dependency management and inter-component communication.

Web Components and Aurelia – The Shadow DOM

By 4 Comments

In this series we explore the Web Component APIs: HTML Imports, Custom elements, HTML Templates, and the Shadow DOM, seeing how each of these APIs can be used within the context of your Aurelia applications. In this installment, we’ll look at the features Aurelia provides, including content projection, DOM encapsulation, and layouts.

The Shadow DOM

Imagine the following scenario: You’ve found a third party control you wanted to drop into your page. The documentation for the component displays a nicely laid out control, with a color scheme that would fit perfectly into your application. With a feeling of anticipation, you eagerly install the component with NPM and include it into your page layout. Problem is, when you re-load the page you realize that that the styles of a different third party library happen to conflict with the component you’ve just added, pushing the margins and padding way off to the side of the site. If that wasn’t bad enough, as you start typing into the control you realize that none of the key-down events are registering because that same bad neighbor of a third party control happens to take control of this as-well.

Wouldn’t it be nice if we had a way of encapsulating each of the components that we included to ensure a predictable result when including them on your page? Further, if you put yourself in the shoes of the component author, wouldn’t it be nice if you could publish that component without facing the inevitable barrage of Github issues reporting the weird and wonderful ways that developers have found to break your beautiful component with the !important directives littered throughout their 10-year-old CMS?

In fact, we’re in luck. The Shadow DOM was introduced to solve these encapsulation problems. It provides a way of encapsulating parts of the DOM (known as DOM subtrees) from the main DOM tree. This allows you to create isolated components that you can drop into a page without worrying about styles or behavior being disrupted by styles or JavaScript included in the main page.

Vanilla Shadow DOM

You can use the Shadow DOM with the aid of some polyfills today by using the element.attachShadow method. You can see an example of this below, where we query for a #componentHost element and then attach a new subtree to it using the element.innerHtml method:

If we take this one step further and mix this with custom elements (which we saw in the previous post in this series), we’ll begin by declaring a simple empty info card template <template id="info-card>. This template takes a message as input which it will render into the template content. We’ll then hook into the createdCallback method, importing the info card node document.importNode(infoCard.content, true), creating a new shadowRoot node this.createShadowRoot() and attaching the new info-card node to the DOM using root.appendChild(infoCardInstance). Finally, we register the new custom element with the DOM using the customElements.define('x-info-card', XInfoCard) method:

If you load this in the browser you’ll notice that the custom element content has been injected under a Shadow root node, meaning that the contents are isolated from any styles applied to the light DOM (the regular DOM outside of the Shadow DOM sub-tree):

Anything inside the #shadowRoot DOM node is invisible to the light DOM. For example, if we attempted to access the <p>Hello World</p> node using jQuery we’d receive an empty node list in response. Also if we applied styles to the <p> tag using CSS in the parent document, our p tag in the x-info-card component would also be protected.

Shadow DOM Slots

Apart from isolation, there is another handy feature of the Shadow DOM called slots which allows you to define a placeholder in your component into which you can inject custom HTML. For example, we could define a header and body slot in the x-info-card template as follows:

You can then use these slots, projecting your own custom HTML fragments into each slot location. The following example shows how you could inject a header and body fragment into the info-card custom element:

With the addition of Shadow DOM slots to our example page, the resulting components now show the HTML fragments that we injected into the header and body slots. The resulting example looks like this:

The thing that I really like about Shadow DOM slots is the fact that they allow you to create custom elements that behave just like standard HTML elements, where you can add nested HTML below the root custom element node. This is very powerful, as it allows you to create reusable high-level components which you can then compose with more specific components. In the case of our info-card, we could potentially create an image-info-card which extends the basic info info-card but projects image related HTML into the content slots.

Using the Shadow DOM with Aurelia

Aurelia provides four main features that allow you to leverage the Shadow DOM in your projects: CSS as='scoped' require option, the useShadowDOM decorator, shadow DOM slots, and layouts.

Scoped CSS

CSS scoping in web components is a hot topic. There generally two requirements for scoped CSS:

  • Avoid styles from outside your component being applied to your component
  • Avoid styles from within your component leaking outside your component

The first requirement can be met in Aurelia by decorating your view-model (the JavaScript class that backs your view) using the @useShadowDOM decorator. You’ll see a demonstration of this soon. The second requirement can be met in two ways. The first way (shown in the below snippet) shows how you could achieve this goal by adding the as='scoped' option to your stylesheet’s require statement. The problem with this approach is that it relies on an API that is currently only supported in Firefox, so the current applications are limited.

The second way (and the simplest approach I’ve to date) for having styles only apply to your component (without the use of a CSS processor like Postcss) is to include the styles inline in your view. This is the approach we’ll take in our examples.

Using the Shadow DOM

Aurelia components are created by defining view, view-model pairs where the name of the view matches the name of the view-model (JavaScript class). To have an Aurelia component inject it contents inside a shadowRoot node all you need to do is add the @useShadowDOM decorator to the view-model class declaration. The view and view-model pair can be created as shown in the below code samples. What’s striking here is that the HTML template in this case is exactly the same with Aurelia as with vanilla web components. The view-model is also very close, but with some neat improvements to the JavaScript API to make it terser:

info-card.html (view)

info-card.js (view-model)

You can see this Aurelia Shadow DOM sample in action at this GistRun.

Shadow DOM Slots

Aurelia’s Shadow DOM slot syntax is identical to vanilla web components. Where Aurelia has an advantage, however, is that you can also use Aurelia’s light-weight data-binding syntax to bind content into the different slots. For example, to bind content into the header and body slots it’s a simple matter of using one-way string interpolation binding. For example, in the below sample root app.html view file we’ve used two info-card elements, and we’re binding the header and body content from the app.js view-model values ${card1Header}. These could just as easily come from a repeater if we wanted to render the cards in a list.

app.html – view file

For more information on the specifics of using DOM slots with Aurelia, I’d recommend checking out this great post by a fellow Australian Aurelia developer Dwayne Charrington https://ilikekillnerds.com/2017/07/checking-view-slot-defined-aurelia.

Layouts

Layouts allow you to define multiple top-level pages into which views in your application can be rendered. This allows you to lay out your user interface the way that best fits each page in your application. Within a layout, you can define swappable areas using Shadow DOM slots. A neat use case for layouts is to define a separate layout for a login page (which doesn’t necessarily need a navigation menu) than they layout you’d use for the main page which would include the nav bar and so on. Layouts are kind of a big topic, so we’ll cover them in a later blog post instead.

That just about wraps up the basics of using the Shadow DOM with Aurelia. In the next installment in this series, we’ll create a Bootstrap 4 info-card component with Aurelia which uses the Shadow DOM to project custom HTML fragments into different card areas. Stay tuned!

Aurelia and Web Components – HTML Templates and Custom Elements

By Leave a Comment

In this series we explore the Web Component APIs: HTML Imports, Custom elements, HTML Templates, and the Shadow DOM, seeing how each of these APIs can be used within the context of your Aurelia applications. In this installment, we’ll look at the features Aurelia provides around HTML templates and custom elements.

HTML Templates

Regardless of which SPA frameworks you use, one of the fundamental requirements involves taking a snippet of HTML (often called a template), injecting variable values, and then rendering it to the DOM. The method that I used to use for this back in the BackboneJS days was to create a JavaScript template:

This template would then be rendered by implementing a Backbone view, which looked the template up by ID using jQuery, and rendered it using the Underscore.js templating engine. This method (termed Overloading script) was pioneered by John Resig in his Micro Templating Utility back in 2008. This approach is actually great for the most part. Because as the script tag is set to display:none by default, nothing is rendered when the template is loaded. It doesn’t actually get rendered until we choose to do this with JavaScript – the browser doesn’t parse this script as content. Further, the template is inert – the browser doesn’t attempt to process the text as JavaScript because the type is set to something other than text/javascript. However, this approach does come with a downside. If you take user input and then use then directly set the .innerHTML using the rendered template combined with this input it can lead to XSS vulnerabilities. So long as you’re aware of these vulnerabilities it’s not a problem, but ideally, there would be a standard approach that circumvents it all together. You can find out more about the pros and cons of this template method on the HTML 5 Rocks – Template Tutorial.

HTML templates provide a standard way of creating snippets of markup that are not rendered when the page is loaded, but are instead loaded at run time with JavaScript. These work in much the same way as the Overloaded JavaScript approach but do not have the drawback of increasing the likelihood of developers introducing XSS vulnerabilities into your application. In the below example HTML page I show an <info-card> HTML snippet. An important thing to note here is that image in the snippet isn’t rendered when the page is loaded. Instead, we need to explicitly create an element for it and load it into the DOM. Using templates is as simple as declaring a new <template> element with some content:

After declaring the template element, we need to query it from the DOM document.querySelector('#info-card'), clone the node, creating a new copy of the DOM fragment from the template so that it can be included in the current document document.importNode(infoCard.content, true), and then append cloned node to the current document bodyElement.appendChild(infoCardInstance):

Using HTML Templates with Aurelia

Aurelia views are created using HTML templates. When the Aurelia framework loads it parses the template and creates a view instance which it then initializes with data-binding and so on. You can find out more about the Aurelia view initialization process in this great post by Jeremy Danyow on the Aurelia Hub. Aurelia adds templating features such as repeaters, one-way and two-way data-binding, binding behaviors, input validation and so on primarily through the use of custom HTML attributes. This keeps the view syntax as close to standard HTML as possible. The equivalent info card view template in Aurelia might look something like this:

The striking thing about the template syntax in the above example is how close it is to the vanilla web component template we saw earlier.

Custom elements

I was first introduced to the idea of custom elements with Angular 1 directives, which provided a way of declaring an HTML snippet (view) and linking it to a backing controller. Since then just about every SPA framework has implemented custom elements in some way shape or form. Custom elements extend the HTMLElement class and should be prefixed with an X. To refer back to the info-card template from earlier, if we wanted to implement this as a vanilla custom element we’d first need to create an XInfoCard class which derived from HTMLElement. It’s also possible to attributes on a custom element using the observedAttributes() method, and respond to changes by implementing the attributeChangedCallback in the custom attribute class:

You could then use the custom element as follows:

For various reasons (primarily performance), the Aurelia team chose to create a framework specific implementation of custom elements, rather than using the vanilla web components option. These custom elements are the bedrock of Aurelia’s component system. You create them by first implementing a view-model (for example info-card.js), which is analogous to the XInfoCard class in the vanilla web components example, and then creating the corresponding HTML view template. Instead of needing to implement custom callbacks to watch for attributes changing, Aurelia handles this by convention, as you’ll see in the below example:

info-card.js – the view-model

You then need to create the corresponding view file (which as we saw earlier is just a standard HTML template):

info-card.html – the view

You can use the custom element as follows:

<info-card message.bind="myMessage"></info-card>

This passes the message from a parent component down to the info-card component using one-way data-binding.

Whilst Aurelia doesn’t leverage vanilla custom elements under the hood, I think the trade-off is worth it. This design choice allows for the performance gains and an elegant development model.

This concludes the overview of how you can use Templates and Custom Elements in Aurelia. In the next post, we’ll the Shadow DOM, arguably the most important, and my favorite feature of web component API.

Web Components and Aurelia – HTML Imports

By Leave a Comment

In the last post in this series, we took a journey through some of the web component technologies that have been popular over the last 10 years. This post wrapped up by providing a brief introduction to the modern web component APIs and specifications, which I contend are the future of building reusable components for the web. In the next few posts in this series, we’ll look into how Aurelia uses several of the web component APIs to implement some interesting features like templated components (with Shadow DOM slots). We’ll also look at how Aurelia enables the use of vanilla and Polymer web components right within your Aurelia SPAs. In This post, we look at the first web component API supported by Aurelia, HTML Imports.

HTML Imports and the Require Statement

HTML Imports define a method for loading other HTML documents into a parent document. This is very useful in the context of web components when you begin to think of a page as nothing but a hierarchy of bite sized UI widgets composed together. The main benefits of HTML imports are as follows:

  • Web native loading system: Where there are many other mechanisms out there for achieving a similar result, HTML Imports are designed to be built into browsers going forward, which ideally will allow you to load components without the need for any third party dependencies. If you need a third party loader to load modules, then how do you load the loader? Just a thought.
  • Dependency Management: Dependent components are loaded in the order you expect. For example, if you import component google-map which imports say map then map should be loaded first to set up the dependencies. HTML imports provide these out of the box.
  • Native HTML parsing
  • De-duplication of dependencies: If you imagine a dependency graph where two parent components rely on the same child component, the child component will only be loaded once.

You can use HTML imports by adding a link rel="import" tag in the head of your page as shown in the below example where we import an info-card component into the page. One of the neat things about HTML imports is that you can include everything that the component needs inside the referenced HTML page. This provides consumers of your component with a straightforward way to bring it into your application:

For example, Google provides a Google maps Polymer component which makes it trivial to add Google maps to your website without the need for an IFrame. All that’s required is to include an HTML import statement to load the web component:

<link rel="import" href="google-map.html">

This is all well and good, but how does it apply to Aurelia? Like many subsystems within the Aurelia framework, Aurelia’s template loading system uses a plugin model. There is a base template loader called loader which defines the common template loading interface. Other loaders, including the text-template-loader, aurelia-webpack-loader and html-import-template-loader, each implement this standard interface, as shown in the below diagram:

Aurelia template loaders

As you can see, Aurelia supports an html-import-template-loader which is specifically designed to allow you to include vanilla and Polymer web components easily within your Aurelia applications. From the HTML import template loader source this loader works by creating a new link rel='import' element as we saw in the above google-map component example and asynchronously loads the target HTML component:

To use this loader within your Aurelia application it’s simply a matter of adding the plugin to Aurelia’s bootstrap process in the main.js file:

If you’re interested in learning more about using Polymer components this great guide on the Aurelia Hub, which takes you through a step by step process to add Polymer components to an Aurelia project with the aid of the aurelia-html-import-template-loader.

One caveat to all of this is that the future of HTML imports is uncertain at this point. While Polymer adopted HTML imports whole heartedly, it was pretty much the only mainstream framework to do so. As such, with version 3 of Polymer, Google has announced that they’re now moving towards ES6 modules as their preferred approach to template loading instead of HTML imports. Whilst this won’t have much of an impact on the Aurelia development story (due to Aurelia’s flexible plugin model for loading components) it does mean that it’s a space to watch in the near future.

Web Components, from 2007 to Today

By Leave a Comment

This post starts with a brief archeological retrospective on the component systems of the past 11 years to provide some perspective of where we are now, and what’s possible with modern web technologies compared to the recent past. The post starts in the pre-iPhone era of 2005 which I’ll dub 2005-BI (Before iPhone).

2005 (BI – Before iPhone)

When I started building websites back around the 2005 time frame, there were a few cutting-edge technologies that made it possible to create user interface widgets that could be created once and then dropped into any website to enhance the functionality. At the time, this collection of technologies consisted of Flash, Java Applets, and Silverlight. In 2005 these technologies were great. They closed the gap between what was possible in the browser natively, and what we as developers wanted to deliver to our end users on the web. Common use cases included things like video players or file upload controls. These technologies worked by providing a plugin model, where users would install an application on their PC (for example Adobe Flash), which would then plug into the browser. You could then create applications that ran within this sandboxed environment, where the creators of the plugin systems could establish APIs that filled the gaps that were missing in what the browser provided. To summarize, these technologies helped solve two problems:

  • Encapsulation: By the nature of the plugin model widgets created in these technologies were encapsulated from the rest of the page, meaning that styles and behavior from the rest of the page didn’t leak into the controls. This made it easy to drop a control created for one site into another and have it “just-work”.
  • Bridging the feature gap: Whilst it’s easy to forget in this day and age, back in the 2005-BI era there were things that you just couldn’t do with native browser technologies period. These technologies solved this problem by adding the features that were not supported by native browser APIs.

2007 – Now (AI – After iPhone)

Whilst these technologies were essential at the time, events have transpired between then and now that have made them just as extinct as the dinosaurs. Two key events leading to this include:

  • The advent of the smart phones and tablets (primarily the iPhone) which refused to enable plugins. This meant that an increasing segment of users couldn’t be reached using these technologies.
  • Browser technologies got better, much better. Among the changes we got ES2015+ and HTML5, which allowed us to build the kind of rich components in our web applications that previously were impossible with the browser APIs alone.

The wild west of web development

Whilst browser technologies have come along way over the past 15 years and helped solve the feature gap problem we had back in the 2007 (BI) era, up until quite recently we didn’t have a way of standard way of building encapsulated controls. Many libraries began to emerge at this point to solve big parts of the problem space. This led to more and more applications being built in pure web technologies. But until recently, if I wrote a control that I wanted to share with your website, without you making any changes to my control or your side, we’d have had a difficult time doing it.

Enter web components

Recently a new collection of technologies have evolved to help solve the problem of creating encapsulated components for the web. These technologies consist of four web specifications designed with the aim of making it easy to build encapsulated user interface blocks that you can write once, and drop into other websites, without modifying either the component block or the destination site.

These specifications are in the process of being implemented by the various browser vendors as APIs. The four specifications are as follows:

  • HTML Imports which allow you to load HTML documents into other HTML documents
  • The Shadow DOM which provides encapsulation of styles and markup. This is the key to creating components that you can seamlessly drop into any website. You can achieve some of the same benefits with IFrames, but while IFrames are targeted at loading external pages into your website and coincidentally provide encapsulation, the Shadow DOM is designed with encapsulation in mind, and as such has features targeted at this purpose.
  • HTML Templates which provide a way of including snippets of markup within a page which are not executed when the page loads. This means for example that if you include an image tag within an img tag it won’t be retrieved from the server and rendered until you choose to initiate the template using the JavaScript API.
  • Custom Elements provide the building blocks to create custom DOM elements that behave just like the DOM elements you use on a day to day basis in your web development projects. For example you could create an <info-card> </info-card> custom element with child nodes, styling, and custom events, that would behave just like an out of the box element like the <p> tag.

You can get a long way creating web components with vanilla HTML and JavaScript, along with a few polyfills to fill in the browser API gaps. In a previous post, I showed an outline of how to create a web component with vanilla JavaScript. This can be done and is in some ways a great choice for creating bite-sized, isolated web components. However, the vanilla approach does have some drawbacks when it comes to creating web components that live as a part of a larger application. Features such as data-binding and routing, which developers used to modern SPA frameworks have come to take for granted have not been implemented at the time of writing. For me there are two frameworks that stand out with regards to web components today:

  • PolymerJS was created by Google as a means of sanding down some of the rough edges of the current web component implementation. It’s light weight and provides some much needed syntactic sugar to the web component APIs. I think Polymer is a great choice for creating stand alone components that you need to be able to share between a potentially diverse set of websites. It adds features such as data-binding, and easy event management, creating a far smoother developer experience than you would see using the web component APIs directly. Google recently announced that they’ve re-built YouTube on PolymerJS, which if nothing else shows that a) it’s possible to build fantastic websites on web components with PolymerJS, and b) Google is invested in this project for the long term.
  • Aurelia is a single page application framework designed make it easy to build modern web applications. One of the things that continues to attract me to Aurelia is its interaction and support of the web component APIs. Aurelia applications use HTML templates, and HTML imports under the hood to implement some of the core frameworks features such as views, and template loading. Further, you can use the ShadowDOM in your Aurelia views to create components that feel like native DOM elements. Like most other modern frameworks such as Angular2, React, and VueJS you can also use polymer components within an Aurelia application. What differentiates Aurelia from Polymer is that whilst Aurelia supports the web components, it is also a fully fledged SPA framework, with features like routing, and layout management, pub-sub, and dependency injection which make it great for architecting larger scale applications.

This brings us through to the modern era, today, where we have an emerging web component specification and a set of APIs which browser vendors improve support for day by day. My prediction at this point in time is that web development frameworks with converge in some senses, adopting better support for the web component standards. I also expect that we’ll continue to see the same great amount of diversity in web frameworks that we see today where different development styles in each framework appeal to different developers. Some frameworks such as React have already started to diverge in more functional programming direction, where Aurelia and VueJS appeal to developers with an eye for simplicity. In the next post in this series, we’ll take a deeper look at how Aurelia leverages the web component APIs, and how you can use these APIs within an Aurelia project.

If you’re interested in learning more about Aurelia, check out the book.