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.

// pseudo-code; `typeof TCustomElement` doesn't work in Generics form.
<TCustomElement>(this: typeof TCustomElement, node: INode, platform: IPlatform) => boolean | void;

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.

<my-element>
 <foo></foo>
 <bar></bar>
</my-element>

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.

import { customElement, INode, IPlatform } from '@aurelia/runtime-html';

// Use a standalone function
function processContent(node: INode, platform: IPlatform) { }
@customElement({ name: 'my-element', processContent })
export class MyElement { }

// ... or use a static method explicitly
@customElement({ name: 'my-element', processContent: MyElement.processContent })
export class MyElement {
  static processContent(node: INode, platform: IPlatform) { }
}

// ... or use a static method named 'processContent' (convention)
@customElement({ name: 'my-element' })
export class MyElement {
  static processContent(node: INode, platform: IPlatform) { }
}

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

import { customElement, INode, IPlatform, processContent } from '@aurelia/runtime-html';

// Reference a static method
@processContent(MyElement.processContent)
export class MyElement {
  static processContent(node: INode, platform: IPlatform) { }
}

// ...or a standalone method
function processContent(this: typeof MyElement, node: INode, platform: IPlatform) { }
@processContent(processContent)
export class MyElement {
}

// ...or the method-level decorator
export class MyElement {
  @processContent()
  static processContent(node: INode, platform: IPlatform) { }
}

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.

<!--tabs.html-->
<div class="header">
  <au-slot name="header"></au-slot>
</div>
<div class="content">
  <au-slot name="content"></au-slot>
</div>

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

<!--app.html-->
<tabs>
  <tab header="Tab one">
    <span>content for first tab.</span>
  </tab>
  <tab header="Tab two">
    <span>content for second tab.</span>
  </tab>
  <tab header="Tab three">
    <span>content for third tab.</span>
  </tab>
</tabs>

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.

// tabs.ts
import { INode, IPlatform, processContent } from '@aurelia/runtime-html';

@processContent(Tabs.processTabs)
class Tabs {

  public static processTabs(node: INode, p: IPlatform): boolean {
    const el = node as Element;

    // At first we prepare two templates that will provide the projections to the `header` and `content` slot respectively.
    const headerTemplate = p.document.createElement('template');
    headerTemplate.setAttribute('au-slot', 'header');
    const contentTemplate = p.document.createElement('template');
    contentTemplate.setAttribute('au-slot', 'content');

    // Query the `<tab>` elements present in the `node`.
    const tabs = toArray(el.querySelectorAll('tab'));
    for (let i = 0; i < tabs.length; i++) {
      const tab = tabs[i];

      // Add header.
      const header = p.document.createElement('button');
      // Add a class binding to mark the active tab.
      header.setAttribute('class.bind', `activeTabId=='${i}'?'active':''`);
      // Add a click delegate to activate a tab.
      header.setAttribute('click.delegate', `showTab('${i}')`);
      header.appendChild(p.document.createTextNode(tab.getAttribute('header')));
      headerTemplate.content.appendChild(header);

      // Add content.
      const content = p.document.createElement('div');
      // Show the content if the tab is activated.
      content.setAttribute('if.bind', `activeTabId=='${i}'`);
      content.append(...toArray(tab.childNodes));
      contentTemplate.content.appendChild(content);

      el.removeChild(tab);
    }
    // Set the first tab as the initial active tab.
    el.setAttribute('active-tab-id', '0');

    el.append(headerTemplate, contentTemplate);
  }

  @bindable public activeTabId: string;
  public showTab(tabId: string) {
    this.activeTabId = tabId;
  }
}

Example transformation function for default [au-slot]

If you have used au-slot, 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.

processContent(node: INode, p: IPlatform) {
  const projection = p.document.createElement('template');
  projection.setAttribute('au-slot', '');
  const content = projection.content;
  for (const child of toArray(node.childNodes)) {
    if (!(child as Element).hasAttribute('au-slot')) {
      content.append(child);
    }
  }
  if (content.childElementCount > 0) {
    node.appendChild(projection);
  }
}

Sometimes developers want to simulate the situation they have experienced in other frameworks in Aurelia, like Angular or Vue binding syntax. Aurelia provides an API that allows you to change how it interprets templating syntax and even emulate other framework syntax with ease.

What is attributePattern?

attributePattern decorator in the form of extensibility feature in Aurelia. With it, we can introduce our own syntax to Aurelia's binding engine.

export function attributePattern(...patternDefs: AttributePatternDefinition[]): AttributePatternDecorator {
    // ...
}

