Migrating from Durandal to Aurelia#

If you have an existing Durandal application you maybe want to migrate this app to Aurelia. Typically you used

Knockout for data-binding. Because Aurelia brings its own data-binding language the usage of Knockout

is not necessary anymore. But probably especially this part of the migration requires the greatest effort,

because you have to modify much of your code or partially rewrite it. So let’s split this effort as much as possible:

Here’s a way how you can use Aurelia side-by-side with the Knockout technology and then migrate each view and

view-model step-by-step. You can use your old Knockout views and their backed JavaScript code with its observables

and subscriptions, as if you were still using Durandal.

First Steps#

First, install the Aurelia plugin

1
jspm install aurelia-knockout

and register it during the startup of your app:

1
export function configure(aurelia) => {
2
    aurelia.use
3
        .standardConfiguration()
4
        .developmentLogging()
5
        .plugin("aurelia-knockout");
6

7
    aurelia.start().then(() => aurelia.setRoot());
8
}

The next step will be, to add the knockout custom attribute to each view which uses Knockout syntax:

1
<template>
2
  <div knockout>
3
    <button data-bind="click: changeVisibility">Change Visibility</button>
4
    <div data-bind="if: isVisible">
5
      <span data-bind="text: firstName"></span>
6
      <br />
7
      <span data-bind="text: lastName"></span>
8
    </div>
9
  </div>
10
</template>

Note: The element with the custom attribute has to wrap all code with Knockout syntax.

This attribute binds the HTML to the current BindingContext of Aurelia.

And that’s it! With these small modifications you can use all Knockout bindings which are available.

Using Compositions#

Durandal also provided a binding to compose views. Because this binding was implemented from Durandal and not

from Knockout you can not use this feature natively. But the aurelia-knockout plugin supports the composition

with all possible variants listed in the official Durandal docs:

1
<div data-bind="compose: 'path/to/view.html'"></div>
2
<div data-bind="compose: 'path/to/module'"></div>
3
<div data-bind="compose: { view: 'path/to/view.html' }"></div>
4
<div data-bind="compose: { model: 'path/to/module' }"></div>
5
<div data-bind="compose: { model: moduleInstance }"></div>
6
<div
7
  data-bind="compose: { view: 'path/to/view.html' model: 'path/to/module' }"
8
></div>
9
<div
10
  data-bind="compose: { view: 'path/to/view.html' model: moduleInstance }"
11
></div>
12
<div data-bind="compose: moduleInstance"></div>
13
<div data-bind="compose: moduleConstructorFunction"></div>

Set @bindable properties#

To enhance the flexibility of your migration process, this plugin also supports the ability to set @bindable

variables in rewritten subordinated Aurelia views through the activationData. This offers the possibility to rewrite

single views in lower hierarchies without the need to do the same with their parent views.

Parent Knockout based view#

Supposed that there is a parent view using Knockout technology which composes a child view like this:

1
<template>
2
  <div
3
    data-bind="compose: { model: 'path/to/submodule', activationData: data }"
4
  ></div>
5
</template>

The appropriate data object would looks like this:

1
{
2
  price: ko.observable(5),
3
  productName: "Apples"
4
}

Child Aurelia based view#

The child view and view-model uses Aurelia:

1
<template>
2
  Product:
3
  <span>${productName}</span>
4
  <br />
5
  Price:
6
  <span>${price}</span>
7
</template>

1
import { bindable } from "aurelia-framework";
2
import { inject } from "aurelia-dependency-injection";
3
import { KnockoutBindable } from "aurelia-knockout";
4

5
@inject(KnockoutBindable)
6
export class ProductView {
7
  @bindable
8
  price;
9
  productName;
10

11
  knockoutBindable;
12

13
  constructor(knockoutBindable) {
14
    this.knockoutBindable = knockoutBindable;
15
  }
16

17
  activate(activationData) {
18
    this.knockoutBindable.applyBindableValues(activationData, this);
19
  }
20
}

This will set the value from activationData.price to this.price. this.productName however, is not

updated because it has no @bindable decorator and the variable from activationData is no Knockout

observable. To process non Knockout observables anyway you have to pass false as third parameter to the

applyBindableValues function. If the outer value changed (and is an observable) the corresponding inner

variable is updated too.

Subscriptions for Knockout observables which are created from this plugin internally will be disposed automatically

if the child view is unbound.

Conclusion#

The migration to a new framework is often a big task depending on your application. But that does not mean that you have to implement it all at once. This plugin offers you a possibility to ship preliminary results during the transition phase of your application.