Skip links

Sean Hunter - Blog

thoughts and code

Header Right

Main navigation

Aurelia CLI – Do we really need it?

By Leave a Comment

I’m from a background in ASP.NET. Like me, anyone from a .NET background is familiar with what some may now call a failed experiment from Microsoft: WebForms. It was a cold January day in 2002 when Microsoft introduced WebForms to the .NET community. This was a time where Vb6, Distributed COM, C++ were still a common choice toolset amongst developers. Now, when you can stop cringing for long enough to read on, WebForms was a great idea at the time. If you’re not familiar with it, the Visual Studio IDE had a drag-drop interface where you could drop UI widgets like Data-Grids on the form, click a few options to connect it to a SQLServer database, hit F5, and Boom! Fully functional CRUD web-app. This was a technology designed to bring Visual Basic developers writing windows forms applications to the Web, by making the learning curve as simple as possible (ie making the experience exactly the same as developing Windows forms applications).

Then down the line you want a designer to make some change , you go and inspect that page source only to be greeted with something like this:

You don’t have to understand that code to see that it’s a dog’s breakfast. It’s going to cause issues like performance (huge page bloat), and difficulties in bringing people like designers on the team to make changes. The motivation was good, but with the benefit of hindsight, the implementation was wrong.

So, now whenever I hear of a development environment enhancement that will save developers time getting started, and shield them from the need to learn the nitty gritty aspects of a technology, I approach said technology with a healthy dose of scepticism. I had this mindset approaching the Aurelia-CLI. But I’ve also learned over time not to diss it before I’ve tried it. So I decided to spend some time with the CLI to see what it’s like to use in practice.

The first thing that I noticed about the Aurelia-CLI is that it aims to solve a different problem than the WebForms example from above. It doesn’t try to write your application for you, but instead solves the a problem that many new developers have when getting started with any of the newer SPA Frameworks: The Front end Build Pipeline.

When I was initially learning Aurelia I was overwhelmed by the sheer concept count required just to get hello world up and running, but that concept count wasn’t in actually building the applications, it was in setting up the dependencies, and the Shell of the application.

You can install the Aurelia CLI with this command:

npm install aurelia-cli -g

Once you’ve got it installed you can spin up a new application by running this command and then stepping through the prompts:

au new

What this really does for you:

  • Installs all of your NPM dependencies.
  • Provides a set of pre-baked Gulp tasks that the Aurelia CLI can run for you in order to things like build and run the app.
  • Sets up an initial set of application bundles that make sense, so that you can continue by amending this list rather than trying to learn the structure from scratch.
  • Puts in place an initial directory structure for you.
  • Creates your index.html, app.js model, and app.html view so that when you run the project you’re starting from a known working state that you can then experiment with.
    Sets up the RequireJS module loader.

The common thread between all of the items I’ve listed is that they are done rarely.

These tasks are only completed at the start of a project, which has two implications:

  • If you were doing this manually you’d be doing it so rarely that you’d most likely forget and need to look at the documentation again next time anyway.
  • You may have somebody in your team that can specialize in these aspects so that the entire team doesn’t need to get bogged down in them.

What the Aurelia-CLI really does is take you down the happy path for getting started with an Aurelia application, by giving you a project structure and build-pipeline designed by people who actually know what on earth they’re doing with this stuff.

Yes, I agree this stuff is not rocket science, and it’s definitely helpful to know how all of it works under the hood. I would even recommend setting a few projects up from scratch as a learning exercise so when you inevitably need to modify the build pipeline or bundle configuration you are not completely lost. But these tools and techniques are also not core to your application. In the same way that we are happy to let the garbage collector deal with memory management for us, perhaps we can lean on the CLI for the same reasons. They let us get on with the important work of building our actual applications rather than Yak Shaving.

I’ve found the experience working with the CLI to be surprisingly pleasant. The project structure and build pipeline are clean, and probably better than what I would have come up with on my own anyway. This is not Web-Forms, the problem that it is solving is one that is useful to solve, and it’s been implemented in the right way.

Side note

If you’re interested in getting started with the Aurelia CLI there is a great guide available in the Aurelia docs Hub.

Inter-Component Communication with Aurelia

By Leave a Comment

Inter-Component Communication

Aurelia is a next generation JavaScript framework. One of the aspects that makes it a next generation framework is it’s emphasis on building applications from bite sized re-usable components (similar in that sense to React and Angular2). Components are created in Aurelia by building a View and View-Model pair, where the view is a standards compliant HTML template and the ViewModel is an ES-Next or Typescript file. By convention the view and view-model have the same filename (without extension).

