Sean Hunter - Blog

thoughts and code

Header Right

Main navigation

How to create a country-picker Aurelia component

By Leave a Comment

Common advice I’ve come across when building apps using SPA frameworks is to avoid using jQuery and other direct DOM manipulation techniques in favor of letting the framework update the DOM as a result in changes in your models state. This is generally fantastic advice, and I try to follow it where possible in my own Aurelia projects. But, often situations arise where a third party library (even ghasp a jQuery plugin) already exists that perfectly fits the problem at hand. One of the problems that plugins like selectize and select2 solve well is enhancing the out of the box functionality of the select element to provide a better user experience with auto-complete and more. In this post, we’ll look at how you can create a country picker component by combining the jQuery based selectize control, along with a country flags library to create a country picker component in Aurelia.

This article will cover the following points:

  • Adding the selectize control into an Aurelia CLI project using NPm and requireJS
  • Plugging the selectize control into the Aurelia component life-cycle using the attached callback
  • Dynamically compiling Aurelia templates on the fly to render country select items

By the end of this post, we’ll have created a working country-picker control that allows users to pick their country from an auto-complete list. To make this list a little more user-friendly we’ll render the corresponding country flag associated with a given country code. You can see the end result in the below screengrab:

Aurelia country picker

You can see the custom element in action here.

Setting up the pre-requisites

note: This assumes you’ve already created an Aurelia project using the requireJS module loader. For information on getting started with the Aurelia CLI, check out this article on the Aurelia Hub.

To begin with we’ll need to install the three per-requisite packages via NPM: selectize, and flag-icon-css, and of course jquery:

With these installed, the next step is to modify the aurelia.json file as follows to ensure that the packages are bundled correctly into your Aurelia vendor-bundle.js file. In case you’ve not come across this yet, Aurelia CLI + requireJS projects create two bundles by default:

  • The app-bundle.js file which includes the view-models, view-templates and so on that make up your Aurelia project
  • The vendor-bundle.js file which includes the third party dependencies that your application relies on

You’ll notice that we’re modifying the dependencies section to include the new plugins. The selectize and flag-icon-css nodes include references to the css resources that should be bundled. This allows us to require them into our Aurelia view templates just like any other kind of view-resource, as you’ll see in a moment. For brevity, I’ve only included an excerpt with the relevant part of the file here. If you’re interested you can see the complete file here.

aurelia.json

With the bundling configured, most of our dependencies are now in place, but one more step remains. The flag icon files (used to render the country flag next to each country name) are referenced from the flag-icon.css file using relative paths like this url(../flags/4x3/ad.svg);, so we need to copy these files into that relative path from the root of the Aurelia application to have them load correctly. Fortunately, we can do this by modifying the build pipeline generated for us by the CLI. To do this we’ll create a new gulp task as shown below, and call it as a part of the build step. This file relies on input and output paths defined in the aurelia.json file above:

copy-flags.js

With this file in place, it can be included in the Aurelia build by modifying the build.js file as shown below:

build.js

With the dependencies in place, we can now get to the more fun part of creating the component. We’ll structure this by first creating a generic selectize component that takes an http-query used to pull a list of results back as a JSON blob, and render the results as select items using an Aurelia view template.

Creating the ux-selectize component

We’ll create the ux-selectize component as a custom attribute. One benefit of doing it this way rather than using a custom element is that the select element can remain pretty-well unchanged. By applying the custom attribute to the select element we can transform it into a selectize control, in a way that’s quite unobtrusive from perspective of the view template. Also, due to the way that selectize works, we’d need to know the custom element options up-front (passing them down from a parent view-model or using a static list), rather than fetching them dynamically as we are in this case, which rules out the option of using a custom element in this scenario.

There are a few interesting parts to note about this custom attribute. Firstly, we’re using the attached Aurelia component life-cycle call-back to initialize the jQuery component. This is the preferred life-cycle hook to perform DOM interaction as it occurs when a component is attached to the DOM. It’s also worth noting that we’re using unbind component life-cycle method to clean up the selectize control when the view is unbound.

The dynamicOptions decorator is used to add new bindable properties to the custom attribute at will without the need to declare them one-by-one. For performance reasons you may want to declare them individually if you have a well-known and controlled set of properties, you intend to bind against. Looking down further, we’ve Aureliarized the HTTP logic as well. Instead of using jQuery AJAX to fetch the country list from the remote server, we’re instead passing a function, which makes the call using the aurelia-fetch-client module (as you’ll see shortly). Finally, we’re hooking into the onChange selectize event and delegating it to the select element. This will allow us to listen for this event from the country-picker parent component and use the updated country value.

