Using toastr with aurelia

Introduction

For this post I want to show an example how to use an existing library in an aurelia app. The hard part is understanding how to use your library with systemjs and jspm.

Use case: toastr

I got a request to demo this with toastr.
Toastr is an open source library to show simple javascript toast notifications.

Project Setup

I like a good code name for every blogpost, today we'll go with High Red Avenue.
So let's crank up an empty folder, open that commandline and get to it!

jspm

HighRedAvenue> jspm init

We will use all the default settings here.
Next up: let's install aurelia similiar like we did in a previous post.

HighRedAvenue> jspm install aurelia-framework
HighRedAvenue> jspm install aurelia-bootstrapper

Now we would like to install toastr with jspm. But let's wait for a moment here.

Did you every wondered how jspm knows how to download the right repositories from github when running jspm install aurelia-framework?

If we look at our config.js several mappings are made by jspm.

So where did all that info come from? Well a number of packages are listed globally in the jspm registry. These point to github or npm and get downloaded from there.
Unfortunately toastr is not mentioned in the list.

So running

HighRedAvenue> jspm install toastr --> won't work

will throw an err Repo jspm:toastr not found!

Toastr is is on github so it can be downloaded by jspm.
Let's do this and give it a nice alias of toastr

HighRedAvenue> jspm install toastr=github:CodeSeven/toastr

Toastr has a dependency on jquery so we will need to install jquery as well.

HighRedAvenue> jspm install jquery

Our config.js file will be updated and containing

"jquery": "github:components/jquery@2.1.4",
"toastr": "github:CodeSeven/toastr@2.1.1",

Loading toastr with System

We'll need an index.html file to host our application.
This will need to include a reference to system.js and our config.js.
Once those are added we can load toastr using System.import.
This returns a Promise with the toastr module.
From there on all we need is a reference to the toastr style file and we should be able to view our first message.

Fire up browser-sync to serve as a webserver.

HighRedAvenue> browser-sync start --server --files *.*

Importing toastr in the viewmodel

Now let's get to the aurelia part! We'll setup a basic app.html, app.js and modify the index.html to load our app.

In the app.html we create a small form and bind the submit event to our viewmodel.

Lastly we want to show a toast when the user submits the form. So inside the submit() method we'll use the toastr library. The ES2015 way to import a module:

import * as toastr from "toastr";

* means that we want import everything from the "toastr" module with an alias of toastr. The from "toastr" part maps to "toastr" in our config.js file. Systemjs will know what file to import.

At this point we can call functions from the imported toastr object.

And Bob's your uncle!

Remarks

  • Toastr uses requirejs as it's module system. Luckily jspm knows how to deal with that.
  • Due to the nature of ES2015 modules you will get an exception if you try to enter 'toastr' in your developer console. The toastr object is only known inside app.js and is not polluting the global scope.
  • Toastr also has a package on npm, we could also have used jspm install toastr=npm:toastr to install it.

The Source

Available on github

Final words

When starting with aurelia jspm, Systemjs and ES2015 can be a bit challenging. I hope this simple project explains a couple of concepts and helps beginners getting started.

If you have any further questions, remarks or corrections please add them below.
Thanks for reading!

Yours truly,
nojaf

Florian Verdonck
Florian Verdonck

Florian Verdonck is web & .NET developer. He is passionate about clean code and is eager to learn new technologies.