Plugin Installation for Aurelia CLI

For the plugin installation in a project created via Aurelia CLI, navigate to your project root and exute the following command:

npm install aurelia-notify --save

This will download the plugin and add it to your package.json. After that, open the aurelia_project/aurelia.json file and scroll down to the build.bundles section. Add the following to the dependencies section:

{
  "name": "aurelia-notify",
  "path": "../node_modules/aurelia-notify/dist/amd",
  "main": "aurelia-notify",
  "resources": [
    "bs-notification.html",
    "style.css"
  ]
}

Plugin Installation via JSPM

For the plugin installation via JSPM, go to your project root and verify npm (npm install) and jspm (jspm install) installation was already executed.

Now, you can install the notification plugin via the following command:

jspm install aurelia-notify

The command will add the plugin source code to your jspm_packages directory as well as a mapping into your config.js which looks similar to the following:

"aurelia-notify": "github:MarcScheib/aurelia-notify@x.y.z"

You can also add a specific branch to your application if you are looking for technical previews by executing the following command:

jspm install aurelia-notify=github:MarcScheib/aurelia-notify@master

This will add the current master branch instead of the latest tagged version.

Plugin Configuration in your Application

During the bootstrapping of the Aurelia Framework, you can include the notification plugin by simply adding it to the list of loaded plugins:

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging()
    ...
    .plugin('aurelia-notify'); // Add this line to load the plugin

  aurelia.start().then(a => a.setRoot('app', document.body));
}

Getting started

A simple introduction for the aurelia-notify plugin is shown by using the Aurelia demo application skeleton-navigation.

We start by setting up the project. Afterwards, we install and configure the plugin as shown in Installation.

1. Clone the repository into your local project folder:

git clone https://github.com/aurelia/skeleton-navigation.git

2. Switch into the skeleton-navigation directory and choose one of your preferred starter kits. In this example, we choose the skeleton-es2016. Switch into that directory and install all npm dependencies:

cd skeleton-navigation
cd skeleton-es2016
npm install

3. In the same directory, install the jspm dependencies:

jspm install

4. Install the aurelia-notify dependency via jspm:

jspm install aurelia-notify