Building applications in a component oriented manner yields many benefits. It allows developers to think about only one piece of the user interface at a time, improves testability, allows for greater reusability without additional effort, and more. Web-Components are the Micro-Services of front-end web development.

The natural result of building an application in this style is a large number of small components that need to communicate and work together to deliver the end-user experience. In order to make these components work together cleanly it is important to determine a pattern (or collection of patterns) for how inter-component coordination should be structured.

In order to do this, I find it helpful to ask the following questions:

– Who own’s a particular piece of data?
– Who’s responsibility is it to persist changes in data to the back end?
– Who needs to know when a piece of data changes?

Answering these questions helps determine how the communication should be structured, and which tools and techniques should be used. Aurelia provides many tools and techniques to allow web components to communicate, and as with anything in software development there is no one correct answer. The best choice depends on the complexity of the problem you are trying to solve, which is determined in large part by the finding answers to the above questions.

I’ll summarise some of the tools and techniques that Aurelia provides, and explain in what might indicate that a particular option should be selected.

Data-Binding

Aurelia’s Data-Binding system allows for data to be passed from a view-model to a view (in the case of a one way data-binding), and back again (in the case of a two-way data-binding). Data-binding really shines in simple situations such as:

View-Model to View

Set a property on the view-model to be read by the view.

Read the property in the view with Aurelia’s string interpolation and render it into the h1 tag.

A less obvious way of using Aurelia’s data-binding system is to pass data down from a parent-component to a child component as shown in the following diagram:

Data-Binding
Data-Binding

We can do this by turning our hello view + view-model into a greeter CustomElement (the primary option for creating web-components with Aurelia):

We declare a property on the root view-model called parentGreeting, again setting it in the constructor. We then bind this property to the property greeting on the child view-model:

For this simple example the one-way data-binding from the parent down to the child worked perfectly. It was simple to set up, low concept count, and low lines of code. This pattern can be utilised to pass data down through the view heir-achy from parent to child. Any changes made in the parent will filter down to the children. There are two key area’s where this falls short though if we look to extend the application:

– What if we don’t always want the value from the parent to directly filter down to the children? For example we only want children to receive the update on a certain event such as hitting the save button.
– How do we notify the parent component that a value has changed in the child?
– If a value is updated in the child, should it save the value to the data-store/web-api itself? How does the parent find out that it needs to re-fetch the state from the web-api and re-render itself?

These questions indicate that we’ve hit the limitations of what data-binding can offer, and we need to reach for a more advanced tool in order to fulfil these requirements.

Enter the EventAggregator.

Event Aggregator

An Event Aggregator is a simple element of indirection. In its simplest form you have it register with all the source objects you are interested in, and have all target objects register with the Event Aggregator. The Event Aggregator responds to any event from a source object by propagating that event to the target objects.

— Martin Fowler

In Aurelia this effectively means that the parent component registers for messages that the child-components publish, and if needed child components listen to messages from parents.

This looks something like the diagram below:

EventAggregator
EventAggregator

In a more complex application you would have many components each subscribing to key messages published from other components.

For example in a messaging application you might have a messageComposer, messageList and a messageBell component:

Messaging app
Messaging App

When new message composition is complete, a new-message event should be published to the EventAggregator. The messageBell and messageList components can then subscribe to this event and respond appropriately:

Using the EventAggregator provides more flexibility in the way that data is passed between components. It makes the message passing explicit, rather than implicit. This in turns makes it clear exactly who owns a particular state change. Components can make the decision what to do when an event occurs, rather than having the parent component decide it on their behalf.

So if the messageComposer is responsible for creating a new message, does it also have the responsibility of storing that message? What if something else needs to be done with the message before it is sent down to the back-end? At this point the natural extension of the above pattern is to move to an architecture called Data-Down, Actions Up which originated in the Ember.js community, which in turn was influenced by the Flux/Redux Uni-Directional Data-Flow pattern from React.

Data-Down Actions-Up

Data-Down, Actions Up is an a simple rule of thumb for how to structure communication in complex component based applications. Data is passed down from a parent component to the child components (similar to what we saw in the first data-binding example). Actions (EventAggregator Events in the Aurelia world) are then passed back up to the parent so that a decision can be made:

Data-Down Actions-Up
Data-Down Actions-Up

Extending our messaging application example from above, we can follow this rule of thumb by creating a new root level component called messages. This component is responsible for fetching the message list from the web-api, and persisting any changes back:

This component would pass the data down to it’s child components using one-way data-binding, and the child components would pass actions such as new-message up so that any required state changes could be persisted. Taking it one step further, the communication network could be simplified by subscribing to all actions/events from message related child components. That way the messaging component becomes a coordinator. All child messaging components talk to it via the EventAggregator, but don’t talk to each-other.

The next logical step would be implementing true uni-directional data-flow with something like Redux. It’s all about the complexity threshold, keep things simple until you find hit a wall, then look for a more advanced tool to solve tool to move forward.

Summary

Component oriented development is the future of large scale client side JavaScript. Structuring applications in this way brings a number of benefits. However it is important to decide on an explicit strategy for managing state changes between these components. If this is not done it is likely that the application will become un-maintainable as the lines between these components blur. This would negate most of the benefits of adopting this approach in the first place. Data-Binding and the EventAggregator can be combined in a number of ways in order to implement explicit messaging patterns within component based Aurelia applications.

Building Web Components – The Shadow DOM

By Leave a Comment

Overview

The ShadowDOM is one of the four web standards that when combined together allow us to build Web Components. From the specification, it is a:

method of combining multiple DOM trees into one hierarchy and how these trees interact with each other within a document, thus enabling better composition of the DOM.

At it’s most basic, the Shadow DOM provides a way of creating DOM fragments that that can be injected into parts of the main DOM, but are isolated from changes made in the parent DOM.

Example (the range element)

Browser vendors have utilised the Shadow DOM for some time now with element types such as range and date. When you create an input with a type of date, a hidden shadow DOM fragment is associated with your input element. If you view the source of the element you won’t see any of the DOM elements associated with this by default:

2016-05-30_13-01-35

With Chrome you can look to see what the browser is doing under the hood by enabling the user agent shadow DOM setting:

2016-05-30_13-04-02

The next time you view the source you should see that your input element actually contains a shadow root that hosts the range Shadow Tree:

2016-05-30_13-08-11

Special syntax can be used to style elements within a Shadow Tree. By default any styling applied to the hosting document does not apply to the Shadow Tree, and visa-versa. This will resolve a world of pain for component vendors who need to make their control work with a huge number of different sites.

Basic Usage

In the following example we’ll combine the Shadow DOM with a Custom Element in order to create a simple user-profile badge component:

2016-05-30_12-19-00

Firstly, we create a custom element object based on the DOM Element Prototype. We then set up a hook into a callback that will be fired when the custom element is registered.

There are four callbacks available:

  • createdCallback: Called when an element is registered.
  • attachedCallback: Called when an element is inserted into the DOM.
  • DetachedCallback: Called when an element is removed from the DOM.
  • attributeChangedCallback: Called when an attribute on an element is changed, added or removed.

For now, the only one that we need to worry about is the createdCallback. We hook into this callback, create the Shadow Root which is the host element. In this case we immediately set the innerHTML of this element. This is a fairly crude example. Realistically you would use the power of templates and HTML Imports to shift all of this HTML and CSS code into a more sensible location.

The last thing that we need to do is register the element. Which will in turn fire the callback that we created above. This lets the browse know about the element that we’ve defined, so that it will appropriately interpret the element’s usage in the corresponding HTML file. One important thing to note at this point is that custom elements must contain a ‘–‘ character in the name. This caught me out initially.

With this in place we can consume the element in our HTML file:

Which in turn renders the expected user profile element:

2016-05-30_12-19-00

2016-05-30_13-50-15

We now have everything associated with our custom element self contained within it’s own shadow root. In a way it looks like we’ve got our own mini DOM inside of our main HTML document, which is pretty close conceptually speaking to what is actually happening.

In Summary

The ShadowDOM is one of the four pillars of Web Components. Component authors can use this in combination with custom elements to define what kind of interactions should be allowed between the host website and the component both in terms of the JavaScript behaviour and more importantly the CSS styles.

The sample code for this blog post is available on Github.

Web Components 101

By Leave a Comment

We’ve always had the concept of components on the web. Historically they’ve taken a number of different shapes and sizes. Vendors have attempted to create component models in the past with the likes of Flash, Silverlight, Java applets, and any number of vendor specific plugins for server side frameworks such as ASP.NET Web Forms. These previous approaches to component based web development have met with varying degrees of success. In a lot of ways systems like Flash made it very easy to create sandboxed plugins that could be created once and dropped into any number of sites. There were however a number of problems with these plugin based systems:

  • The plugins ran within a particular sandbox (Flash/Silverlight) etc. This meant that users needed to have this particular sandbox installed on their PC In order to actually run the plugin, and needed to deal with software updates etc.
  • They were developed using a number of vendor specific toolkits, meaning that there was no standard way of developing components across these different frameworks.