export interface AttributePatternDefinition {
  pattern: string;
  symbols: string;
}

Its parameters are as follows

Consider the following example:

@attributePattern({ pattern: 'foo@PART', symbols: '@' })

foo@bar would give you the parts foo and bar, but if you omitted symbols, then it would give you the parts foo@ and bar.

This attribute should be on top of a class, and that class should have methods whose name matches the pattern property of each pattern you have passed to the attributePattern. Consider the following example:

// attr-patterns.ts

@attributePattern({ pattern: '[(PART)]', symbols: '[()]' })
export class AngularTwoWayBindingAttributePattern {

    public ['[(PART)]'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'two-way');
    }

}

<!-- Angular two-way binding usage -->
<input [(value)]="message">

We have defined the Angular two-way binding pattern, [(PART)], the symbols are [()] which behaves as a syntax sugar for us; the public method defined in the body of the class has the same name as the pattern defined.

This method also accepts three parameters, rawName, rawValue, and parts.

• rawName: "[(value)]"

• rawValue: "message"

• parts: ["value"]

The ref binding command to create a reference to a DOM element. In Angular, this is possible with #. For instance, ref="uploadInput" has #uploadInput equivalent in Angular.

@attributePattern({ pattern: '#PART', symbols: '#' })
export class SharpRefAttributePattern {   
    public ['#PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, parts[0], 'element', 'ref');
    }
}

Given the above example and the implementation, the parameters would have values like the following:

<!-- #uploadInput="" -->
<input type="file" #uploadInput/>

• rawName: "#uploadInput"

• rawValue: "" , an empty string.

• parts: ["uploadInput"]

If we want to extend the syntax for ref.view-model="uploadVM", for example, we could just add another pattern to the existing class:

@attributePattern(
    { pattern: 'PART#PART', symbols: '#' }, // e.g. view-model#uploadVM
    { pattern: '#PART', symbols: '#' }      // e.g. #uploadInput
)
export class AngularSharpRefAttributePattern {
    public ['PART#PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, parts[1], parts[0], 'ref');
    }
    public ['#PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, parts[0], 'element', 'ref');
    }   
}

It is up to you to decide how each PART will be taken into play.

How to register an attributePattern?

You can register attributePattern in the following two ways:

Globally

Go to the main.ts or main.js and add the following code:

import {
  AngularTwoWayBindingAttributePattern
} from './attr-patterns';

Aurelia
  .register(
    AngularTwoWayBindingAttributePattern
  )
  .app(MyApp)
  .start();

Locally

You may want to use it in a specific part of your application. You can introduce it through dependencies.

Import from somewhere else:

import { AngularTwoWayBindingAttributePattern } from "./attr-patterns";

@customElement({ 
    name: 'foo',
    template, 
    /* HERE */
    dependencies: [
        AngularTwoWayBindingAttributePattern
    ] 
})

Define it inline:

@customElement({ 
    name: 'foo',
    template    
    /* HERE */
    dependencies: [
        AttributePattern.define(class { ['!PART'](n, v, [t]) { return new AttrSyntax(n, v, t, 'bind') } }
    ] 
})

Cheatsheet

// attr-patterns.ts

import { attributePattern, AttrSyntax } from '@aurelia/runtime-html';

// Angular

@attributePattern({ pattern: '#PART', symbols: '#' })
export class AngularSharpRefAttributePattern {
    public ['#PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, parts[0], 'element', 'ref');
    }
}

@attributePattern({ pattern: '[PART]', symbols: '[]' })
export class AngularOneWayBindingAttributePattern {
    public ['[PART]'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'to-view' /*'bind'*/);
    }
}

@attributePattern({ pattern: '(PART)', symbols: '()' })
export class AngularEventBindingAttributePattern {
    public ['(PART)'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'trigger');
    }
}

@attributePattern({ pattern: '[(PART)]', symbols: '[()]' })
export class AngularTwoWayBindingAttributePattern {
    public ['[(PART)]'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'two-way');
    }
}

// Vue

@attributePattern({ pattern: '[PART]', symbols: ':' })
export class VueOneWayBindingAttributePattern {
    public [':PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'to-view' /*'bind'*/);
    }
}

@attributePattern({ pattern: '@PART', symbols: '@' })
export class VueEventBindingAttributePattern {
    public ['@PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'trigger');
    }
}

@attributePattern({ pattern: 'v-model', symbols: '' })
export class VueTwoWayBindingAttributePattern {
    public ['v-model'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, 'value', 'two-way');
    }
}