I’ll ask you to ignore the magic in the getHtml method at the bottom of the file for now, and we’ll circle back to that later.

ux-selectize.js

With this component in place, the next step is to create a country-picker custom element to encapsulate the selectize component, and provide the country-picking specific implementation details. This component imports the flag-icon, and selectize CSS files, and declares a new select element decorated with the ux-selectize custom attribute. The selectize attribute binding expression takes 6 parameters:

  • httpQuery : The method (declared on the country-picker view-model used to fetch the countries from the server)
  • selected : The currently selected country
  • templateUrl : The path to the country item template (relative path within the project)
  • valueField : The field on the country model to use as the select option value
  • searchField : The field on the country model to use as the lookup key
  • labelField : The field on the country model used for the select option label

We also specify an initial option to be used when the select component is initialized. This includes the selected country name and code:

<option value.bind="selected.code">${selected.name}</option>

Creating the country-picker component

country-picker.html (view)

The next step is to create the corresponding country-picker view-model. This defines the getCountries method used to fetch countries from the countries.json endpoint using the aurelia-fetch-client module. This list is filtered by the country name that the user types into the input element. To improve efficiency filtering logic would be better implemented on the server side to minimize the payload we need to pull back from the server.

We’re also listening for the countryChange event fired from the ux-selectize view-model in order to set our currently selected country.

country-picker.js (view-model)

..and the magic

I promised that we’d circle back to how the ux-selectize component renders its item templates, and now is the time. The selectize control has a render method which you can pass HTML that should be rendered for each select item. A simple implementation would have just been to return a string literal representing the HTML we wished to return, which would have looked something like this:

Even though this approach works fine, I generally prefer to keep my HTML templates as pure HTML, separated from the JavaScript files. I wanted to be able to create an item template at /templates/country-item.html, then have Aurelia’s binding engine take care of data-binding the item and creating the output HTML. It turns out that this is doable, with the help of Aurelia’s ViewEngine class.

First, let’s take a look at the template that we’ll use to render each of the country select items. This is a basic Aurelia view template which uses string interpolation binding to render country details to the view. I’ll not go into this in too much detail:

country-template.html

So how is this template used by the ux-selectize custom attribute? To begin with, we use the viewEngine to create a view factory given the template URL this.viewEngine.loadViewFactory(templateUrl). We do this up-front to avoid needing to repeat the process for every select item. Once we’ve got the view factory, we can use it to create a view instance const view = factory.create(childContainer); and bind the current select item using the view.bind method: view.bind(item);. To get the actual HTML of the view instance we need to attach it to a DOM element, which in our case is a wrapper div: let country = DOM.createElement("div"), view.appendNodesTo(country);. Finally, we can return the actual outerHTML of the element to be rendered.

I’ve glossed over the details of how the view engine process works under the hood here, since the main purpose is to give you the gist of what is happening. If you’re interested in reading more, I’d recommend this great article by Jeremy Gonzalez which I used as a reference when figuring this stuff out.

Put all of this together, and we have a re-usable country picker component, built on top of the jquery based selectize utility.

aurelia-country-picker

Nice! But, what have we learned?

It’s not advisable to go wholesale DOM manipulation and jQuery in an Aurelia project, as you start to get away from the benefits that Aurelia’s powerful templating and binding system gives you. But, sometimes there is an existing tool that solves your problem perfectly. In cases where this tool exists as an NPM package (and let’s be honest what doesn’t these days), it’s a simple matter of installing it into your Aurelia project, and making the relevant configuration tweaks to your aurelia.json file.

We also saw how you can use the dynamicOptions decorator to add bindable properties to your custom attributes at will, without the need to declare each property individually.

Finally, we saw that although Aurelia’s binding engine API can be daunting at first, it’s powerful when you get to understand a few of the building blocks. An example of one of these building blocks is the viewEngine.loadViewFactory method, used for creating view instances given a template URL. This gives you the flexibility of creating your own patterns when Aurelia’s default templating and binding approaches don’t quite fit what you need to do.

If you’re interested in seeing more implementation detail, the source code for the project is available on GitHub.

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 to serve as high-level blueprints into which you can project custom HTML at various extensibility points known as 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 replaceable part and the part attribute to indicate which part can be replaced. The general problem I’ve found with replaceable parts is that this implementation detail leaks out to the consumer of the component. Ideally I wanted a way to define templated parts which didn’t force any additional implementation details onto the component consumer. In the course of my investigation, I found a really cool example of how you can create a templated list in Aurelia by building 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 next API feature to learn about is the processContent(processor: boolean | Function) decorator, which 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 replaceable 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.