Welcome to the magical world of Javascript development. This guide is for any newcomer to front-end development who isn't that experienced with modern tooling or Javascript frameworks.

Getting started

For the purposes of this tutorial and as a general rule for any modern framework like Aurelia, you will be using a terminal of some sort. On Windows, this can be the Command Prompt or Powershell. On macOS, it'll be Terminal (or any other Terminal alternative), the same thing with Linux.

To work with Aurelia, you will need to install Node.js. If you are new to Node.js, it is used by almost every tool in the front-end ecosystem now, from Webpack to other niche bundlers and tools. It underpins the front-end ecosystem.

The easiest way to install Node.js is from the official website here. Download the installer for your operating system and then follow the prompts.

Download a code editor

To write code, you need an editor that will help you. The most popular choice for Javascript development is Visual Studio Code. It is a completely free and open-source code editor made by Microsoft, which has great support for Aurelia applications and Node.js.

Create a new Aurelia project

We will be following the instructions in the Quick install guide to bootstrap a new Aurelia application. After installing Node.js, that's it. You don't need to install anything else to create a new Aurelia application, here's how we do it.

Open up a Terminal/Command Prompt window and run the following:

npx makes aurelia

You are going to be presented with a few options when you run this command. Don't worry, we'll go through each screen step by step.

Step 1. Name your project

You will be asked to enter a name for your project, this can be anything you want. If you can't think of a name just enter my-app and then hit enter.

Step 2. Choose your options

In step 2 you will be presented with three options.

• Option one: "Default ESNext Aurelia 2 App" this is a basic Aurelia 2 Javascript application using Babel for transpiling and Webpack for the bundler.

• Option two: "Default Typescript Aurelia 2 App" this is a basic Aurelia 2 TypeScript application with Webpack for the bundler.

• Option three: "Custom Aurelia 2 App" no defaults, you choose everything.

In this guide, we are going to go with the most straightforward option, option #1.

Step 3. Install the dependencies

You are going to be asked if you want to install the Npm dependencies and the answer is yes. For this guide we are using Npm, so select option #2.

Depending on your internet connection speed, this can take a while.

Step 4. Run the sample app

After the installation is finished you should see a little block of text with the heading, "Get Started" follow the instructions. Firstly, cd my-app to go into the directory where we installed our app. Then run npm start to run our example app.

Your web browser should open automatically and point to http://localhost:9000

Any changes you make to the files in the src directory of your app will cause the dev server to refresh the page with your new changes. Edit my-app.html and save it to see the browser update. Cool!

Building your app

In the last section we created a new application and ran the development server, but in the "real world" you will build and deploy your site for production.

Run the Npm build command by running the following in your Terminal or Command Prompt window:

npm run build

This will build your application for production and create a new folder called dist.

In our hello world example we touched upon some very basic and light Aurelia concepts. The most important of those is the view/view-model relationship. However, please note that you can write Aurelia applications in a wide variety of different ways, including custom elements without view models.

It is highly recommended that you have a read through additional sections in the "Getting Started" section to become familiar with the templating syntax, building components with bindable properties, looping through collections and more.

Once you are familiar with Aurelia's templating syntax and conventions, you will discover that you end up applying these templating basics to every app that you build.

If you followed along with our tutorial, you would now have a functional hello world application. The application will function like the one below. Typing into the text input field should dynamically display the value you entered.

There are various ways that you can set up an Aurelia project, including everything from adding a simple script tag to your HTML page to creating a custom configuration. One of the easiest and most powerful ways to get started is by using

Before you run makes, you will need a recent version of Node.js installed on your machine. If you do not have Node.js, you can Please ensure that Node.js is up-to-date if you already have it installed.

Next, using , a tool distributed with Node.js, we'll create a new Aurelia app. Open a command prompt and run the following command:

makes will then start the Aurelia project wizard, asking you a few questions to help you get things set up properly. When prompted, give your project the name "hello-world" and then select a default setup, either ESNext (Javascript) or TypeScript, depending on your preference. Finally, choose "yes" to install the project dependencies.

You have now created a hello world app without writing a single line code, well done. However, we'll be updating our app to allow for text input so we can make it say, "Hello" to whoever we want in the next section.

You now have an Aurelia setup ready for you to run, debug, or deploy. To ensure that everything is working properly, cd into your project folder and run npm start. Your project will then build and a web browser will open, displaying the message "Hello World".

Congratulations! 🎊 You just ran your first Aurelia app. Now, let's get building.

Introduction

Aurelia was designed to make building web applications and rich UI's easy. Living by the mantra of; Simple, Powerful and Unobtrusive, you have everything you need right out of the box to start building feature-rich web applications.

This section aims to give you a brief technical overview of how Aurelia works, but it is not intended to be a tutorial or reference. If you are looking for a nice gentle introduction to Aurelia that will only take a few minutes of your time the is a great place to start.

Core concepts

The core concepts of Aurelia are simple; HTML, CSS and Javascript. While Aurelia does introduce its own templating language you will need to become familiar with, it is enhanced HTML, so the syntax and concepts will feel familiar to you already.

View models and views

Underpinning Aurelia is the view-model and view convention. Out-of-the-box, Aurelia assumes that your components are made up of both a view model (.js or .ts file) as well as an accompanying view with a .html file extension.

If you have worked with .NET or other frameworks that use similar concepts, the view-model and view paradigm will be familiar with you. The view-model contains the business logic and data, the view is responsible for displaying it.

Like all concepts in Aurelia, these are default conventions and can be changed as needed.

Dependency injection

Much like other fully-featured Javascript frameworks and once again, .NET, Aurelia features a robust dependency injection system that allows you to manage your in-app dependencies. You will learn about the benefits of dependency injection in other parts of the documentation, but it plays a fundamental part in Aurelia.

Install node.js

To create new Aurelia applications using the Aurelia CLI via Makes, you will need to ensure you have Node.js installed. The latest version of Node is always recommended and preferable. While Node can be installed through different methods, the easiest is to obtain a distributable from the .

Create an app

Aurelia does not require you to install any global Node packages, instead of using the scaffolding tool, new Aurelia applications can be generated by running the following command.

You will then be presented with the Aurelia CLI screen which will first ask for a project name, then guide you through some options. The fastest way to get started is by choosing either the ESNext or TypeScript default options (1 and 2).

We highly recommend choosing TypeScript for any new Aurelia applications. With TypeScript you get the benefits of intellisense and type safety.

Run the app

Once the CLI process is finished and you have installed the dependencies for your new app, run npm start in the project directory, a browser window will open up with the new Aurelia application you just generated running.

Ready to dive deeper?