// Vue+

@attributePattern({ pattern: '::PART', symbols: '::' })
export class DoubleColonTwoWayBindingAttributePattern {
    public ['::PART'](rawName: string, rawValue: string, parts: string[]): AttrSyntax {
        return new AttrSyntax(rawName, rawValue, parts[0], 'two-way');
    }
}

// main.ts

import {
  AngularEventBindingAttributePattern,
  AngularOneWayBindingAttributePattern,
  AngularSharpRefAttributePattern,
  AngularTwoWayBindingAttributePattern,
  DoubleColonTwoWayBindingAttributePattern,
  VueEventBindingAttributePattern,
  VueOneWayBindingAttributePattern,
  VueTwoWayBindingAttributePattern
} from './attr-patterns';

Aurelia
  .register(
    AngularSharpRefAttributePattern,
    AngularOneWayBindingAttributePattern,
    AngularEventBindingAttributePattern,
    AngularTwoWayBindingAttributePattern,
    VueOneWayBindingAttributePattern,
    VueEventBindingAttributePattern,
    VueTwoWayBindingAttributePattern,
    DoubleColonTwoWayBindingAttributePattern
  )
  .app(MyApp)
  .start();

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.

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:

Then, intuitively, we would write the following template:

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

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.

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.

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

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.

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.

Live example

A similar example can be seen in action below.

Hooks

There are scenarios where an application wants to control how to preprocess a template before it is compiled. There could be various reasons, such as accessibility validation, adding debugging attributes etc...

Aurelia supports this via template compiler hooks, enabled with the default template compiler. To use these features, declare and then register the desired hooks with either global (at startup) or local container (at dependencies (runtime) or <import> with convention).

An example of declaring global hooks that will be called for every template:

With VanillaJS

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

Aurelia
  .register(TemplateCompilerHooks.define(class {
    compiling(template: HTMLElement) {
      element.querySelector('table').setAttribute(someAttribute, someValue);
    }
  }))

With decorator

import Aurelia, { templateCompilerHooks } from 'aurelia';

@templateCompilerHooks
class MyTableHook1 {
  compiling(template) {...}
}
// paren ok too
@templateCompilerHooks()
class MyTableHook1 {
  compiling(template) {...}
}

Aurelia.register(MyTableHook1);

Supported hooks

• compiling: this hook will be invoked before the template compiler starts compiling a template. Use this hook if there need to be any changes to a template before any compilation.

Hooks invocation order

All hooks from local and global registrations will be invoked: local first, then global.

Compilation Behavior

The default compiler will remove all binding expressions while compiling a template. This is to clean the rendered HTML and increase the performance of cloning compiled fragments.

Though this is not always desirable for debugging, it could be hard to figure out what element mapped to the original part of the code. To enable an easier debugging experience, the default compiler has a property debug that when set to true will keep all expressions intact during the compilation.

This property can be set early in an application lifecycle via AppTask, so that all the rendered HTML will keep their original form. An example of doing this is:

import Aurelia, { AppTask, ITemplateCompiler } from 'aurelia';
import { MyApp } from './my-app';

Aurelia
  .register(AppTask.creating(ITemplateCompiler, compiler => compiler.debug = true))
  .app(MyApp)
  .start();

List of attributes that are considered expressions:

• containerless

• as-element

• ref

• attr with binding expression (attr.command="...")

• attr with interpolation (attr="${someExpression}")

• custom attribute

• custom element bindables

Scenarios

Now that we understand how the template compiler works let's create fun scenarios showcasing how you might use it in your Aurelia applications.

Feature Flagging in Templates

If your application uses feature flags to toggle features on and off, you may want to modify templates based on these flags conditionally.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class FeatureFlagHook {
  constructor(private featureFlags: Record<string, boolean>) {}

  compiling(template: HTMLElement) {
    const featureElements = template.querySelectorAll('[data-feature]');
    for (const element of featureElements) {
      const featureName = element.getAttribute('data-feature');
      if (!this.featureFlags[featureName]) {
        element.parentNode.removeChild(element);
      }
    }
  }
}

const activeFeatureFlags = {
  'new-ui': true,
  'beta-feature': false
};

Aurelia.register(TemplateCompilerHooks.define(new FeatureFlagHook(activeFeatureFlags)))
  .app(MyApp)
  .start();

Here, elements with a data-feature attribute will be removed from the template if the corresponding feature flag is set to false, allowing for easy management of feature rollouts.

Auto-Generating Form Field IDs for Label Association