The latest generation of this idea of web components comes in the form offour new standard web specifications:

  • Custom Elements: A way of creating new user defined DOM elements that the browser knows how to render natively.
  • HTML Imports: Standard method for including and reusing additional external HTML resources as a part of an HTML document.
  • Templates: This is a new element that allows a block of HTML to be declared which can then be cloned by script and inserted into an HTML document. In the past this has been done by using the script element with a type of text/template.
  • Shadow DOM: The Shadow DOM is a way of separating the contents of a document from the presentation. For example, this is how browser vendors implement such features as the date input type. From a DOM perspective the only thing presented is the input element, but behind the scenes behaviour is added using the Shadow DOM.

These standards come together to create a new method for building web components that all browsers will (eventually) understand natively. This solves both of the problems highlighted above. Any of these features can be used independently of one another, and some modern Single Page Application frameworks are starting to do just this.

While these four standards provide the building blocks for web components, implementing them with these parts from scratch requires a lot of boilerplate code, and is generally not recommended. As a result of this, a number of projects have spun up in order to improve and streamline the development process:

  1. Polymer JS: The most popular framework for building web components at this point in time is PolymerJS. Polymer has a nice declarative syntax for building components, and provides many features out of the box such as data-binding and easy component life-cycle callbacks
  2. X-Tag: A small light weight framework for creating web components that was originally developed by Firefox but has since been taken over by Microsoft. While the footprint is low for the actual framework itself, the additional boilerplate that goes into building a component with X-Tag makes it somewhat less appealing.

Modern JavaScript Single Page Application frameworks are being built with web components in mind, this means that going forward, we should be able to use our tool of choice (such as Aurelia, Angular2, React etc) to build the components, then export them as standard chunks of functionality to be dropped into websites via a simple import statement.

Another interesting resource in this space is the Polymer Web Component Catalogue which provides a kind of app store that allows web components to be easily discovered, and installed via a package manager such as Bower.

In Summary

Web components are made up of a set of four web standards. These standards can be utilised together using frameworks such as Polymer JS to build standard widgets that can be dropped into any site. This is going to be a really interesting way of delivering and sharing all sorts of functionality going forward.

Searchable tables with Aurelia Value Converters

By

When I first started looking at Aurelia one thing which appeared to be missing at first glance was the ability to easily apply filtering to a table. Fortunately we can implement this with minimal effort using Aurelia Value converters.

Aurelia Value Converters

Aurelia Value Converters are a class responsible for taking the data in the view-model and making it suitable for presentation in the view. The most basic example of this is a date filter. Instead of manually formatting the date in the view-model and storing it in a different property for presentation, or applying a format function in the view itself, we can pipe the date through a value converter to have it display in the format we want.

For example (example sourced from the Aurelia Blog):

This code is importing the momentjs library. It then provides a hook function called toView which translates the value piped into the value converter into a string formatted presentation suitable for the view. What I didn’t realise when I initially looked into value converters was how flexible they are. This flexibility allows us to do a lot more interesting things than simple formatting.

We’ll now build a filterable table using Bootstrap styling with value converters.

Firstly we’ll get the most basic thing on the page rendering by stamping out each of the raw todo items in a table:

Basic todo list table
Basic todo list table

Cleaning up the table

There are a number of improvements that we can make to this table, but let’s start by a adding value converter. We’ll apply a date format value converter to the created at column to improve readability. We’ll also add a class binding expression, and a check-box to allow us to toggle complete/incomplete items, and quickly view which items are complete:

2016-02-14_14-45-32

Adding the table filter

Once we reach a certain todo-list size it becomes convenient to be able to quickly filter the list based on the text of the todo items. We can achieve this with the introduction of another value converter:

This value converter takes two parameters:

  • searchTerm: The view-model property we wish to filter the table by.
  • filterFunc: The comparison function used to determine whether a particular row matches the given search criteria.

We’ll also need to make some adjustments to our view-model to support filtering:

And make the corresponding adjustments in our view to take advantage of the new value-converter:

In Summary

With very little effort we’ve been able to implement a generic filter pipe that we can use to filter client side data in a table (albeit a very naive one). Value Converters can also be used to implement sorting, paging etc, and are a vital part of the Aurelia tool-box.