Take a look at our beginner-friendly obligatory hello world introduction to Aurelia . And if you want to dive even deeper (perhaps you've dabbled in Aurelia before) we have a fantastic selection of tutorials .

Aurelia as a default convention works on the premise of a view and view-model, both of which are tied together. The view-model is where your business logic lives and, if you have ever worked with .NET before (or other frameworks), you might refer to this as the controller.

Navigate to the src directory where your application code lives and open up the my-app(.ts/.js file. This is the main entry point for the application and this file is where business logic would live. As you can see, there is not a lot going on at the moment.

The class property message contains a string and within our view, we are displaying it using interpolation.

We are now going to create a new component which will be a smarter hello component. Inside of src create a new file called hello-name and use the appropriate file extension depending on whether you are using TypeScript or not. So, hello-name.ts or hello-name.js.

Notice how our new component doesn't look much different than the generated one? That's intentional. We are going to bind to this name property using two-way binding from within our view. We don't need any callback functions to update this value either.

Nice one! You just created a custom element view-model. It might not look like much, but you just learned a very core fundamental concept of building Aurelia applications. A view-model can be as simple and complex as you want it to be.

In the next chapter, we will hook this up with our view and allow a text input to change this value.

What is Aurelia?

Welcome to Aurelia, the future-oriented, open-source JavaScript platform for crafting extraordinary web, mobile, and desktop applications. At its core, Aurelia is more than just a framework; it believes in the unbridled power of open web standards. With Aurelia, your development experience is streamlined, intuitive, and remarkably flexible.

Aurelia isn't just feature-rich; it's a testament to high performance and extensive extensibility, offering a component-oriented design that's fully testable. It's built for developers who know the value of simplicity and the importance of conventions that don't obstruct but enhance creativity. 😎

To start, jump to our Quick Start Guide or read on for an overview.

Why choose Aurelia?

Aurelia emerges as a beacon of innovation and power in front-end development in a sea of frameworks. Here's why Aurelia might be the perfect choice for your next project:

• All-in-One Ecosystem: Aurelia is your Swiss Army knife, offering everything from dependency injection to routing, eliminating the need to juggle multiple libraries. Its ecosystem extends to plugins for internationalization, validation, and more, supported by tools like a CLI and a VS Code plugin for seamless development. And with Aurelia, flexibility is key; you can customize every aspect, including the templating/binding engine.

• Unparalleled Performance: Speed and efficiency are in Aurelia's DNA. It consistently outperforms competitors in benchmarks thanks to its sophisticated batched rendering and efficient memory usage.

• Data-Binding Done Right: Aurelia harmonizes the safety of uni-directional data flow with data-binding productivity, ensuring both performance and ease of development.

• Stability in a Dynamic World: Since our 1.0 release in 2016, Aurelia has maintained API stability, innovating without breaking changes, a testament to our commitment to developer trust.

• Adherence to High Standards: Aurelia is a paragon of standards compliance, focusing on modern JavaScript and Web Components without unnecessary abstractions.

• Empowering Developers: Aurelia's philosophy is simple: empower developers with plain JavaScript/TypeScript and get out of the way. This results in cleaner, more maintainable code.

• Ease of Learning and Use: Aurelia's design is intuitive and consistent, minimizing the learning curve and maximizing productivity with solid, simple conventions.

• Seamless Integration: Aurelia plays well with others. Its adherence to web standards makes it a breeze to integrate with any third-party library or framework.

• A Vibrant Open-Source Community: Embrace the open-source ethos with Aurelia, licensed under MIT, without restrictive clauses. Join a community that thrives on collaboration and innovation.

• A Welcoming and Supportive Community: Our active core team and Discord server embody a culture of welcome and support, where every developer is a valued member of the Aurelia family.

Embracing a Boutique Ecosystem

While it's true that Aurelia's ecosystem and community might seem modest compared to some of its more populous counterparts, this perceived underdog status is, in fact, one of its greatest strengths. Aurelia represents a boutique choice in web frameworks, prioritizing quality over quantity and fostering a tight-knit, highly engaged community. This approach translates to a more focused, consistent, and dedicated development experience, both in terms of the framework itself and the support you receive from the community.

The Advantages of a Niche Community

• Direct Impact: In a smaller community, each member's voice and contribution have a more significant impact. Developers have direct access to the core team, fostering a collaborative environment where feedback and contributions influence the framework's evolution.

• Quality Over Quantity: Aurelia focuses on delivering a high-quality, refined development experience. This means that each plugin, library, and tool in the ecosystem has been carefully crafted and thoroughly vetted to meet high standards.

• Nurturing Innovation: A smaller ecosystem doesn't mean limited capabilities. On the contrary, it often leads to innovative solutions and creative problem-solving, as developers are encouraged to think outside the box.

• Stronger Connections: A smaller community fosters closer relationships, leading to more meaningful interactions, collaborations, and a sense of belonging. This environment is conducive to a supportive and helpful atmosphere where developers at all levels can thrive.

Why Size Isn't Everything

The size of a community or ecosystem should not be the sole criterion for its effectiveness. In many cases, the quality of interactions, the dedication of its members, and the framework's alignment with your project's needs are far more critical factors. Aurelia's commitment to standards, modern best practices, and empowering approach offers a unique and rewarding development experience that stands on its own merits. Aurelia isn't trying to reinvent the wheel or make your life a misery by changing its API with every major release.

The Power of Conventional DOM Manipulation: why Aurelia doesn't have a Virtual DOM

In a landscape where Virtual DOM is often touted as a necessity, Aurelia confidently takes a different path. Aurelia's choice not to use a Virtual DOM is a deliberate and strategic decision grounded in a philosophy that prioritizes efficiency, simplicity, and alignment with web standards.

Understanding the Conventional DOM Approach

• Directness and Efficiency: Aurelia interacts directly and efficiently with the DOM. By avoiding the overhead of a Virtual DOM, Aurelia ensures faster rendering and updates, leading to a smoother user experience.

• Simplicity and Predictability: Without the abstraction layer of a Virtual DOM, Aurelia offers a more straightforward and predictable development experience. Developers work closer to the web platform, leveraging native browser capabilities for DOM manipulation.

• Optimal Performance: Aurelia's approach to DOM updates is highly optimized. It intelligently manages DOM changes, ensuring minimal performance overhead. This results in applications that are not only fast but also more resource-efficient. Let's say Aurelia isn't going to drain your phone or Macbook Pro battery.

The Benefits of Conventional DOM in Aurelia

• Aligned with Web Standards: Aurelia's commitment to standards means that it leverages the native capabilities of modern browsers, ensuring compatibility and future-proofing your applications. If the browser can do it, Aurelia won't try one-upping it by rolling its own implementation.

• Less Complexity, More Control: By avoiding a Virtual DOM, Aurelia reduces the complexity of your application's architecture. This direct approach gives developers more control and understanding of how their application interacts with the browser.

• Tailored for Modern Web Development: Aurelia is designed to meet the needs of modern web applications. Its efficient, standards-based approach is perfectly suited for today's dynamic, interactive web experiences.

The decision to not use a Virtual DOM is a reflection of Aurelia's overarching philosophy: to provide a powerful, efficient, and straightforward framework that stays true to the nature of the web. This approach encourages developers to build applications that are both performant and maintainable, leveraging the full potential of the web platform.

Navigation The Aurelia Docs

Your journey with Aurelia begins here in our meticulously crafted documentation. Start with the Quick Start Guide to grasp the basics of building an Aurelia application. The "Getting Started" section is your next stop, followed by "App Basics" for a deep dive into regular Aurelia usage.

As your comfort with Aurelia grows, explore "Advanced Scenarios" for insights into performance optimization and large-scale project management. While you may find less need for raw API documentation due to Aurelia's convention-based approach, our "API" section is comprehensive. Don't miss the "Examples" section, where practical code samples for common scenarios are found. And, our "Resources" section is a treasure trove of FAQs, framework comparisons, and much more.

Did you find something amiss in our documentation? Every page includes an "Edit on GitHub" link, making it easy to contribute corrections or improvements.

How to Be Part of the Community

As you become more and more familiar with Aurelia, perhaps you will even come up with something that you would like to share with the community. 🎉 The Aurelia team welcomes any contributions you feel would benefit others in the community. Check out the "Community Contribution" section if that is the case. We also welcome any feedback or suggestions that will help improve Aurelia and enrich the community. Check out the "Contributor Guide" for details about the contributing process and how to contact us.

Where To Begin

You're in the right place. If you are starting with Aurelia, we highly recommend reading through our Quick Start Guide. It will show you how to create a project and build your first components using Aurelia's powerful templating system.

Learn about enabling SVG binding in Aurelia template.

Adding SVG registration

By default, Aurelia won't work with SVG elements, since SVG elements and their attributes require different parsing rules. To teach Aurelia how to handle SVG element bindings, add the SVGAnalyzer like the following example:

import { SVGAnalyzer } from '@aurelia/runtime-html';
import { Aurelia } from 'aurelia';

Aurelia
    .register(SVGAnalyzer) // <-- add this line
    ...

After adding this registration, bindings with attributes will work as expected and the syntax is the same with the other bindings. Readmore on the basic binding syntax of Aurelia here.

In your view templates, you can specify inline variables using the <let> custom element.

The <let> element supports working with interpolation strings, plain strings, referencing view model variables, and other let bindings within your templates.

<let some-var="This is a string value"></let>

You could then display this value using its camelCase variant:

<p>${someVar}</p>

You can bind to variable values in a <let> too:

<let math-equation.bind="1 + 2 + 5"></let>

<!-- This will display 8 -->
<p>${mathEquation}</p>

The router emits several events via the Event Aggregator, allowing you to listen to router events. In some situations, you might opt for a router hook, but in other cases, an event might be what you are after.

A good example of where using events might be more appropriate is showing and hiding loaders and other parts of your applications related to routing.

The events fired are:

• au:router:router-start

• au:router:router-stop

• au:router:navigation-start

• au:router:navigation-end

• au:router:navigation-cancel

• au:router:navigation-error

To listen to these events, you subscribe to them using the event aggregator like this:

import { IEventAggregator } from 'aurelia';
import { IRouteableComponent } from '@aurelia/router'; 

export class MyComponent implements IRouteableComponent {    
    constructor(@IEventAggregator readonly ea: IEventAggregator) {

    }
    
    bound() {
        this.ea.subscribe('au:router:navigation-start', payload => {
            // Do stuff inside of this callback
        });
    }
 }   

As you might expect, these events are named in an intuitive way depending on the action taking place inside the router.

Error message

Attempted to jitRegister an intrinsic type: yyyy. Did you forget to add @inject(Key)

Parameters

Interface name

Error explanation

A DI container is trying to resolve an instance of an interface, but there is no registration for it. This means the instance you are trying to load has not been registered with Dependency Injection.

Possible solutions

Ensure that you are registering your interface with Aurelia. This can be done inside of the register method on the Aurelia instance or through the DI methods themselves.

Please also note that this error could be caused by a plugin and not your application. After ruling out that the error is not being caused by your code, try removing any registered plugins one at a time to see if the error resolves itself.

Error message

yyyy not registered, did you forget to add @singleton()?

Parameters

Name of the key being resolved

Error explanation

A DI container is trying to resolve a key, but there's not a known strategy for it.

Possible solutions

Try adding a strategy for your resolved key. You can do this using @singleton or other forms of DI resolution

Please also note that this error could be caused by a plugin and not your application. After ruling out that the error is not being caused by your code, try removing any registered plugins one at a time to see if the error resolves itself.

Aurelia 2’s templating system offers a powerful and intuitive way to build and manage the user interface of your web application. It goes beyond the traditional boundaries of HTML, infusing it with enhanced capabilities to create dynamic and interactive user experiences. At the heart of Aurelia 2's templating is the seamless connection between your HTML templates and the underlying JavaScript or TypeScript code, enabling a responsive and data-driven UI.

In Aurelia 2, templates are not just static HTML files. They are dynamic views that interact with the underlying logic of your application, responding to user actions and data changes. This integration makes your development process more efficient, allowing you to build complex UIs with less code and greater clarity.

From the moment you scaffold a new Aurelia 2 project, you engage with templates that are both familiar in their HTML structure and powerful in their extended functionality. Whether defining the layout for a new component or displaying data in your HTML, Aurelia 2's templating syntax is designed to be both developer-friendly and highly expressive.

Features of Aurelia Templating

• Two-Way Data Binding: Aurelia's robust data binding system ensures a seamless data flow between your application’s model and the view, keeping both in sync without extra effort.

• Custom Elements and Attributes: Extend your HTML with custom elements and attributes that encapsulate complex behaviors, promoting code reuse and modularity.

• Adaptive Dynamic Composition: Dynamically render components and templates based on your application's state or user interactions, enabling the creation of flexible and adaptive UIs.

• Rich Templating Syntax: Utilize Aurelia's powerful templating syntax for iterating over data, conditionally rendering parts of your UI, and easily handling events.

• Expression and Interpolation: Effortlessly bind data to your templates and manipulate attributes with Aurelia’s straightforward expression syntax.

This guide will take you through creating a hello world app using Aurelia and briefly explain its main concepts. We will be building a simple hello, world example with a text field you can enter a name into and watch the view update. We assume you are familiar with JavaScript, HTML, and CSS.

When you complete this guide, you'll be ready to take your first steps building your own Aurelia app and, you'll have the resources you need to continue into more advanced topics. So, what are you waiting for? Let's get started!

Text interpolation allows you to display values within your template views. By leveraging ${}, a dollar sign followed by opening and closing curly braces, you can display values inside your views. The syntax will be familiar to you if you are familiar with .

Displaying values with interpolation

Interpolation can be used to display the value of variables within your HTML templates, object properties and other forms of valid data.

To show how interpolation works, here is an example.

Notice how the variable we reference in our HTML template is the same as it is defined inside of our view model? Anything specified on our view model class is accessible in the view. Aurelia will replace ${myName} with Aurelia think of it as a fancy string replacement. All properties defined in your view model will be accessible inside your templates.

Template expressions

A template expression allows you to perform code operations inside of ${} we learned about earlier. You can perform addition, subtraction and even call functions inside of interpolation.

In the following simple example, we are adding two and two together. The value that will be displayed will be 4.

You can call functions with parameters if you have a function inside your view model.

You can also use ternaries inside of your interpolation expressions:

Optional Syntax

Also supported in template expressions is optional syntax. Aurelia supports the following optional syntax in templates.

• ??

• ?.

• ?.()

• ?.[]

Using optional syntax and nullish coalescing allows us to create safer expressions without the need for if.bind or boilerplate code in view models.

This can help clean up what otherwise might have been long and complex ternary expressions to achieve the above result.

Notes on syntax

You would be forgiven for thinking that you can do pretty much anything that Javascript allows you to do, but there are limitations in what you can do inside of interpolation you need to be aware of.

1. Expressions cannot be chained using ; or ,

2. You cannot use primitives such as Boolean, String, instanceOf, typeof and so on

3. You can only use the pipe separator | when using value converters but not as a bitwise operator

There are situations that some elements of a custom element should be rendered at a different location within the document, usually at the bottom of a document body or even inside of another element entirely. Aurelia supports this intuitively with the portal custom attribute.

While the location of the rendered element changes, it retains its current binding context. A great use for the portal attribute is when you want to ensure an element is displayed in the proper stacking order without needing to use CSS hacks like z-index:9999

Using the portal attribute without any configuration options will portal the element to beneath the document body (before the closing body tag).

Targeting CSS selectors

If you want to choose where a portalled element is moved to, you can supply a CSS selector where it should be moved.

Target an element with an ID of somewhere:

Target an element by class:

Target an element by tagName:

Targeting elements

The portal attribute can also reference other elements with a ref attribute on them.

You can also target elements not using the ref attribute too. A good example is a custom element. Maybe you want to portal a section of a child element to the parent element.

We can do things with the injected element instance, like access the parentElement or other non-standard scenarios you might encounter.

You could also do this with query calls such as querySelector and so forth as well aliased to class properties.

Determining the position

By default, the portal attribute will portal your elements before the closing tag of your target. By default using portal without any configuration values will portal it just before the closing </body> tag.

We can override this behavior using the position property and the following values:

• beforebegin

• afterbegin

• beforeend (the default value)

• afterend

In this example, our element will move to just after the opening body tag <body> the other values are self-explanatory.

In the previous section, we created a basic view model, and you are probably sceptical that we are now going to create a view with a text input that updates this value without writing any more Javascript.

Inside the src directory create a new file called hello-name.html this will complicate the view model you already have (hello-name.ts or hello-name.js).

Firstly, let's write the code to display the value. Notice how we are using interpolation to print the value like the default generated my-app.html file was? ${name} the value inside the curly braces references the class property we defined in the previous section, by the name of name.

I would say run the app and see it in action, but we haven't imported our custom element just yet. Let's do that now.

Inside of my-app.html replace the entire file with the following:

We use the import element to include our newly created component. Take note there is a lack of file extension. This is because Aurelia will know to include our view-model and, in turn, include our view and any styles.

We then reference our custom element by its name. Aurelia knows using default conventions to take the file name, strip the file extension and use that as the tag name (this is configurable but beyond the scope of this tutorial).

If you were to run the app using npm start you would then see your application rendering your new component. You should see the text, Hello, Person! rendering in the view. Once you have the app running, leave it running as any changes you make will automatically be detected and re-rendered.

Binding the name to a text input

We have a functional custom element, but we promised we would be able to update the name with any value we want. Inside of hello-name.html add the following beneath the existing heading.

You should now see a text input with the value Person inside of it. By adding value.bind to the input, Aurelia will use two-way binding by default. This means it will show the value from the view-model inside of the view, and if it changes in either view or view-model, it will be updated. Think of a two-way binding as syncing the value.

Type something into the text input and you should see the heading value change as you type. This works because Aurelia binds to the native value property of the text input and keeps track of the changes for you without needing to use callbacks or anything else.

As you might have noticed, there really is not that much code here. Leveraging Aurelia's conventions and defaults allows you to write Aurelia applications without the verbosity and without writing tens of lines of code to do things like binding or printing values.

Attribute binding in Aurelia is a powerful feature that allows you to bind to any native HTML attribute in your templates. This enables dynamic updates to element attributes such as classes, styles, and other standard HTML attributes.

Basic Binding Syntax

The basic syntax for binding to attributes in Aurelia is straightforward:

<div attribute-name.bind="value"></div>

You can bind to almost any attribute listed in the comprehensive HTML attributes list, which can be found here.

Binding Techniques and Syntax

Aurelia provides multiple methods for attribute binding, each with its syntax and use cases.

Interpolation Binding

Interpolation allows for embedding dynamic values within strings. Here's an example using interpolation to bind the id attribute:

<div>
    <h1 id="${headingId}">My Heading</h1>
</div>

Keyword Binding

Aurelia supports several binding keywords, each defining the data flow between the view model and the view:

• one-time: Updates the view from the view model once and does not reflect subsequent changes.

• to-view / one-way: Continuously updates the view from the view model.

• from-view: Updates the view model based on changes in the view.

• two-way: Creates a two-way data flow, keeping the view and view model in sync.

• bind: Automatically determines the appropriate binding mode, defaulting to two-way for form elements and to-view for most other elements.

Examples of Keyword Binding

<input type="text" value.bind="firstName">
<input type="text" value.two-way="lastName">
<input type="text" value.from-view="middleName">

<a class="external-link" href.bind="profile.blogUrl">Blog</a>
<a class="external-link" href.to-view="profile.twitterUrl">Twitter</a>
<a class="external-link" href.one-time="profile.linkedInUrl">LinkedIn</a>

Binding to Images

Binding image attributes, such as src and alt, is as simple as:

<img src.bind="imageSrc" alt.bind="altValue">

Disabling Elements

Bind to the disabled attribute to disable buttons and inputs dynamically:

<button disabled.bind="disableButton">Disabled Button</button>

InnerHtml and TextContent

Choose between innerhtml for rendering HTML content and textcontent for text-only content:

<div innerhtml.bind="htmlContent"></div>
<div textcontent.bind="textContent"></div>

Advanced Binding Techniques

How Attribute Binding Works

Aurelia uses a mapping function to convert properties to HTML attributes. The attribute mapper handles the conversion, typically changing kebab-case to camelCase. However, not all properties map directly to attributes.

Using the .attr Tag

If automatic mapping fails, use .attr to ensure proper attribute binding:

<input pattern.attr="patternProp">

Attribute Binding Behavior

Apply the attribute binding behavior with .bind and & attr to specify the binding type:

<input pattern.bind="patternProp & attr">

The <au-viewport> element is where all of the routing magic happens, the outlet. It supports a few different custom attributes, allowing you to configure how the router renders your components. It also allows you to use multiple viewports to create different layout configurations with your routing.

Named viewports

The router allows you to add multiple viewports to your application and render components into each viewport element by their name. The <au-viewport> element supports a name attribute, which you'll want to use if you have more than one.

<main>
    <au-viewport name="main"></au-viewport>
</main>
<aside>
    <au-viewport name="sidebar"></au-viewport>
</aside>

In this example, we have the main viewport for our main content, and another viewport called sidebar for our sidebar content which is dynamically rendered. When using viewports, think of them like iframes, independent containers that can maintain their own states.

Specifying a viewport on a route

Routes will load in the default viewport element if there are one or more viewports. However, routes can be told to load into a specific viewport.

import { IRouteableComponent, routes } from '@aurelia/router';

@routes([
    {
        component: import('./my-component'),
        path: 'my-component',
        title: 'Your Component <3',
        viewport: 'sidebar'
    }
])
export class MyApp implements IRouteableComponent {
}

By specifying the viewport property on a route, we can tell it to load into a specific route.

Aurelia makes it easy to modify an element inline class list and styles. You can work with not only strings but also objects to manipulate elements.

Binding HTML Classes

The class binding allows you to bind one or more classes to an element and its native class attribute.

Binding to a single class

Adding or removing a single class value from an element can be done using the .class binding. By prefixing the .class binding with the name of the class you want to display conditionally selected.class="myBool" you can add a selected class to an element. The value you pass into this binding is a boolean value (either true or false), if it is true the class will be added; otherwise, it will be removed.

<p selected.class="isSelected">I am selected (I think)</p>

Inside of your view model, you would specify isSelected as a property and depending on the value, the class would be added or removed.

Here is a working example of a boolean value being toggled using .class bindings.

Binding to multiple classes

Unlike singular class binding, you cannot use the .class binding syntax to conditionally bind multiple CSS classes. However, there is a multitude of different ways in which this can be achieved.

Once you have your CSS imported and ready to use in your components, there might be instances where you want to dynamically bind to the style attribute on an element (think setting dynamic widths or backgrounds).

Binding Inline Styles

Binding to a single style

You can dynamically add a CSS style value to an element using the .style binding in Aurelia.

<p background.style="bg">My background is blue</p>

Inside of your view model, you would specify bg as a string value on your class.

Here is a working example of a style binding setting the background colour to blue:

Binding to multiple styles

To bind to one or more CSS style properties you can either use a string containing your style values (including dynamic values) or an object containing styles.

Style binding using strings

This is what a style string looks like, notice the interpolation here? It almost resembles just a plain native style attribute, with exception of the interpolation for certain values. Notice how you can also mix normal styles with interpolation as well?

export class MyApp {
  private backgroundColor = 'black';
  private textColor = '#FFF';
}

<p style="color: ${textColor}; font-weight: bold; background: ${backgroundColor};">Hello there</p>

You can also bind a string from your view model to the style property instead of inline string assignment by using style.bind="myString" where myString is a string of styles inside of your view model.

Style binding using objects

Styles can be passed into an element by binding to the styles property and using .bind to pass in an object of style properties. We can rewrite the above example to use style objects.

export class MyApp {
  private styleObject = {
    background: 'black',
    color: '#FFF'
  };
}

<p style.bind="styleObject">Hello there</p>

From a styling perspective, both examples above do the same thing. However, we are passing in an object and binding it to the style property instead of a string.

In Aurelia 2, templates are designed to limit direct access to global variables like window or document for security reasons. However, there are scenarios where access to certain global variables is necessary. Aurelia allows access to a predefined list of global variables commonly used in development.

To reduce boilerplate, Aurelia allows template expression to access a fixed list of global variables that are usually needed. Those globals are as follows:

Global Examples

Here are some examples of using globals inside of Aurelia templates. The usage is the same as it is inside of Javascript, except in your Aurelia templates.

Working with JSON

Manipulate JSON data directly in your templates.

Mathematical Operations

Perform calculations using the Math object.

Conditional Rendering with isNaN

Display content conditionally based on numeric checks.

Regular Expressions with RegExp

Use the RegExp constructor to create dynamic regular expressions for data validation or manipulation.

Dynamic Object Property Access with Object

Access properties dynamically on an object using the Object constructor.

Set Operations with Set

Demonstrate set operations like union, intersection, or difference.

Encoding and Decoding URLs with encodeURI and decodeURI

Manipulate URL strings by encoding or decoding them.

Number Formatting with Intl.NumberFormat

Format numbers using Intl.NumberFormat for localization.

Complex Array Manipulations with Array

Demonstrate complex array manipulations, such as chaining methods.

Best Practices and Considerations

• Use Sparingly: Rely on global variables only when necessary. Prefer component properties and methods for data and logic.

• Security: Be cautious of the data processed using global functions to prevent XSS attacks and other vulnerabilities.

• Performance: Frequent use of complex operations like JSON.stringify in templates can impact performance. Consider handling such operations in the component class.

• Reactivity: Remember that changes to global variables are not reactive. If you need reactivity, use component properties or state management solutions.

The Observer Locator API allows you to watch properties in your components for changes without the need for using the @observable decorator. In most cases, manual observation will not be required using this API, but it is there if you want it.

Basic observer interface

By default, an observer locator is used to create observers and subscribe to them for change notification.

A basic observer has the following interface:

The subscribe method of an observer can be used to subscribe to the changes that it observes. This method takes a subscriber as its argument.

A basic subscriber has the following interface:

Getting an observer of a property

An observer of an object property can be retrieved using an observer locator.

An example of this is:

And to subscribe to changes emitted by this observer:

Getting an observer of an expression

It's not always sufficient to observe a single property on an object, and it's sometimes more desirable to return a computed value from the source so that subscribers of an observer don't have to perform any logic dealing with the updated values. An example of this is the follow observation of firstName and lastName to notify full name:

Doing it the way above is cumber some as we need to setup 2 observers and 2 subscribers, also there's a typo risk. We can also use a getter to express a computed value, and then observe that getter to avoid having to do heavy setup work:

This is not always feasible since the obj could be from a 3rd party library, or some json data from server, and the risk of having a typo fullName is still there.

Aurelia provides another API of creating observer to deal with this scenario, where it's more desirable to use a function/lambda expression to express the dependencies and computed value to notify the subscriber. To use this API, replace the 2nd parameter of getObserver with a getter function to express the value:

Please see below a reference to each related error with explanations and resources for debugging and solving.

This section details how you can use the load method on the router instance or load attribute to navigate to other parts of your application.

Programmatically using the load method

To use the load method, you have first to inject the router into your component. This can be done easily by using the IRouter decorator on your component constructor method. The following code will add a property to your component, which we can reference.

import { IRouter, IRouteableComponent } from '@aurelia/router';

export class MyComponent implements IRouteableComponent {
    constructor(@IRouter private router: IRouter) {

    }
}

Navigating without options

The load method can accept a simple string value allowing you to navigate to another component without needing to supply configuration options.

import { IRouter, IRouteableComponent } from '@aurelia/router';

export class MyComponent implements IRouteableComponent {
    constructor(@IRouter private router: IRouter) {

    }

    async viewProducts() {
        await this.router.load('/products');
    }
}

You could also use the string value method to pass parameter values and do something like this where our route expects a product ID, and we pass 12:

import { IRouter, IRouteableComponent } from '@aurelia/router';

export class MyComponent implements IRouteableComponent {
    constructor(@IRouter private router: IRouter) {

    }

    async viewProducts() {
        await this.router.load(`/products/12`);
    }
}

Specifying load options

The router instance load method allows you to specify different properties on a per-use basis. The most common one is the title property, which allows you to modify the title as you navigate your route.

A list of available load options can be found below:

• title — Sets the title of the component being loaded

• parameters — Specify an object to be serialized to a query string and then set to the query string of the new URL.

• fragment — Specify the hash fragment for the new URL.

These option values can be specified as follows and when needed:

import { IRouter, IRouteableComponent } from '@aurelia/router';

export class MyComponent implements IRouteableComponent {
    constructor(@IRouter private router: IRouter) {

    }

    async viewProduct() {
        await this.router.load('products', {
            title: 'My product',
            parameters: {
                prop1: 'val',
                tracking: 'asdasdjaks232'
            },
            fragment: 'jfjdjf'
        });
    }
}

HTML load attribute

The router also allows you to decorate links and buttons in your application using a load attribute, which works the same way as the router instance load method.

If you have routes defined on a root level (inside of my-app.ts) you will need to add a forward slash in front of any routes you attempt to load. The following would work in the case of an application using configured routes.

<a load="/products/12">Product #12</a>

The load attribute can do more than accept a string value. You can also bind to the load attribute for more explicit routing. The following example is a bit redundant as specifying route:product would be the same as specifying load="product" , but if you're wanting more explicit routing, it conveys the intent better.

<a load="route:product;">My Route</a>

And where things start to get interesting is when you want to pass parameters to a route. We use the params configuration property to specify parameters.

<a load="route:profile; params.bind:{name: 'rob'}">View Profile</a>

In the above example, we provide the route (id) value (via route: profile). But, then also provide an object of parameters (via params.bind: { name: 'rob' }).

These parameter values correspond to any parameters configured in your route definition. In our case, our route looks like this:

{
    id: 'profile',
    path: 'profile/:name',
    component: () => import('./view-profile'),
    title: 'View Profile'
},

Redirecting

Depending on the scenario, you will want to redirect users in your application. Unlike using the load API on the router where we manually route (for example, after logging in) redirection allows us to redirect inside router hooks.

Please see the Routing Lifecycle section to learn how to implement redirection inside your components.

Installation

Install via npm

npm install @aurelia/ui-virtualization

Load the plugin

import { Aurelia } from 'aurelia';
import { DefaultVirtualizationConfiguration } from '@aurelia/ui-virtualization';

Aurelia
    .register(DefaultVirtualizationConfiguration)
    .app(...)

Using the plugin

Simply bind an array to virtual-repeat like you would with the standard repeat. The repeated rows are expected to have equal height throughout the list, and one item per row.

div

<template>
  <div virtual-repeat.for="item of items">
    ${$index} ${item}
  </div>
</template>

list

<template>
  <ul>
    <li virtual-repeat.for="item of items">
    ${$index} ${item}
    </li>
  </ul>
</template>

table

<template>
  <table>
    <tr virtual-repeat.for="item of items">
      <td>${$index}</td>
      <td>${item}</td>
    </tr>
  </table>
</template>

export class MyVirtualList {
    items = ['Foo', 'Bar', 'Baz'];
}

With a surrounding fixed height container with overflow scroll. Note that overflow: scroll styling is inlined on the elemenet. It can also be applied from CSS. An error will be thrown if no ancestor element with style overflow: scroll is found.

Caveats

1. <template/> is not supported as root element of a virtual repeat template. This is due to the difficulty of technique employed: item height needs to be calculatable. With <tempate/>, there is no easy and performant way to acquire this value.

2. Similar to (1), other template controllers cannot be used in conjunction with virtual-repeat, unlike repeat. I.e: built-in template controllers: with, if, etc... cannot be used with virtual-repeat. This can be workaround'd by nesting other template controllers inside the repeated element, with <template/> element, for example:

<template>
  <h1>${message}</h1>
  <div virtual-repeat.for="person of persons">
    <template with.bind="person">
      ${Name}
    </template>
  </div>
</template>

1. Beware of CSS selector :nth-child and similar selectors. Virtualization requires appropriate removing and inserting visible items, based on scroll position. This means DOM elements order will not stay the same, thus creating unexpected :nth-child CSS selector behavior. To work around this, you can use contextual properties $index, $odd, $even etc... to determine an item position, and apply CSS classes/styles against it, like the following example:

<template>
  <div virtual-repeat.for="person of persons" class="${$odd ? 'odd' : 'even'}-row">
    ${person.name}
  </div>
</template>

1. Similar to (3), virtualization requires appropriate removing and inserting visible items, so not all views will have their lifecycle invoked repeatedly. Rather, their binding contexts will be updated accordingly when the virtual repeat reuses the view and view model. To work around this, you can have your components work in a reactive way, which is natural in an Aurelia application. An example is to handle changes in change handler callback.

Tobe implemented feature list

• ability to configure height & many aspects of the virtual repeat

• infinite scroll

• horizontal scrolling

• variable height

• scrolling direction

Application Startup

Aurelia allows you to configure the application startup in a couple of different ways. A quick setup where some defaults are assumed and a verbose setup where you can configure some of the framework-specific behaviors.

Quick startup

The quick startup approach is what most developers will choose.

import { RouterConfiguration } from '@aurelia/router';
import Aurelia, { StyleConfiguration } from 'aurelia';

import { MyRootComponent } from './my-root-component';

// By default host to element name (<my-root-component> for MyRootComponent),
// or <body> if <my-root-component> is absent.
Aurelia.app(MyRootComponent).start();

// Or load additional Aurelia features
Aurelia
  .register(
    RouterConfiguration.customize({ useUrlFragmentHash: false })
  )
  .app(MyRootComponent)
  .start();

// Or host to <my-start-tag>
Aurelia
  .register(
    RouterConfiguration.customize({ useUrlFragmentHash: false })
  )
  .app({
    component: MyRootComponent,
    host: document.querySelector('my-start-tag')
  })
  .start();

Verbose Startup

To start an Aurelia application, create a new Aurelia() object with a target host and a root component and call start().

import Aurelia, { StandardConfiguration } from 'aurelia';
import { ShellComponent } from './shell';

new Aurelia()
  .register(StandardConfiguration)
  .app({ host: document.querySelector('body'), component: ShellComponent })
  .start();

In most instances, you will not use the verbose approach to starting your Aurelia applications. The verbose approach is more aimed at developers integrating Aurelia into existing web applications and views.

Register a globally available custom element

Registering a single element

To make a custom element globally available to your application, pass the custom element constructor to the .register() method on your Aurelia app.

import { CardCustomElement } from './components/card';

// When using quick startup
Aurelia
  .register(...)
  .register(<any>CardCustomElement);
  .app({ ... })
  .start();

// When using verbose startup
new Aurelia()
  .register(...)
  .register(<any>CardCustomElement)
  .app({ ... })
  .start();

Register a set of elements

If you have a package that exports all your custom elements, you can pass the entire package to the .register() method on your Aurelia app.

src/components/index.ts:

export { CardCustomElement } from './card';
export { CollapseCustomElement } from './collapse';

src/main.ts:

import * as globalComponents from './components';

// When using quick startup
Aurelia
  .register(...)
  .register(<any>globalComponents)
  .app({ ... })
  .start();

// When using verbose startup
new Aurelia()
  .register(...)
  .register(<any>globalComponents)
  .app({ ... })
  .start();

Getting started

Aurelia comes with a flexible and powerful logging system that allows you to display debug and error messages in your applications in a slightly better way than using native console.log statements.

Reasons to use logging inside of your apps and plugins include helpful debug messages for other developers (living comments) or displaying helpful information to the end-user in the console when something goes wrong.

The logger is injected using dependency injection into your components:

import { ILogger } from 'aurelia';

export class MyComponent {
  public constructor(@ILogger private readonly logger: ILogger) {
      this.logger = logger.scopeTo('MyComponent');
  }
}

In this example, we scope our logger to our component. But scoping is optional, and the logger can be used without using scopeTohowever, we highly recommend using the scoping feature to group your messages in the console.

Logging methods

Just like console.log the Aurelia logger supports the following methods:

• debug

• info

• warn

• trace

These methods are called on the logger instance you injected into your component.

import { ILogger } from 'aurelia';

export class MyComponent {
  public constructor(@ILogger private readonly logger: ILogger) {
      this.logger = logger.scopeTo('MyComponent');
  }
  
  public add() {
      this.logger.debug(`Adding something`);
  }
}

Just like console.log you can also pass in values such as strings, booleans, arrays and objects.

import { ILogger } from 'aurelia';

export class MyComponent {
  public constructor(@ILogger private readonly logger: ILogger) {
      this.logger = logger.scopeTo('MyComponent');
  }
  
  public add() {
      this.logger.debug(`Adding something`, [
          { prop: 'value', something: 'else' }
      ]);
  }
}

Creating a logger

To create a custom logger for your applications and plugins, you can create a more reusable wrapper around the logging APIs to use in your applications.

import { DI, ILogger, ConsoleSink, IPlatform, LogLevel, LoggerConfiguration, Registration } from '@aurelia/kernel';
import { BrowserPlatform } from '@aurelia/platform-browser';

const PLATFORM = BrowserPlatform.getOrCreate(globalThis);

const staticContainer = DI.createContainer();
staticContainer.register(Registration.instance(IPlatform, Registration));
staticContainer.register(LoggerConfiguration.create({ sinks: [ConsoleSink], level: LogLevel.fatal }));

export const log = staticContainer.get(ILogger).scopeTo('My App');

It might look like a lot of code, but this logger implementation will create a scoped logger wrapper you can import into your applications and use in the following way:

log.debug(`Debug message`);
log.warn(`This is a warning`);

Aurelia's testing library enhances the developer experience by offering a Fluent API for creating test fixtures. This API provides a more readable, flexible, and chainable way to set up component tests. With the Fluent API, you can incrementally build your test fixture, making the configuration of your tests more intuitive and maintainable.

Understanding the Fluent API

The Fluent API for createFixture comprises a series of chainable methods that allow you to configure each aspect of your test fixture in a step-by-step manner. This methodical approach to building test fixtures is particularly beneficial when dealing with complex setups or when you need to express the configuration in a more descriptive way.

Legacy Approach vs. Fluent API

Previously, creating a test fixture required passing all configuration parameters to the createFixture function in a single call, which could become unwieldy as the number of configurations grew:

const { appHost, startPromise, tearDown } = await createFixture('<my-element></my-element>', class AppRoot {}, [Dependency1, Dependency2]).promise;

With the introduction of the Fluent API, you can now configure your test fixture using several self-explanatory methods, each responsible for a specific part of the setup:

const fixture = createFixture
  .component(AppRoot)
  .deps(Dependency1, Dependency2)
  .html('<my-element></my-element>');
  
const { appHost, startPromise } = await fixture.build().start();

Available Fluent API Methods

The Fluent API provides the following methods, which can be chained together to configure your test fixture:

• .component(component: any): Specifies the root component class for the test fixture.

• .deps(...dependencies: any[]): Registers additional dependencies required by the test or the components under test.

• .html(template: string | HTMLTemplateElement): Sets the HTML template for the test. This can be provided as a string literal, a tagged template literal, or an HTMLTemplateElement.

• .build(): Finalizes the configuration and builds the test fixture.

• .start(): Initializes the test fixture and returns a promise that resolves when the component is bound and attached.

Fluent API in Action: Example Test

Consider you have a MyCustomElement that relies on Dependency1 and Dependency2. The following example demonstrates how to use the Fluent API to create a test fixture for this component:

import { MyCustomElement } from './my-custom-element';
import { Dependency1, Dependency2 } from './dependencies';
import { createFixture } from '@aurelia/testing';

describe('MyCustomElement', () => {
  it('renders correctly', async () => {
    // Incrementally configure the test fixture using the Fluent API
    const fixture = createFixture
      .component(MyCustomElement)
      .deps(Dependency1, Dependency2)
      .html('<my-custom-element></my-custom-element>');

    // Build and start the fixture
    const { appHost, startPromise } = await fixture.build();

    // Await the startPromise to ensure the component is fully initialized
    await startPromise;

    // Perform assertions on appHost to verify the correct rendering of MyCustomElement
    expect(appHost.querySelector('my-custom-element')).toBeDefined();
    expect(appHost.textContent).toContain('Expected content');

    // Additional assertions and test logic...
  });
});

In this example, the Fluent API clearly outlines each step of the test fixture setup. It begins by defining the component under test, registers any dependencies, and sets the HTML template. Finally, the fixture is built and started, and the test awaits the startPromise before performing assertions.

Advantages of the Fluent API

The Fluent API offers several advantages over the traditional approach:

• Readability: The step-by-step configuration makes the test setup easier to read and understand.

• Maintainability: It's easier to update and maintain tests as configurations can be changed independently without affecting the entire setup.

• Flexibility: The API allows for dynamic adjustments to the test setup, accommodating various testing scenarios.

By employing the Fluent API, developers can write more coherent and expressive tests, enhancing the overall testing experience in Aurelia 2 applications.

The Aurelia binding language provides commands like .bind, .one-way, .trigger, .for, .class etc. These commands are used in the view to express the intent of the binding, or in other words, to build binding instructions.

Although the out-of-box binding language is sufficient for most use cases, Aurelia also provides a way to extend the binding language so that developers can create their own incredible stuff when needed.

In this article, we will build an example to demonstrate how to introduce your own binding commands using the @bindingCommand decorator.

Binding command

Before jumping directly into the example, let's first understand what a binding command is. In a nutshell, a binding command is a piece of code used to register "keywords" in the binding language and provide a way to build binding instructions from that.

To understand it better, we start our discussion with the template compiler. The template compiler is responsible for parsing templates and, among all, creating attribute syntaxes. This is where the attribute patterns come into play. Depending on how you define your attribute patterns, the attribute syntaxes will be created with or without a binding command name, such as bind, one-way, trigger, for, class, etc. The template compiler then instantiates binding commands for the attribute syntaxes with a binding command name. Later, binding instructions are built from these binding commands, which are "rendered" by renderers. Depending on the binding instructions, the " rendering " process can differ. For this article, the rendering process details are unimportant, so we will skip it.

Creating a custom binding command

To create a binding command, we use the @bindingCommand decorator with a command name on a class that implements the following interface:

interface BindingCommandInstance {
  type: CommandType;
  build(info: ICommandBuildInfo, parser: IExpressionParser, mapper: IAttrMapper): IInstruction;
}

A binding command must return 'IgnoreAttr' from the type property. This tells the template compiler that the binding command takes over the processing of the attribute.

The more interesting part of the interface is the build method. The template compiler calls this method to build binding instructions. The info parameter contains information about the element, the attribute name, the bindable definition (if present), and the custom element/attribute definition (if present). The parser parameter is used to parse the attribute value into an expression. The mapper parameter of type IAttrMapper is used to determine the binding mode, the target property name, etc. (for more information, refer to the documentation). In short, here comes your logic to convert the attribute information into a binding instruction.

For our example, we want to create a binding command that can trigger a handler when custom events such as bs.foo.bar, bs.fizz.bizz etc. is fired, and we want the following syntax:

<div foo.bar.bs="ev => handleCustomEvent(ev)"></div>

instead of

<div bs.foo.bar.trigger="ev => handleCustomEvent(ev)"></div>

We first create a class that implements the BindingCommandInstance interface to do that.

import { IExpressionParser } from '@aurelia/runtime';
import {
  BindingCommandInstance,
  ICommandBuildInfo,
  IInstruction,
  ListenerBindingInstruction,
  bindingCommand,
} from '@aurelia/runtime-html';

@bindingCommand('bs')
export class BsBindingCommand implements BindingCommandInstance {
  public get type(): 'IgnoreAttr' {
    return 'IgnoreAttr';
  }

  public build(
    info: ICommandBuildInfo,
    exprParser: IExpressionParser
  ): IInstruction {
    return new ListenerBindingInstruction(
      /* from           */ exprParser.parse(info.attr.rawValue, 'IsFunction'),
      /* to             */ `bs.${info.attr.target}`,
      /* preventDefault */ true,
      /* capture        */ false
    );
  }
}

Note that from the build method, we are creating a ListenerBindingInstruction with bs. prefixed to the event name used in the markup. Thus, we are saying that the handler should be invoked when a bs.* event is raised.

To register the custom binding command, it needs to be registered with the dependency injection container.

And that's it! We have created our own binding command. This means that the following syntax will work.

<div foo.bar.bs="ev => handleCustomEvent(ev)"></div>
<!--         ^^
             |_________ custom binding command
-->

Live example

This binding command can be seen in action below.

Note that the example defines a custom attribute pattern to support foo.bar.fizz.bs="ev => handle(ev)" syntax.

A common scenario in a single-page application is page transitions. When a page loads or unloads, an animation or transition effect might be used to make it feel more interactive and app-like.

By leveraging lifecycle hooks, we can perform animations and transition effects in code.

import { lifecycleHooks } from '@aurelia/runtime-html';
import anime from 'animejs';

const animateIn = (element) =>
  anime({
    targets: element,
    translateX: () => ['110%', '0%'],
    duration: 900,
    easing: 'easeInOutQuart',
  });

const animateOut = (element) =>
  anime({
    targets: element,
    translateX: () => ['0%', '110%'],
    duration: 900,
    easing: 'easeInOutQuart',
  });

@lifecycleHooks()
export class AnimationHooks {
  private element;
  private backwards = false;

  public created(vm, controller): void {
    this.element = controller.host;
  }

  public loading(vm, _params, _instruction, navigation) {
    this.backwards = navigation.navigation.back;
  }
  
  public unloading(vm, _instruction, navigation) {
    this.backwards = navigation.navigation.back;
  }

  public attaching() {
    if (this.backwards) {
      animateOut(this.element);
    } else {
      animateIn(this.element);
    }
  }

  public detaching() {
    if (this.backwards) {
      animateIn(this.element);
    } else {
      animateOut(this.element);
    }
  }
}

At first glance, this might look like a lot of code, but we do the animation inside of the attaching and detaching hooks. Using the Anime.js animation library, we create two animation functions for sliding our views in and out.

We use the created lifecycle callback to access the host element (the outer element of our custom element) which we will animate. Most of the other callbacks determine the direction we are heading in.

import { One } from './one';
import { Two } from './two';
import { AnimationHooks } from './animation-hooks';

export class MyApp {
  static dependencies = [AnimationHooks];

  public static routes = [
    { path: ['', 'one'], component: One },
    { path: 'two', component: Two },
  ];

  public message: string = 'Hello Aurelia 2!';
}pe

We inject out AnimationHooks class into our main component, but we also inject it into the sub-components we want to animate. We avoid setting our hook globally, or it would run for all components (which you might want).

As you can see, besides some router-specific lifecycle methods, animating with the router isn't router-specific and leverages Aurelia lifecycles.

A link to a demo of slide in and out animations based on routing can be seen below:

An introduction to enhance

Enhancement in Aurelia allows for integrating Aurelia’s capabilities with existing DOM elements or dynamically inserted HTML content. This feature is particularly useful in scenarios where the application is not entirely built with Aurelia, such as when integrating with server-rendered pages or dynamically generated content.

The showed how to start Aurelia for an empty root node. While that's the most frequent use case, there might be other scenarios where we would like to work with an existing DOM tree with Aurelia.

Basic Syntax and Key Points

The basic usage of enhance is straightforward:

Key Points to Understand:

1. Anonymous Custom Element Hydration: The enhancement treats the target node as an anonymous custom element, allowing Aurelia to apply its behavior to the existing DOM structure.

2. Component Flexibility: The component parameter in enhance can be a custom element class, a class instance, or an object literal. If a class is provided, it's instantiated by Aurelia's dependency injection container, which can be either provided or automatically created.

3. Host Element: The host is typically an existing DOM node that is not yet under Aurelia's control. It's crucial to note that enhance ' neither detaches nor attaches the hostto the DOM. Existing event handlers on thehost` or its descendants remain unaffected.

4. Controller Deactivation: an enhance call results in an application root that requires manual deactivation or integration into an existing controller hierarchy for automatic framework management.

Example of deactivating an application root:

Enhancing During Application Startup

Enhance can be particularly useful during application startup, especially when integrating Aurelia into an existing web page or alongside other frameworks.

Let's create an index.html file containing some HTML markup you would encounter if you generated an Aurelia application using npx makes aurelia or other means.

Pay attention to the contents of the <body> as there is a container called app as well as some HTML tags <my-app>

Now, let's enhance our application by using the enhanceAPI inside of main.ts

Or if your component has one of its lifecycle return a promise:

We first wrap our async code in an anonymous async function. This allows us to catch errors and throw them to the console if enhancement fails, but take note of the enhance call itself. We supply the host element (in our case, it's a DIV with an ID of app as the host).

Above our enhance call, we register our main component, MyApp, the initial component our application will render.

This approach will work for existing applications as well. Say you have a WordPress website and want to create an Aurelia application on a specific page. You could create a container and pass the element to the host on the enhance call.

Enhancing on the fly within components

While using the enhance during registration, the enhance API is convenient for situations where you want to control how an Aurelia application is enhanced. There are times when you want to enhance HTML programmatically from within components. This may be HTML loaded from the server or elements created on the fly.

In the following example, we query our markup for an item-list element and insert some Aurelia-specific markup into it (a repeater).

As you can see, we are dynamically injecting some HTML into an existing element. Because this is being done after Aurelia has already compiled the view, it would not work. This is why we must call enhance to tell Aurelia to parse our inserted HTML.

You can use this approach to enhance HTML inserted into the page after initial compilation, which is perfect for server-generated code.

The navigation model can be thought of as view-friendly version of the configured routes. It provides similar information as of the configured routes with some additional data to it. This is typically useful when you want to create navigation menu from the already registered/configured routes in the router, without necessarily duplicating the data. The information takes the following shape.

Note that apart from , all other properties of the route object are same as the corresponding configured route.

This section provides example of how to use navigation model while discussing different aspects of it.

Create a navigation menu using a navigation model

The following example shows how to create a navigation menu using the info from the navigation model.

In this example, we are using a custom element named nav-bar. In the custom element we inject an instance of IRouteContext and we grab the navigation model from the routing context.

Then the information from the model is used in the view to create the navigation menu.

It additionally shows that from the NavBar#binding, INavigationModel#resolve() is awaited. This is recommended, when dealing with async route configuration. This allows all the promises to be resolved and thereafter building the navigation information correctly.

Using the isActive property

The isActive property is true when this route is currently active (loaded), and otherwise it is false. A typical use-case for this property is to apply or remove the "active" style to the links, depending on if the link is active or not. You can see this in the following example where a new .active class is added and that is bound to the isActive property.

You can see this in action below.

Excluding routes from the navigation model

By default, all configured routes are added to the navigation model. However, there might be routes which is desired to be excluded from the navigation model; for example: a fallback route for un-configured routes. To this end, a route can be configured with nav: false to instruct the router not to included it in the navigation model.

You see this in action in the example below.

Disabling navigation model

If you are not creating a menu using the navigation model, you can also deactivate the navigation model by setting false to the useNavigationModel . Doing so, will set the IRouteContext#navigationModel to null and skip further processing.

Testing custom attributes in Aurelia is analogous to testing components, with the primary difference being that custom attributes do not have a view template. They are, however, responsible for modifying the behavior or appearance of existing DOM elements. By leveraging the same testing techniques used for components, we can effectively validate the functionality of our custom attributes.

Example Custom Attribute

Let's consider a ColorSquareCustomAttribute that we previously created. This attribute applies a color border and sets the size of an element, resulting in a square of uniform dimensions with a colored background.

Testing the Custom Attribute

We will now write tests to ensure that the ColorSquareCustomAttribute behaves as expected when applied to an element.

Test Setup

Before writing tests, ensure that your test environment is properly configured. The setup for testing custom attributes is the same as for components, so refer to the section.

Writing Tests

Create a test file for your custom attribute, such as color-square.spec.ts, and use the following example as a guide:

In the first test, we verify that the default size and color are applied to an element when the custom attribute is used without any bindings. In the second test, we bind the color and size properties and then change the color to ensure the colorChanged method updates the element's style as expected.

Testing Approach

As with components, we use createFixture to set up our test environment. The first argument is the HTML view where we use our custom attribute. The second argument is the view model, which can define values to bind in our view model if needed. The third argument specifies any dependencies required by our tests, such as custom elements, value converters, or attributes.

Conclusion

Testing custom attributes in Aurelia 2 is essential to ensure they correctly manipulate DOM elements as intended. By setting up a proper testing environment, creating fixtures, and writing assertions, we can confidently verify that our custom attributes perform their duties correctly. Always remember to clean up your tests to maintain a pristine testing state.

Conditional rendering in Aurelia 2 is a powerful feature that lets you create dynamic interfaces that respond to your application's state. You can conditionally include or exclude parts of your view using boolean expressions. This guide will walk you through the different techniques provided by Aurelia to manage conditional content.

Using if.bind

The if.bind directive allows you to conditionally add or remove elements from the DOM based on the truthiness of the bound expression.

When the bound value evaluates to false, Aurelia removes the element and its descendants from the DOM. This process includes the destruction of custom elements, detaching of events, and cleanup of any associated resources, which is beneficial for performance and memory management.

Consider an application where you want to display a loading message while data is being fetched:

<div if.bind="isLoading">Loading...</div>

The isLoading variable controls the presence of the div in the DOM. When it's true, the loading message appears; when false, the message is removed.

Complementing if.bind with else

Aurelia enables if/else structures in the view, similar to conditional statements in JavaScript. The else binding must immediately follow an element with if.bind:

<div if.bind="user.isAuthenticated">Welcome back, ${user.name}!</div>
<div else>Please log in.</div>

This snippet displays a welcome message for authenticated users and a login prompt for others.

<custom-element if="value.bind: canShowElement; cache: false"></custom-element>

Performance Considerations

Be mindful that if.bind modifies the DOM structure, which can trigger reflow and repaint processes in the browser. For applications with extensive DOM manipulation, this may become a performance bottleneck. Optimize your usage of if.bind by minimizing the frequency and complexity of conditional rendering operations.

Employing show.bind

The show.bind directive offers an alternative approach to conditional rendering. Instead of adding or removing elements from the DOM, it toggles their visibility. This is akin to applying display: none; in CSS—the element remains in the DOM but is not visible to the user.

<div show.bind="isDataLoaded">Data loaded successfully!</div>

Here, isDataLoaded dictates the visibility of the message. When false, the message is hidden; when true, it is shown. All bindings and events remain intact since the element is not removed from the DOM.

Leveraging switch.bind

For more complex conditional rendering cases, such as when dealing with enumerated values, switch.bind is the ideal choice. It offers a clean, semantic way to handle multiple conditions by mimicking the switch statement in JavaScript.

For instance, given an enumeration of order statuses:

enum Status {
  Received   = 'received',
  Processing = 'processing',
  Dispatched = 'dispatched',
  Delivered  = 'delivered',
  Unknown    = 'unknown',
}

Displaying a message based on the order status with if.bind can become unwieldy. Instead, switch.bind offers a concise and clear approach:

<template switch.bind="orderStatus">
  <span case="received">Order received.</span>
  <span case="processing">Processing your order.</span>
  <span case="dispatched">On the way.</span>
  <span case="delivered">Delivered.</span>
  <span default-case>Status unknown.</span>
</template>

This structure allows for a straightforward mapping between the status and the corresponding message. The default-case acts as a catch-all for any status not explicitly handled.

Grouping Cases

You can bind an array of values to a case, thus grouping multiple conditions:

<template switch.bind="orderStatus">
  <span case.bind="['received', 'processing']">Order is being processed.</span>
  <span case="dispatched">On the way.</span>
  <span case="delivered">Delivered.</span>
</template>

This will display "Order is being processed." for both Received and Processing statuses.

Fall-Through Behavior

The switch construct in Aurelia supports fall-through logic similar to JavaScript's switch:

<template switch.bind="orderStatus">
  <span case="received" fall-through.bind="true">Order received.</span>
  <span case="processing">Order is being processed.</span>
  <!-- Other cases -->
</template>

When orderStatus is Received, both the "Order received." and "Order is being processed." messages will be displayed because of the fall-through attribute.

Advanced Scenarios with switch.bind

Aurelia's switch.bind can accommodate various advanced use cases, making it a versatile tool for conditional rendering. Below are examples of such scenarios:

Using switch.bind with Static Expressions

You can use switch.bind with a static expression, while the case.bind attributes feature more dynamic conditions:

<template repeat.for="num of 100">
  <template switch.bind="true">
    <span case.bind="num % 3 === 0 && num % 5 === 0">FizzBuzz</span>
    <span case.bind="num % 3 === 0">Fizz</span>
    <span case.bind="num % 5 === 0">Buzz</span>
  </template>
</template>

This example iterates over numbers 0 to 99 and applies the FizzBuzz logic, displaying "Fizz", "Buzz", or "FizzBuzz" depending on whether the number is divisible by 3, 5, or both.

Conditional Slot Projection with switch.bind

switch.bind can be combined with au-slot to project content into custom elements conditionally:

<template as-custom-element="foo-bar">
  <au-slot name="s1"></au-slot>
</template>

<foo-bar>
  <template au-slot="s1" switch.bind="status">
    <span case="received">Order received.</span>
    <span case="dispatched">On the way.</span>
    <span case="processing">Processing your order.</span>
    <span case="delivered">Delivered.</span>
  </template>
</foo-bar>

In this case, the custom element foo-bar will project different messages based on the status value.

Nesting switch.bind

switch.bind can be nested within itself for complex conditional logic:

<template>
  <let day.bind="2"></let>
  <template switch.bind="status">
    <span case="received">Order received.</span>
    <span case="dispatched">On the way.</span>
    <span case="processing">Processing your order.</span>
    <span case="delivered" switch.bind="day">
      Expected to be delivered
      <template case.bind="1">tomorrow.</template>
      <template case.bind="2">in 2 days.</template>
      <template default-case>in a few days.</template>
    </span>
  </template>
</template>

This example demonstrates how you can use nested switch.bind statements to handle multiple levels of conditional rendering.

Restrictions on case Usage

The case attribute must be used within the context of a switch and should be its direct child. The following are examples of incorrect and unsupported usages:

<!-- Incorrect: `case` outside of `switch` context -->
<span case="foo"></span>

<!-- Incorrect: `case` not a direct child of `switch` -->
<template switch.bind="status">
  <template if.bind="someCondition">
    <span case="delivered">Delivered</span>
  </template>
</template>

These examples will either throw an error or result in unexpected behavior. If you need to support a use case like this, consider reaching out to the Aurelia team.

By exploring these advanced scenarios, you can harness the full potential of switch.bind to address complex conditional rendering needs in your Aurelia applications. Remember to adhere to the guidelines and limitations to ensure proper functionality and maintainability.

Context

Sometimes you will see the following template in an Aurelia application:

<input value.bind="message">

Aurelia understands that value.bind="message" means value.two-way="message", and later creates a two way binding between view model message property, and input value property. How does Aurelia know this?

By default, Aurelia is taught how to interpret a bind binding command on a property of an element via a Attribute Syntax Mapper. Application can also tap into this class to teach Aurelia some extra knowledge so that it understands more than just value.bind on an <input/> element.

Examples

You may sometimes come across some custom input element in a component library, some examples are:

• Microsoft FAST text-field element: https://explore.fast.design/components/fast-text-field

• Ionic ion-input element: https://ionicframework.com/docs/api/input

• Polymer paper-input element: https://www.webcomponents.org/element/@polymer/paper-input

• and many more...

Regardless of the lib choice an application takes, what is needed in common is the ability to have a concise syntax to describe the two way binding intention with those custom elements. Some examples for the above custom input elements:

<fast-text-field value.bind="message">
<ion-input value.bind="message">
<paper-input value.bind="message">

should be treated as:

<fast-text-field value.two-way="message">
<ion-input value.two-way="message">
<paper-input value.two-way="message">

In the next section, we will look into how to teach Aurelia such knowledge.

Using the Attribute Syntax Mapper

As mentioned earlier, the Attribute Syntax Mapper will be used to map value.bind into value.two-way. Every Aurelia application uses a single instance of this class. The instance can be retrieved via the injection of interface IAttrMapper, like the following example:

import { inject, IAttrMapper } from '@aurelia/runtime-html';

@inject(IAttrMapper)
export class MyCustomElement {
  constructor(attrMapper) {
    // do something with the attr mapper
  }
}

After grabbing the IAttrMapper instance, we can use the method useTwoWay(fn) of it to extend its knowledge. Following is an example of teaching it that the bind command on value property of the custom input elements above should be mapped to two-way:

attrMapper.useTwoWay(function(element, property) {
  switch (element.tagName) {
    // <fast-text-field value.bind="message">
    case 'FAST-TEXT-FIELD': return property === 'value';
    // <ion-input value.bind="message">
    case 'ION-INPUT': return property === 'value';
    // <paper-input value.bind="message">
    case 'PAPER-INPUT': return property === 'value';
    // let other two way mapper check the validity
    default:
      return false;
  }
})

Combining the attribute syntax mapper with the node observer locator

Teaching Aurelia to map value.bind to value.two-way is the first half of the story. The second half is about how we can teach Aurelia to observe the value property for changes on those custom input elements. We can do this via the Node Observer Locator. Every Aurelia application uses a single instance of this class, and this instance can be retrieved via the injection of interface INodeObserverLocator like the following example:

import { inject, INodeObserverLocator } from '@aurelia/runtime-html';

@inject(INodeObserverLocator)
export class MyCustomElement {
  constructor(nodeObserverLocator) {
    // do something with the locator
  }
}

After grabbing the INodeObserverLocator instance, we can use the method useConfig of it to extend its knowledge. Following is an example of teaching it that the value property, on a <fast-text-field> element could be observed using change event:

nodeObserverLocator.useConfig('FAST-TEXT-FIELD', 'value', { events: ['change' ] });

Similarly, examples for <ion-input> and <paper-input>:

nodeObserverLocator.useConfig('ION-INPUT', 'value', { events: ['change' ] });
nodeObserverLocator.useConfig('PAPER-INPUT', 'value', { events: ['change' ] });

nodeObserverLocator.useConfig({
  'FAST-TEXT-FIELD': {
    value: { events: ['change'] }
  },
  'ION-INPUT': {
    value: { events: ['change'] }
  },
  'PAPER-INPUT': {
    value: { events: ['changer'] }
  }
})

Combining the examples in the two sections above into some more complete code block example, for Microsoft FAST components:

import { inject, IContainer, IAttrMapper, INodeObserverLocator, AppTask, Aurelia } from 'aurelia';

Aurelia
  .register(
    AppTask.creating(IContainer, container => {
      const attrMapper = container.get(IAttrMapper);
      const nodeObserverLocator = container.get(INodeObserverLocator);
      attrMapper.useTwoWay((el, property) => {
        switch (el.tagName) {
          case 'FAST-TEXT-FIELD': return property === 'value';
          case 'FAST-TEXT-AREA': return property === 'value';
          case 'FAST-SLIDER': return property === 'value';
          // etc...
        }
      });
      nodeObserverLocator.useConfig({
        'FAST-TEXT-FIELD': {
          value: { events: ['change'] }
        },
        'FAST-TEXT-AREA': {
          value: { events: ['change'] }
        },
        'FAST-SLIDER': {
          value: { events: ['change'] }
        }
      });
    })
  )
  .app(class MyApp {})
  .start();

And with the above, your Aurelia application will get two way binding flow seamlessly:

<fast-text-field value.bind="message"></fast-text-field>
<fast-text-area value.bind="description"></fast-text-area>
<fast-slider value.bind="fontSize"></fast-slider>

Aurelia provides a higher-level API for simplifying some common tasks to handle a common reactivity intent in any application: run a function again when any of its dependencies have been changed.

This function is called an effect, and the dependencies are typically tracked when they are accessed (read) inside this effect function. The builtin @observable decorator from Aurelia enables this track-on-read capability by default.

Aurelia provides a few ways to declare a dependency for an effect function. The most common one is the track "on read" of a reactive property.

In the following example:

class MouseTracker {
  @observable
  coord = [0, 0];
}

The property coord of a MouseTracker instance will be turned into a reactive property and is also aware of effect function dependency tracking.

The effect APIs are provided via the default implementation of the interface IObservation, which can be retrieved like one of the following examples:

• Getting from a container directly:

import { IObservation } from 'aurelia';

...
const observation = someContainer.get(IObservation);

• Getting through injection:

import { inject, IObservation } from 'aurelia';

@inject(IObservation)
class MyElement {
  constructor(observation) {
    // ...
  }
}

Or

class MyElement {
  constructor(@IObservation readonly observation) {
    // ...
  }
}

After getting the observation object, there are two APIs that can be used to created effects as described in the following sections:

Watch effect

Watch effect is a way to describe a getter based observation of an object. An example to create watch effect is per the following:

import { inject, IObservation } from 'aurelia';

@inject(IObservation)
class PersonalInfo {
  constructor(observation) {
    const effect = observation.watch(this.primaryInfo, (primaryInfo) => primaryInfo.name, function nameChanged(newName, oldName) {
      // do something with name
    });

    // effect.stop() later when necessary
  }
}

Note that the effect function will be run immediately. If you do not want to run the callback immediately, pass an option immediate: false as the 4th parameter:

observation.watch(obj, getter, callback, { immediate: false });

By default, a watch effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation instance has stopped. To stop/destroy an effect, call the method stop() on the effect object.

Run effect

Run effects describe a function to be called repeatedly whenever any dependency tracked inside it changes.

Creating an Effect

After getting an IObservation instance, a run effect can be created via the method run of it:

const effect = observation.run(() => {
  // code here
});

Note that the effect function will be run immediately.

By default, a effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation instance has stopped. To stop/destroy an effect, call the method stop() on the effect object:

const effect = IObservation.run(() => {
  // code here
});

// stop the effect like this
effect.stop();

Effect examples

The following section gives some examples of what it looks like when combining @observable and run effect.

Creating a run effect that logs the user mouse movement on the document

import { inject, IObservation, observable } from 'aurelia'

class MouseTracker {
  @observable coord = [0, 0]; // x: 0, y: 0 is the default value
}

// Inside an application:
@inject(IObservation)
class App {
  constructor(observation) {
    const mouseTracker = new MouseTracker();

    document.addEventListener('mousemove', (e) => {
      mouseTracker.coord = [e.pageX, e.pageY]
    });

    observation.run(() => {
      console.log(mouseTracker.coord)
    });
  }
}

Now whenever the user moves the mouse around, a log will be added to the console with the coordinate of the mouse.

Creating a run effect that sends a request whenever user focus/unfocus the browser tab

import { inject, IObservation, observable } from 'aurelia'

class PageActivity {
  @observable active = false
}

// Inside an application:
@inject(IObservation)
class App {
  constructor(observation) {
    const pageActivity = new PageActivity();

    document.addEventListener(visibilityChange, (e) => {
      pageActivity.active = !document.hidden;
    });

    observation.run(() => {
      fetch('my-game/user-activity', { body: JSON.stringify({ active: pageActivity.active }) })
    });
  }
}

You might know router hooks as guards in other routers. Their role is to determine how components are loaded. They're pieces of code that are run in between.

The lifecycle hooks sharing API can be used to define reusable hook logic. In principle, nothing new needs to be learned: their behavior is the same as described in Lifecycle Hooks, with the only difference being that the view model instance is added as the first parameter.

If you worked with Aurelia 1, you might know these by their previous name: router pipelines.

Creating a custom lifecycle hook

import Aurelia, { lifecycleHooks } from 'aurelia';
import { Parameters, Navigation, RouterConfiguration, RoutingInstruction } from '@aurelia/router';

@lifecycleHooks()
class NoopAuthHandler {
    canLoad(viewModel, params: Parameters, instruction: RoutingInstruction, navigation: Navigation) { 
        return true; 
    }
}

Aurelia
    .register(RouterConfiguration, NoopAuthHandler)
    .app(component)
    .start();

Shared lifecycle hook logic can be defined by implementing a router lifecycle hook on a class with the @lifecycleHooks() decorator. This hook will be invoked for each component where this class is available as a dependency. This can be either via a global registration or via one or more component-local registrations, similar to how, e.g. custom elements and value converters are registered.

In the example above, we register NoopAuthHandler globally, which means it will be invoked for each routed component and return true each time, effectively changing nothing.

Anatomy of a lifecycle hook

While lifecycle hooks are indeed their own thing independent of the components you are routing to, the functions are basically the same as you would use inside an ordinary component.

This is the contract for ordinary route lifecycle hooks for components:

import { Parameters, IRouteableComponent, Navigation, RoutingInstruction } from '@aurelia/router';

class MyComponent implements IRouteableComponent {
  canLoad(params: Parameters, instruction: RoutingInstruction, navigation: Navigation);
  loading(params: Params, instruction: RoutingInstruction, navigation: Navigation);
  canUnload(instruction: RoutingInstruction, navigation: Navigation);
  unloading(instruction: RoutingInstruction, navigation: Navigation);
}

And this is the contract for shared lifecycle hooks

import { lifecycleHooks } from 'aurelia'; 
import { Parameters, Navigation, RoutingInstruction } from '@aurelia/router';

@lifecycleHooks()
class MySharedHooks {
  canLoad(viewModel, params: Parameters, instruction: RoutingInstruction, navigation: Navigation);
  loading(viewModel, params: Params, instruction: RoutingInstruction, navigation: Navigation);
  canUnload(viewModel, instruction: RoutingInstruction, navigation: Navigation);
  unloading(viewModel, instruction: RoutingInstruction, navigation: Navigation);
  unload(viewModel, instruction: RoutingInstruction, navigation: Navigation);
}

The only difference is the addition of the first viewModel parameter. This comes in handy when you need the component instance since the this keyword won't give you access like in ordinary component methods.

Restricting hooks to specific components

When dealing with route hooks, you might only want to apply those to specific components. Imagine an authentication workflow where you would want to allow unauthenticated users to access your login or contact page.

To do this, we can specify our route hook as a dependency in the component via the static dependencies property, which takes an array of one or more dependencies.

import { IRouteableComponent } from "@aurelia/router";
import { AuthHook } from './route-hook';

export class SettingsPage implements IRouteableComponent {
    static dependencies = [ AuthHook ];
}

Whenever someone tries to route to the SettingsPage component, they will trigger the authentication hook you created. This per-component approach allows you to target the needed components you want behind a route hook.

Multiple hooks per component/class

Shared lifecycle hooks run in parallel with (but are started before) component instance hooks, and multiple of the same kind can be applied per component. When multiple hooks are registered per component, they are invoked in the registration order.

import { lifecycleHooks } from 'aurelia';

@lifecycleHooks()
class Log1 {
    async loading() {
        console.log('1.start');
        await Promise.resolve();
        console.log('1.end');
    }
}

@lifecycleHooks()
class Log2 {
    async loading() {
        console.log('2.start');
        await Promise.resolve();
        console.log('2.end');
    }
}

export class MyComponent {
    static dependencies = [Log1, Log2];

    async loading() {
        console.log('3.start');
        await Promise.resolve();
        console.log('3.end');
    }
}

// Will log, in order:
// 1.start
// 2.start
// 3.start
// 1.end
// 2.end
// 3.end

It is also permitted to define more than one hook per shared hook class:

@lifecycleHooks()
export class LifecycleLogger {
    canLoad(viewModel, params, instruction, navigation) {
        console.log(`invoking canLoad on ${instruction.component.name}`);
        return true;
    }

    loading(viewModel, params, instruction, navigation) {
        console.log(`invoking load on ${instruction.component.name}`);
    }
}

Every component instance has a lifecycle that you can tap into. This makes it easy for you to perform various actions at particular times.

For example, you may want to execute some code as soon as your component properties are bound but before the component is first rendered. Or, you may want to run some code to manipulate the DOM as soon as possible after your element is attached to the document.

Constructor

When the framework instantiates a component, it calls your class's constructor, just like any JavaScript class. This is the best place to put your basic initialization code that is not dependent on bindable properties.

Furthermore, the constructor is where you handle the injection of dependencies using dependency injection. You will learn about DI in the dependency injection section, but here is a basic example of where the constructor is used.

import { IRouter } from '@aurelia/router-lite';

export class MyComponent {
    constructor(@IRouter readonly router: IRouter) {
    }
}

Hydrating

The "hydrating" hook allows you to add contextual DI registrations (to controller.container) to influence which resources are resolved when the template is compiled. It is still considered part of "construction".

export class MyComponent {
    hydrating(controller: IContextualCustomElementController<this>) {

    }
}

Hydrated

The "hydrated" hook is a good place to influence how child components are constructed and rendered contextually. It runs synchronously after the definition is compiled (which happens synchronously after hydrating) and, like hydrating, can still be considered part of "construction".

export class MyComponent {
    hydrated(controller: IContextualCustomElementController<this>) {

    }
}

Created

The "created" hook is the last hook that can be considered part of "construction". It is called (synchronously) after this component is hydrated, which includes resolving, compiling and hydrating child components. In terms of the component hierarchy, the created hooks execute bottom-up, from child to parent (whereas hydrating and hydrated are all top-down). This is also the last hook that runs only once per instance.

Here you can perform any last-minute work that requires having all child components hydrated, which might affect the bind and attach lifecycles.

export class MyComponent {
    created(controller: IContextualCustomElementController<this>) {

    }
}

Binding

If your component has a method named "binding", then the framework will invoke it after the bindable properties of your component are assigned. In terms of the component hierarchy, the binding hooks execute top-down, from parent to child, so your bindables will have their values set by the owning components, but the bindings in your view are not yet set.

You can optionally return a Promise either making the method asynchronous or creating a promise object. If you do so, it will suspend the binding and attaching of the children until the promise is resolved. This is useful for fetching/save of data before rendering.

export class MyComponent {
    binding(initiator: IHydratedController, parent: IHydratedController, flags: LifecycleFlags) {

    }
}

Bound

If your component has a method named "bound", then the framework will invoke it when the bindings between your component and its view have been set. This is the best place to do anything that requires the values from let, from-view or ref bindings to be set.

export class MyComponent {
    bound(initiator: IHydratedController, parent: IHydratedController, flags: LifecycleFlags) {

    }
}

Attaching

If your component has a method named "attaching, " the framework will invoke it when it has attached the component's HTML element. You can queue animations and/or initialize certain 3rd party libraries.

export class MyComponent {
    attaching(initiator: IHydratedController, parent: IHydratedController, flags: LifecycleFlags) {

    }
}

Attached

If your component has a method named "attached", the framework will invoke it when it has attached the current component and all of its children. In terms of the component hierarchy, the attached hooks execute bottom-up.

export class MyComponent {
    attached(initiator: IHydratedController, flags: LifecycleFlags) {

    }
}

Detaching

If your component has a method named "detaching", then the framework will invoke it when removing your HTML element from the document. In terms of the component hierarchy, the detaching hooks execute bottom-up.

export class MyComponent {
    detaching(initiator: IHydratedController, parent: IHydratedController, flags: LifecycleFlags) {

    }
}

Unbinding

If your component has a method named "unbinding, " the framework will invoke it when it has fully removed your HTML element from the document. In terms of the component hierarchy, the unbinding hooks execute bottom-up.

export class MyComponent {
    unbinding(initiator: IHydratedController, parent: IHydratedController, flags: LifecycleFlags) {

    }
}

Dispose

If your component has a method named "dispose", then the framework will invoke it when the component is to be cleared from memory completely. It may be called, for example, when a component is in a repeater, and some items are removed that are not returned to the cache.

export class MyComponent {
    dispose() {
    }
}

Lifecycle Hooks

The lifecycle hooks API supports all of the above lifecycle methods. Using the lifecycleHooks decorator, you can perform actions at various points of the component lifecycle. Because the router uses lifecycle hooks, they are documented here in the router section, but do not require the use of the router to use (except for router-specific hooks).

Others

For <au-compose>, there are extra lifecycle hooks that are activate/deactivate. Refers to dynamic composition doc for more details.

Testing components in Aurelia 2 is a straightforward process thanks to the framework's design and the utilities provided by the @aurelia/testing package. This guide will walk you through the steps to test your components effectively, ensuring they work as expected within the context of a view.

In Aurelia, a component typically consists of a view (HTML) and a view model (JavaScript or TypeScript). To ensure the quality and correctness of your components, you should write tests that cover both aspects. Testing components involves checking that the view renders correctly with given data and that the view model behaves as intended when interacting with the view.

Testing Strategy

When testing components, we will focus on integration tests that involve both the view and view model. This approach allows us to verify the component as a whole, as it would function within an Aurelia application.

Example Component

For demonstration purposes, we will use a simple PersonDetail component with bindable properties name and age.

import { bindable } from 'aurelia';

export class PersonDetail {
    @bindable name: string;
    @bindable age: number;
}

<template>
    <p>Person is called ${name} and is ${age} years old.</p>
</template>

Writing the Test

We aim to test that the PersonDetail component renders the expected text when provided with name and age properties.

Test Setup

Before writing the test, ensure your environment is correctly set up for testing. Refer to the Overview section for details on how to initialize the Aurelia testing platform.

Test Implementation

Create a test file for your component, such as person-detail.spec.ts, and implement your tests using the syntax of your chosen test runner. The following example uses Jest:

import { createFixture } from '@aurelia/testing';
import { PersonDetail } from './person-detail';
import { bootstrapTestEnvironment } from './path-to-your-initialization-code';

describe('PersonDetail component', () => {
  beforeAll(() => {
    // Initialize the test environment before running the tests
    bootstrapTestEnvironment();
  });

  it('renders the name and age correctly', async () => {
    const { component, startPromise, tearDown } = createFixture(
      '<person-detail name.bind="testName" age.bind="testAge"></person-detail>',
      class App {
        testName = 'Alice';
        testAge = 30;
      },
      [PersonDetail]
    );

    await startPromise;

    expect(component.textContent).toContain('Person is called Alice and is 30 years old.');

    await tearDown();
  });

  // Additional tests...
});

In this example, createFixture is used to instantiate the component with a test context, binding name and age to specified values. We then assert that the component's text content includes the correct information. After the test completes, tearDown cleans up the component instance to avoid memory leaks and ensure test isolation.

Testing Components with Dependencies

If your component has dependencies, such as services or other custom elements, you'll need to register these within the Aurelia testing container.

Example with a Dependency

Assume PersonDetail depends on a PersonFormatter service:

import { inject } from 'aurelia';
import { PersonFormatter } from './person-formatter';

@inject(PersonFormatter)
export class PersonDetail {
    @bindable name: string;
    @bindable age: number;

    constructor(private personFormatter: PersonFormatter) {}

    get formattedDetails() {
        return this.personFormatter.format(this.name, this.age);
    }
}

To test this component, you can create a mock PersonFormatter and register it with the Aurelia container:

import { createFixture, Registration } from '@aurelia/testing';
import { PersonDetail } from './person-detail';
import { PersonFormatter } from './person-formatter';

describe('PersonDetail with PersonFormatter dependency', () => {
  it('formats the details using PersonFormatter', async () => {
    const mockPersonFormatter = {
      format: jest.fn().mockImplementation((name, age) => `Formatted: ${name}, age ${age}`),
    };

    const { component, startPromise, tearDown } = createFixture(
      '<person-detail name.bind="testName" age.bind="testAge"></person-detail>',
      class App {
        testName = 'Bob';
        testAge = 40;
      },
      [PersonDetail],
      [Registration.instance(PersonFormatter, mockPersonFormatter)]
    );

    await startPromise;

    expect(mockPersonFormatter.format).toHaveBeenCalledWith('Bob', 40);
    expect(component.textContent).toContain('Formatted: Bob, age 40');

    await tearDown();
  });
});

In the test above, we use Jest's jest.fn() to create a mock implementation of PersonFormatter. We then verify that the mock's format method is called with the correct arguments and that the component's text content includes the formatted details.

Conclusion

Testing Aurelia components involves setting up a test environment, creating fixtures, and writing assertions based on your expectations. By following these steps and best practices, you can ensure that your components are reliable and maintainable. Remember to clean up after your tests to maintain a clean test environment and to avoid any side effects between tests.

Template references in Aurelia 2 provide a powerful and flexible way to connect your HTML templates with your JavaScript or TypeScript view models. Using the ref attribute, you can easily identify and interact with specific parts of your template, making it more efficient to manipulate the DOM or access template data.

Declaring Template References

Basic Usage

Add the ref attribute to an HTML element within your template to create a template reference. This marks the element as a reference, allowing you to access it directly in your view model.

<input type="text" ref="myInput" placeholder="First name">

In this example, myInput references the input element, which can be used both in the template and the corresponding view model.

Accessing Reference in Template

Template references are immediately available within the template. For instance, you can display the value of the input field as follows:

<p>${myInput.value}</p>

This binding displays the current value of the input field dynamically.

Accessing Reference in View Model

To access the referenced element in the view model, declare a property with the same name as the reference. For TypeScript users, it's important to define the type of this property for type safety.

export class MyApp {
  private myInput: HTMLInputElement;

  // Additional view model logic here
}

Advanced Usage

Working with Custom Elements and Attributes

Aurelia's ref attribute is not limited to standard HTML elements. It can also be used with custom elements and attributes to reference their component instances (view-models) or controllers.

Custom Element Instance Use component.ref="expression" to create a reference to a custom element's component instance (view-model). This was known as view-model.ref in Aurelia v1.

<my-custom-element component.ref="customElementVm"></my-custom-element>

Custom Attribute Instance Similarly, custom-attribute.ref="expression" can reference a custom attribute's component instance (view-model).

<div my-custom-attribute custom-attribute.ref="customAttrVm"></div>

Controller Instance For more advanced scenarios, controller.ref="expression" creates a reference to a custom element's controller instance.

<my-custom-element controller.ref="customElementController"></my-custom-element>

Practical Applications

Template references are incredibly useful for integrating with third-party libraries or when direct DOM manipulation is necessary. Instead of using traditional JavaScript queries to find elements, template references provide a more straightforward, framework-integrated approach.

When dealing with Aurelia and custom elements, we tend to use the @bindable decorator to define bindable properties. The bindable properties are members of the underlying view model class. However, there are cases where we want to work directly with attributes of the DOM elements.

For example, we want an <input> element with a maxlength attribute and map a view model property to the attribute. Let us assume that we have the following view model class:

export class App {
  private inputMaxLength: number = 10;
  private input: HTMLInputElement;
}

Then, intuitively, we would write the following template:

<input maxlength.bind="inputMaxLength" ref="input">

This binds the value to the maxlength attribute of the <input> element. Consequently, the input.maxLength is also bound to be 10. Note that binding the value of the maxLength attribute also sets the value of the maxLength property of the input element. This happens because Aurelia, in the background, does the mapping for us.

On a broad level, this is what attribute mapping is about. This article provides further information about how it works and how to extend it.

How it works

To facilitate the attribute mapping, Aurelia uses IAttrMapper, which has information about how to map an attribute to a property. While creating property binding instructions from binding commands, it is first checked if the attribute is a bindable. If it is a bindable property, the attribute name (in kebab-case) is converted to the camelCase property name. However, the attribute mapper is queried for the target property name when it is not a bindable. If the attribute mapper returns a property name, then the property binding instruction is created with that property name. Otherwise, the standard camelCase conversion is applied.

If we want to bind a non-standard <input> attribute, such as fizz-buzz, we can expect the input.fizzBuzz property to be bound. This looks as follows.

<input fizz-buzz.bind="someValue" ref="input">

export class App {
  private someValue: number = 10;
  private input: HTMLInputElement;

  public attached(): void {
    console.log(this.input.fizzBuzz); // 10
  }
}

Extending the attribute mapping

The attribute mapping can be extended by registering new mappings with the IAttrMapper. The IAttrMapper provides two methods for this purpose. The .useGlobalMapping method registers mappings applicable for all elements, whereas the .useMapping method registers mapping for individual elements.

To this end, we can grab the IAttrMapper instance while bootstrapping the app and register the mappings (there is no restriction, however, on when or where those mappings are registered). An example might look as follows.

import {
  AppTask,
  Aurelia,
  IAttrMapper,
} from '@aurelia/runtime-html';

const au = new Aurelia();
au.register(
  AppTask.creating(IAttrMapper, (attrMapper) => {
    attrMapper.useMapping({
      'MY-CE': {
        'fizz-buzz': 'FizzBuzz',
      },
      INPUT: {
        'fizz-buzz': 'fizzbuzz',
      },
    });
    attrMapper.useGlobalMapping({
      'foo-bar': 'FooBar',
    });
  })
);

In the example above, we are registering a global mapping for foo-bar attribute to FooBar property, which will apply to all elements. We are also registering mappings for individual elements. Note that the key of the object is the nodeName of the element; thus, for an element, it needs to be the element name in upper case. In the example above, we map the fizz-buzz attribute differently for <input> and <my-ce> elements.

With this custom mapping registered, we can expect the following to work.

<input fizz-buzz.bind="42" foo-bar.bind="43" ref="input">
<my-ce fizz-buzz.bind="44" foo-bar.bind="45" ref="myCe"></my-ce>

export class App {
  private input: HTMLInputElement;
  private myCe: HTMLElement;

  public attached(): void {
    console.log(this.input.fizzbuzz); // 42
    console.log(this.input.FooBar); // 43
    console.log(this.myCe.FizzBuzz); // 44
    console.log(this.myCe.FooBar); // 45
  }
}

Use two-way binding for attribute

In addition to registering custom mappings, we can teach the attribute mapper when using two-way binding for an attribute. To this end, we can use the .useTwoWay method of the IAttrMapper. The .useTwoWay method accepts a predicate function determining whether the attribute should be bound in two-way mode. The predicate function receives the attribute name and the element name as parameters. If the predicate function returns true, then the attribute is bound in two-way mode, otherwise it is bound in to-view mode.

An example looks as follows.

import {
  AppTask,
  Aurelia,
  IAttrMapper,
} from '@aurelia/runtime-html';

const au = new Aurelia();
au.register(
  AppTask.creating(IAttrMapper, (attrMapper) => {
    // code omitted for brevity
    attrMapper.useTwoWay(
      (el, attr) => el.tagName === 'MY-CE' && attr == 'fizz-buzz'
    );
  })
);

In this example, we are instructing the attribute mapper to use two-way binding for fizz-buzz attribute of <my-ce> element. This means that the following will work.

<my-ce
    ref="myCe"
    foo-bar.bind="myCeFooBar"
    fizz-buzz.bind="myCeFizzBuzz"></my-ce>

myCeFizzBuzz: ${myCeFizzBuzz} myCeFooBar: ${myCeFooBar}

export class MyApp {
  private myCeFooBar: any = 'fizz';
  private myCeFizzBuzz: any = '2424';
  private myCe: HTMLElement & { FooBar?: string; FizzBuzz?: string };
  public attached() {
    setInterval(() => {
      // This change will trigger a change for the myCeFizzBuzz property
      this.myCe.FizzBuzz = Math.ceil(Math.random() * 10_000).toString();

      // This change won't trigger a change for the myCeFooBar property
      this.myCe.FooBar = Math.ceil(Math.random() * 10_000).toString();
    }, 1000);
  }
}

Live example

A similar example can be seen in action below.

Routing with Aurelia feels like a natural part of the framework. It can easily be implemented into your applications in a way that feels familiar if you have worked with other frameworks and library routers. Here is a basic example of routing in an Aurelia application using router-lite.

The following getting started guide assumes you have an Aurelia application already created. If not, consult our Quick Start to get Aurelia installed in minutes.

Installation

npm i @aurelia/router-lite

Configure the router-lite

To use the router-lite, we have to register it with Aurelia. We do this at the bootstrapping phase.

import Aurelia from 'aurelia';
import { RouterConfiguration } from '@aurelia/router-lite';
import { MyApp } from './my-app';

Aurelia
  .register(RouterConfiguration.customize({
      useUrlFragmentHash: true, // <-- enables the routing using the URL `hash`
    }))
  .app(MyApp)
  .start();

Create the routable components

For this example, we have a root component which is MyApp. And then we are going to define two routes for the root component, namely home and about.

Let us define these components first.

import { customElement } from '@aurelia/runtime-html';
import template from './home.html';

@customElement({ name: 'ho-me', template })
export class Home {
  private readonly message: string = 'Welcome to Aurelia2 router-lite!';
}

<h1>${message}</h1>

import { customElement } from '@aurelia/runtime-html';
import template from './about.html';

@customElement({ name: 'ab-out', template })
export class About {
  private readonly message = 'Aurelia2 router-lite is simple';
}

<h1>${message}</h1>

Configure the routes

With the routable components in place, let's define the routes. To this end, we need to add the route configurations to our root component MyApp.

import { customElement } from '@aurelia/runtime-html';
import { route } from '@aurelia/router-lite';
import template from './my-app.html';
import { Home } from './home';
import { About } from './about';

@route({
  routes: [
    {
      path: ['', 'home'],
      component: Home,
      title: 'Home',
    },
    {
      path: 'about',
      component: About,
      title: 'About',
    },
  ],
})
@customElement({ name: 'my-app', template })
export class MyApp {}

<nav>
  <a href="home">Home</a>
  <a href="about">About</a>
</nav>

<au-viewport></au-viewport>

There are couple of stuffs to note here. We start by looking at the configurations defined using the @route decorator where we list out the routes under the routes property in the configuration object in the @route decorator. The most important things in every route configurations are the path and the component properties. This instructs the router to use the defined component in the viewport when it sees the associated path.

The viewport is specified in the view (see my-app.html) by using the <au-viewport> custom element. For example, the router will use this element to display the Home component when it sees the / (the empty path) or the /home paths.

The nav>a elements are added to navigate from one view to another.

See this in action:

Using pushstate

If you have opened the demo then you can notice that the URL in the address bar or the URLs in the nav>a elements contains a # (example: /#home, /#about etc.). Depending on your project need and esthetics you may want to get rid of the #-character. To this end, you need set the useUrlFragmentHash to false, which is also the default.

Live examples

For the documentation of router-lite, many live examples are prepared. It is recommended to use the live examples as you read along the documentation. However, if you are feeling adventurous enough to explore the features by yourself, here is the complete collection of the live examples at your disposal.

Lambda expressions in Aurelia templates offer a concise and powerful way to include JavaScript-like functionality directly within your HTML using a subset of Arrow Function syntax. This feature enhances the expressiveness of Aurelia's templating engine, allowing for more inline, readable, and maintainable code.

Array methods with repeat.for

One of the most common scenarios will likely be calling Array methods on an array you're looping over using repeat.for.

Previously, to filter some array items in a repeater, you might have written something like this using a value converter:

While there is nothing wrong with value converters, and in some situations, they might be preferable (especially for testing), you can achieve the same thing without writing any additional code like this:

We are calling a callback function called isGood defined inside our template to determine if the item is filtered.

Filter and Sort

Observation-wise, Aurelia knows only to observe selected property of every item in items, as well as pos property of every selected item. This means changing the value of selected property of any item will result in the re-evaluation of the above expression. Changing the value of pos property of any selected item will also trigger the re-evaluation. Aurelia will also subscribe to the mutation of the array items to refresh this binding.

As we might have inside of a value converter, we use two Javascript functions, filter and sort — Aurelia's lambda expression support means we can chain these functions without needing to write any code in a view-model or value converter.

Event Callbacks

With arrow functions, we can express the following:

As the following:

As a result, .call is being deprecated in Aurelia as the lambda expression syntax allows us to handle this in a more JavaScript way.

Interpolation Expressions

Not only are lambda functions supported in a repeat.for, but we can also use them in interpolation expressions.

Map

Say you have an array of keywords for an item, and you want to display those as a comma-separated list. Previously, you would have used a value converter or function in your view model to achieve this task. Now, you can do it from within your templates.

Reduce

Another task might be to take an array of items (say, products in a cart) and then calculate the total. Once again, we might have previously used a value converter or computed getter for this task, but now we can use reduce in our template.

Valid Uses

While a broad syntax for lambda expressions is supported, here is a list of valid uses.

Invalid Uses

The following uses of lambda expressions are not supported in Aurelia templates.

Examples

Now we understand what lambda expressions are and how they can be used, here are some examples of how you might leverage them in your Aurelia applications.

Inline Array Transformation and Display

Transform and display an array of objects inline, such as a list of names.

Complex Object Filtering

Use lambda expressions for complex filtering, such as filtering based on multiple object properties.

Event Handling with Additional Context

Handle events with additional context passed to the event handler.

Nested Array Operations

Perform operations on nested arrays, such as displaying a flattened list of sub-items.

Combining Multiple Array Methods

Chain multiple array methods for data processing.

Using Reduce for Total Calculation

Calculate the total price of items in a shopping cart.

Creating a Comma-Separated List

Transform an array of objects into a comma-separated list.

Calculating an Aggregate Property

Use reduce to calculate an aggregate property, such as the average age.

Using includes for Conditional Rendering

Check if an array includes a certain value and conditionally render content.

Dynamic Class Assignment with includes

Assign a class to an element if an array includes a specific item.

Finding an Item with find

Display details of the first item that matches a condition.

Using find in Event Handling

Use find in an event handling expression to work with a specific item.

Nested Arrays with flat

Flatten a nested array and display its contents.

Displaying a Flattened List of Attributes

Use flat to create a flattened list of attributes from an array of objects.

Introduction

In many instances, when working with templated views in Aurelia, you will be approaching development from a reusability mindset. However, sometimes, you need a template for one specific application part. You could create a component for this, but it might be overkill. This is where local templates can be useful.

The example defines a template inside the my-app.html markup that can be used as a custom element. The name of the custom element, so defined, comes from the value of the as-custom-element attribute used on the template.

In this case, it is named as person-info. A custom element defined that way cannot be used outside the template that defines it; in this case, the person-info is, therefore, unavailable outside my-app. Thus, the name 'local template'.

Local templates can also optionally specify bindable properties using the <bindable> tag as shown above. Apart from property, other allowed attributes that can be used in this tag are attribute, and mode. In that respect, the following two declarations are synonymous.

Although it might be quite clear, it is worth reiterating that the value of the bindable attribute should not be camelCased or PascalCased.

Why use local templates

In essence, the local templates are similar to HTML-Only custom elements, with the difference that the local templates cannot be reused outside the defining custom element. Sometimes we need to reuse a template multiple times in a single custom element.

Creating a separate custom element for that is a bit overkill. Also, given that the custom element is only used in one single custom element, it might be optimized for that and not meant to be reused outside this context. The local templates are meant to promote that, whereas having a separate custom element makes it open for reuse in another context.

In short, it aims to reduce boilerplate code and promotes highly cohesive, better-encapsulated custom elements.

This means that the following is a perfectly valid example. Note that the local templates with the same name (foo-bar) are defined in different custom elements.

Features and pitfalls

Like anything, there is always an upside and downside: local templates are no different. While they can be a powerful addition to your Aurelia applications, you need to be aware of the caveats when using them, as you may encounter them.

Local templates are hoisted.

It is theoretically possible to go to an infinite level of nesting. That is, the following example will work. However, whether such composition is helpful depends on the use case.

Although it might provide a stronger cohesion, as the level of nesting grows, it might not be easy to work with. It is up to you to decide on a reasonable tradeoff while using local templates.

In this respect, a good thumb rule is to keep the local function analogy in mind.

Custom elements cannot contain only local templates

The following examples will cause a (jit) compilation error.

A local template always needs to be defined directly under the root element

The following example will cause a (jit) compilation error.

Local templates need to have a name

The following example will cause a (jit) compilation error.

Local template names need to be unique

The following example will cause a (jit) compilation error.

Bindable tags need to be under the local template root

The following example will cause a (jit) compilation error.

The property attribute on bindable tags is mandatory

The following example will cause a (jit) compilation error.

There are scenarios where we would like to transform the template provided by the usage-side. The 'processContent' hook lets us define a pre-compilation hook to make that transformation.

The signature of the hook function is as follows.

There are two important things to note here.

First is the node argument. It is the DOM tree on the usage-side for the custom element. For example, if there is a custom element named my-element, on which a 'processContent' hook is defined, and it is used somewhere as shown in the following markup, then when the hook is invoked, the node argument will provide the DOM tree that represents the following markup.

Then inside the hook this DOM tree can be transformed/mutated into a different DOM tree. The mutation can be addition/removal of attributes or element nodes.

Second is the return type boolean | void. Returning from this function is optional. Only an explicit false return value results in skipping the compilation (and thereby enhancing) of the child nodes in the DOM tree. The implication of skipping the compilation of the child nodes is that Aurelia will not touch those DOM fragments and will be kept as it is. In other words, if the mutated node contains custom elements, custom attributes, or template controllers, those will not be hydrated.

The platform argument is just the helper to have platform-agnostic operations as it abstracts the platform. Lastly the this argument signifies that the hook function always gets bound to the custom element class function for which the hook is defined.

The most straight forward way to define the hook is to use the processContent property while defining the custom-element.

Apart from this, there is also the @processContent decorator which can used class-level or method-level.

That's the API. Now let us say consider an example. Let us say that we want to create a custom elements that behaves as a tabs control. That is this custom element shows different sets of information grouped under a set of headers, and when the header is clicked the associated content is shown. To this end, we can conceptualize the markup for this custom element as follows.

The markup has 2 slots for the header and content projection. While using the tabs custom element we want to have the following markup.

Now note that there is no custom element named tab. The idea is to keep the usage-markup as much dev-friendly as possible, so that it is easy to maintain, and the semantics are quite clear. Also it is easy to refactor as now we know which parts belong together. To support this usage-syntax we will use the 'processContent' hook to rearrange the DOM tree, so that the nodes are correctly projected at the end. A prototype implementation is shown below.

Example transformation function for default [au-slot]

If you have used , you might have noticed that in order to provide a projection the usage of [au-slot] attribute is mandatory, even if the projections are targeted to the default au-slot. With the help of the 'processContent' hook we can workaround this minor inconvenience. The following is a sample transformation function that loops over the direct children under node and demotes the nodes without any [au-slot] attribute to a synthetic template[au-slot] node.

The CustomElement resource is a core concept in Aurelia 2, enabling developers to create encapsulated and reusable components. Understanding how to leverage the CustomElement API is crucial for building robust applications. In this documentation, we will delve into the usage of CustomElement and its methods, providing detailed examples and explanations.

CustomElement.for

This method retrieves the Aurelia controller associated with a DOM node. The controller offers access to the element's view-model, lifecycle, and other properties.

Usage Examples

Retrieving a Controller for the Current Node

Searching Parent Nodes for a Controller

Getting a Controller for a Named Custom Element

Retrieving a Controller Without Throwing an Error

Parameters

• node: The DOM Node for which to retrieve the controller.

• opts: An object with optional properties to customize the behavior of the method.

Return Value

Returns an instance of ICustomElementController or null/undefined, depending on the options provided and whether a controller is found.

CustomElement.define

The define method registers a class as a custom element in Aurelia.

Usage Examples

Defining a Custom Element with a Name

Defining a Custom Element with a Definition Object

Parameters

• nameOrDef: A string representing the name or a PartialCustomElementDefinition object with configuration options.

• Type: The class containing the logic for the custom element.

Return Value

Returns a CustomElementType representing the defined custom element.

CustomElement.getDefinition

Retrieves the CustomElementDefinition for a custom element class.

Usage Example

Parameters

• Type: The class of the custom element.

Return Value

Returns a CustomElementDefinition object with metadata about the custom element.

CustomElement.annotate and CustomElement.getAnnotation

These methods are used to attach and retrieve metadata to/from a custom element class.

Usage Examples

Annotating a Custom Element Class

Retrieving an Annotation from a Custom Element Class

Parameters

• Type: The custom element class to annotate or from which to retrieve annotations.

• prop: The property key for the annotation.

• value: The value for the annotation (for annotate method).

Return Value

CustomElement.annotate does not return a value. CustomElement.getAnnotation returns the annotation value.

CustomElement.generateName

Generates a unique name for a custom element, which is useful for components that do not require a specific name.

Usage Example

Return Value

A string representing a unique name for a custom element.

CustomElement.createInjectable

Creates an InjectableToken for dependency injection.

Usage Example

Return Value

An instance of InjectableToken.

CustomElement.generateType

Dynamically generates a CustomElementType with a given name and prototype.

Usage Example

Parameters

• name: The name of the custom element.

• proto: An object representing the prototype of the custom element.

Return Value

A CustomElementType that can be used to define a custom element.

Testing in Aurelia often involves testing components that have dependencies injected into them. Using dependency injection (DI) simplifies the process of replacing these dependencies with mocks, stubs, or spies during testing. This can be particularly useful when you need to isolate the component under test from external concerns like API calls or complex logic.

Understanding Mocks, Stubs, and Spies

• Mocks are objects that replace real implementations with fake methods and properties that you define. They are useful for simulating complex behavior without relying on the actual implementation.

• Stubs are like mocks but typically focus on replacing specific methods or properties rather than entire objects. They are useful when you want to control the behavior of a dependency for a particular test case.

• Spies allow you to wrap existing methods so that you can record information about their calls, such as the number of times they were called or the arguments they received.