For accessibility purposes, form fields must associate label elements with matching for and id attributes. We can automate this process during template compilation.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class FormFieldHook {
  private fieldCounter = 0;

  compiling(template: HTMLElement) {
    const formFields = template.querySelectorAll('input, textarea, select');
    for (const field of formFields) {
      if (!field.hasAttribute('id')) {
        const uniqueId = `form-field-${this.fieldCounter++}`;
        field.setAttribute('id', uniqueId);
        
        const label = template.querySelector(`label[for="${field.getAttribute('name')}"]`);
        if (label) {
          label.setAttribute('for', uniqueId);
        }
      }
    }
  }
}

Aurelia.register(TemplateCompilerHooks.define(new FormFieldHook()))
  .app(MyApp)
  .start();

In this use case, the hook generates a unique id for each form field that doesn't already have one and updates the corresponding label's for attribute to match. This ensures that form fields are properly labelled for screen readers and other assistive technologies.

Automatic ARIA Role Assignment

To enhance accessibility, you might want to automatically assign ARIA roles to certain elements based on their class or other attributes to make your application more accessible without manually annotating each element.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class AriaRoleHook {
  compiling(template: HTMLElement) {
    const buttons = template.querySelectorAll('.btn');
    for (const button of buttons) {
      if (!button.hasAttribute('role')) {
        button.setAttribute('role', 'button');
      }
    }
  }
}

Aurelia.register(TemplateCompilerHooks.define(new AriaRoleHook()))
  .app(MyApp)
  .start();

This hook assigns the role="button" to all elements that have the .btn class and do not already have a role defined. This helps ensure that custom-styled buttons are accessible.

Content Security Policy (CSP) Compliance

If your application needs to comply with strict Content Security Policies, you should ensure that inline styles are not used within your templates. A template compiler hook can help you enforce this policy.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class CSPHook {
  compiling(template: HTMLElement) {
    const elementsWithInlineStyles = template.querySelectorAll('[style]');
    for (const element of elementsWithInlineStyles) {
      console.warn(`Inline style removed from element for CSP compliance:`, element);
      element.removeAttribute('style');
    }
  }
}

Aurelia.register(TemplateCompilerHooks.define(new CSPHook()))
  .app(MyApp)
  .start();

This hook scans for any elements with inline style attributes and removes them, logging a warning for developers to take notice and refactor the styles into external stylesheets.

Lazy Loading Image Optimization

For performance optimization, you should implement lazy loading for images. The template compiler can automatically add lazy loading attributes to your image tags.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class LazyLoadingHook {
  compiling(template: HTMLElement) {
    const images = template.querySelectorAll('img:not([loading])');
    for (const img of images) {
      img.setAttribute('loading', 'lazy');
    }
  }
}

Aurelia.register(TemplateCompilerHooks.define(new LazyLoadingHook()))
  .app(MyApp)
  .start();

This hook finds all img elements without a loading attribute and sets it to lazy, instructing the browser to defer loading the image until it is near the viewport.

Dynamic Theme Class Injection

If your application supports multiple themes, you can use a template compiler hook to inject the relevant theme class into the root of your templates based on user preferences.

import Aurelia, { TemplateCompilerHooks } from 'aurelia';

class ThemeClassHook {
  constructor(private currentTheme: string) {}

  compiling(template: HTMLElement) {
    const rootElement = template.querySelector(':root');
    if (rootElement) {
      rootElement.classList.add(`theme-${this.currentTheme}`);
    }
  }
}

const userSelectedTheme = 'dark'; // For example, a dark theme
Aurelia.register(TemplateCompilerHooks.define(new ThemeClassHook(userSelectedTheme)))
  .app(MyApp)
  .start();

This hook adds a theme-specific class to the root element of every template, allowing for theme-specific styles to be applied consistently across the application.

Node APIs used

The default template compiler will turn a template, either in string or already an element, into an element before the compilation. During the compilation, these APIs on the Node & Element classes are accessed and invoked:

• Node.prototype.nodeType

• Node.prototype.nodeName

• Node.prototype.childNodes

• Node.prototype.childNode

• Node.prototype.firstChild

• Node.prototype.textContent

• Node.prototype.parentNode

• Node.prototype.appendChild

• Node.prototype.insertBefore

• Element.prototype.attributes

• Element.prototype.hasAttribute

• Element.prototype.getAttribute

• Element.prototype.setAttribute

• Element.prototype.classList.add

If it is desirable to use the default template compiler in any environment other than HTML, ensure the template compiler can hydrate the input string or object into some object with the above APIs.

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>