The project is now set up together with the notification plugin and we can start using it. Via executing gulp watch you can start a server running the application. It is then available via the shown URL on the command line (e.g. http://localhost:9000).

The next step is to configure the aurelia-notify plugin. In your favored IDE, open the file skeleton-navigation/skeleton-es2016/src/main.js and adjust it as follows:

import 'bootstrap';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging()
    .plugin('aurelia-notify');

  //Uncomment the line below to enable animation.
  //aurelia.use.plugin('aurelia-animator-css');
  //if the css animator is enabled, add swap-order="after" to all router-view elements

  //Anyone wanting to use HTMLImports to load views, will need to install the following plugin.
  //aurelia.use.plugin('aurelia-html-import-template-loader')

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

We simply added the .plugin('aurelia-notify') line. With this basic configuration, the plugin makes use of the available Bootstrap CSS styling. In case you want to use a different configuration, see the Configuration section.

We can start adding notifications to our application now. The plugin exposes a NotificationService which is used to display our notifications. Open the file skeleton-navigation/skeleton-es2016/src/welcome.js and edit the file as follows:

1. We need to import the NotificationService from the plugin. On top of the file, add the following line:

import {NotificationService} from 'aurelia-notify';

2. Inject the service into the constructor of the view-model as shown in the following snippet:

static inject = [NotificationService];
constructor(notificationService){
  this.notificationService = notificationService;
}

3. Now, we can add notifications, e.g. by showing an info notification instead of an alert box when submitting our name. Adjust the submit() method as follows:

submit() {
  this.previousValue = this.fullName;
  this.notificationService.info(`Welcome, ${this.fullName}!`);
}

Note: Make sure you use ` (backtick) instead of ' (apostrophe) for the info() method to use the ES2016 Template Literals and having the name replaced.

The page should update automatically when adding those changes if you started the application via gulp watch. If you press the Submit button multiple times, you can see how the notifications pop up. As you can see, the display of the notifications is not optimal.

By default, notifications are added to the <body> tag as the first child. We can change this, by configuring a different attachment point. Modify the service call in the submit() method as follows:

this.notificationService.info(`Welcome, ${this.fullName}!`, {containerSelector: '#page-host'});

The notification is now displayed below the form and visible to the user directly.

Beside the info() notification, there are three different methods available which in the base configuration make use of Bootstraps alert styles. Those are success(), warning(), and danger().

For more information on the configuration, see the Section Configuration. API information will be available soon.

Configuration

The plugin supports global configuration for all notifications as well as a specialized configuration for each single notification.

Global Configuration

The global configuration is handled together with the plugin registration during Aurelia's bootstrapping process. The following snippet shows, how configuration parameters are handed over to the plugin:

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging()
    .plugin('aurelia-notify', settings => {
      settings.timeout = 10000;
    });

  aurelia.start().then(a => a.setRoot('app', document.body));
}

For all available configuration parameters, see Section Configuration Parameters.

Specialized Configuration

Beside the global configuration, it is also possible to specify a different configuration for each notification itself. Simply add another parameter to the notification service call holding the configuration parameters. The following snippet shows an example:

this.notificationService.info('This notification lasts for 5s before it is closed automatically.', {timeout: 5000});
this.notificationService.danger('This notification lasts for 10s before it is closed automatically.', {timeout: 10000});

For all available configuration parameters, see Section Configuration Parameters.

Configuration Parameters

The aurelia-notify plugin provides the following configuration parameters:

• append
  • Specifies whether notifications should be appended to the notification container instead of inserted as the first element.
  • Default: false
• containerSelector
  • Specifies to which DOM element the created notification will be attached to. The container selector is applied to DOM tree and the first element returned will be used. If no element is found, the default value is used.
  • Default: 'body'
• timeout
  • Specifies the duration of the notification visibility. After the timeout, the notification is removed automatically if the user is not closing it. If zero is specified, the notification can only be cleared manually by the user.
  • Default: 0
• viewModel
  • Specifies which view model is used for the notification. This allows to specify own customized elements and data. The default settings makes use of Bootstrap styles.
  • Default: BSNotification
• limit
  • Specifies the amount of notifications that are shown at the same time. If additional notifications are added, the oldest ones are closed.
  • Default: 5

Customization

The plugin allows several different customizations based on the Configuration Parameters.

Customize service method calls

At the moment, the notification plugin supports four built-in methods to show notifications:

• info(message, settings)
• success(message, settings)
• warning(message, settings)
• danger(message, settings)

Each method takes a message parameter which is shown as the notification message and, optionally, a settings object base on above's configuration parameters. The methods internally call notify(model, settings, level), which can also be used to show notifications. It has a third parameter specifying the level or severity of the notification and, thus, the color of the notification box (when using the default). By default, the levels map to Bootstraps equivalents. The following code snippets show some examples:

This snippet shows a success notification which hides automatically after 5 seconds.

this.notificationService.notify('A success message', {timeout: 5}, NotificationLevel.success);

Customize the notification element

Instead of using the default Bootstrap notification view/view-model, it is also possible to use an own pair.

First of all, it is necessary to specify a view file and a view-model, e.g. the following:

The view may look like this:

<template>
  <div class="simple-notification">
    ${notification}
  </div>
</template>

And the corresponding view-model:

export class SimpleNotification {
  activate(model) {
    this.notification = model.notification;
  }
}

The next step is to configure the plugin to use this view/view-model (it is also possible to use it for one service call only by adjusting the settings of a service method). It may look like this:

import {SimpleNotification} from './simple-notification';

export function configure(aurelia) {
  aurelia.use
    .standardConfiguration()
    .developmentLogging()
    .plugin('aurelia-notify', settings => {
      settings.viewModel = SimpleNotification;
    });

  aurelia.start().then(a => a.setRoot('app', document.body));
}

Now, the customized view/view-model is used instead of the default one.

It is also possible to hand over additional data to the view model beside the notification message and the notification level. The notify(model, settings, level) method can take a complete data object as the first argument. It must at least contain a notification property, otherwise, an exception is thrown. The data is available in the view models activate() method via the data property of the activation parameter, e.g:

export class SimpleNotification {
  activate(model) {
    this.notification = model.notification;
    this.date = model.data.date;
    this.username = model.data.username;
  }
}

And the corresponding service call:

this.notificationService.notify({notification: 'A success message', date: '2016/10/09', username: 'Marc'}, {timeout: 5}, NotificationLevel.success);