This library is part of the Aurelia platform and contains a dialog plugin.
To keep up to date on Aurelia, please visit and subscribe to the official blog and our email list. We also invite you to follow us on twitter. If you have questions, please join our community on Gitter or use stack overflow. Documentation can be found in our developer hub. If you would like to have deeper insight into our development process, please install the ZenHub Chrome or Firefox Extension and visit any of our repository's boards.
This library can be used in the browser.
To build the code, follow these steps.
-
Ensure that NodeJS is installed. This provides the platform on which the build tooling runs.
-
From the project folder, execute the following command:
npm install
-
Ensure that Gulp is installed. If you need to install it, use the following command:
npm install -g gulp
-
To build the code, you can now run:
gulp build
-
You will find the compiled code in the
distfolder, available in three module formats: AMD, CommonJS and ES6. -
See
gulpfile.jsfor other tasks related to generating the docs and linting.
To run the unit tests, first ensure that you have followed the steps above in order to install all dependencies and successfully build the library. Once you have done that, proceed with these additional steps:
-
Ensure that the Karma CLI is installed. If you need to install it, use the following command:
npm install -g karma-cli
-
Ensure that jspm is installed. If you need to install it, use the following commnand:
npm install -g jspm
-
You can now run
jspmto install dependencies required for running the test suite:
jspm install- Download the SystemJS module loader:
jspm dl-loader-
Ensure that you have Chrome installed. Karma runs the test suite in Chrome.
-
You can now run the tests with this command:
karma start
To run the sample code using this plugin proceed with these additional steps:
- Go to the
sampledirectory and install dependencies usingjspm:
cd sample
jspm install- Go back to the root of the project and use gulp to serve the sample project:
cd ..
gulp watch- In your JSPM-based project install the plugin via
jspmwith following command
jspm install aurelia-dialogIf you use Webpack, install the plugin with the following command
npm install aurelia-dialog --saveIf you use TypeScript, install the plugin's typings with the following command
typings install github:aurelia/dialog --save- Make sure you use manual bootstrapping. In order to do so open your
index.htmland locate the element with the attribute aurelia-app. Change it to look like this:
<body aurelia-app="main">
...- Create (if you haven't already) a file
main.jsin yoursrcfolder with following content:
export function configure(aurelia) {
aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-dialog');
aurelia.start().then(a => a.setRoot());
}Note: If you are using WebPack it is possible that the plugin is installed before Aurelia has replaced the
<body>element, if that is where youraurelia-app="main"is defined, which results in some of the dialog components getting overwritten. In this case you can move theaurelia-appattribute to a<div>inside of the<body>. Example -<body><div aurelia-app="main"></div></body>.
There are a few ways you can take advantage of the Aurelia dialog.
- You can use the dialog service to open a prompt -
import {DialogService} from 'aurelia-dialog';
import {Prompt} from './prompt';
export class Welcome {
static inject = [DialogService];
constructor(dialogService) {
this.dialogService = dialogService;
}
submit(){
this.dialogService.open({ viewModel: Prompt, model: 'Good or Bad?'}).then(response => {
if (!response.wasCancelled) {
console.log('good');
} else {
console.log('bad');
}
console.log(response.output);
});
}
}This will open a prompt and return a promise that resolves when closed. If the user clicks out, clicks cancel, or clicks the 'x' in the top right it will still resolve the promise but will have a property on the response wasCancelled to allow the developer to handle cancelled dialogs.
There is also an output property that gets returned with the outcome of the user action if one was taken.
- You can create your own view / view-model and use the dialog service to call it from your app's view-model -
import {EditPerson} from './edit-person';
import {DialogService} from 'aurelia-dialog';
export class Welcome {
static inject = [DialogService];
constructor(dialogService) {
this.dialogService = dialogService;
}
person = { firstName: 'Wade', middleName: 'Owen', lastName: 'Watts' };
submit(){
this.dialogService.open({ viewModel: EditPerson, model: this.person}).then(response => {
if (!response.wasCancelled) {
console.log('good - ', response.output);
} else {
console.log('bad');
}
console.log(response.output);
});
}
}This will open a dialog and control it the same way as the prompt. The important thing to keep in mind is you need to follow the same method of utilizing a DialogController in your EditPerson view-model as well as accepting the model in your activate method -
import {DialogController} from 'aurelia-dialog';
export class EditPerson {
static inject = [DialogController];
person = { firstName: '' };
constructor(controller){
this.controller = controller;
}
activate(person){
this.person = person;
}
}and the corresponding view -
<template>
<ai-dialog>
<ai-dialog-body>
<h2>Edit first name</h2>
<input value.bind="person.firstName" />
</ai-dialog-body>
<ai-dialog-footer>
<button click.trigger="controller.cancel()">Cancel</button>
<button click.trigger="controller.ok(person)">Ok</button>
</ai-dialog-footer>
</ai-dialog>
</template>The modal exposes an attach-focus custom attribute that allows focusing in on an element in the modal when it is loaded. You can use this to focus a button, input, etc... Example usage -
<template>
<ai-dialog>
<ai-dialog-body>
<h2>Edit first name</h2>
<input attach-focus="true" value.bind="person.firstName" />
</ai-dialog-body>
</ai-dialog>
</template>You can also bind the value of the attach-focus attribute if you want to alter which element will be focused based on a view model property.
<input attach-focus.bind="isNewPerson" value.bind="person.email" />
<input attach-focus.bind="!isNewPerson" value.bind="person.firstName" />###Global Settings
You can specify global settings as well for all dialogs to use when installing the plugin via the configure method. If providing a custom configuration, you must call the useDefaults() method to apply the base configuration.
export function configure(aurelia) {
aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-dialog', config => {
config.useDefaults();
config.settings.lock = true;
config.settings.centerHorizontalOnly = false;
config.settings.startingZIndex = 5;
config.settings.enableEscClose = true;
});
aurelia.start().then(a => a.setRoot());
}Note: The startingZIndex will only be assignable during initial configuration. This is because we stack everything on that Z-index after bootstrapping the modal.
###Settings The settings available for the dialog are set on the dialog controller on a per-dialog basis.
lockmakes the dialog modal, and removes the close button from the top-right hand corner. (defaults to true)centerHorizontalOnlymeans that the dialog will be centered horizontally, and the vertical alignment is left up to you. (defaults to false)positiona callback that is called right before showing the modal with the signature:(modalContainer: Element, modalOverlay: Element) => void. This allows you to setup special classes, play with the position, etc... If specified,centerHorizontalOnlyis ignored. (optional)ignoreTransitionsis a Boolean you must set totrueif you disable css animation of your dialog. (optional, default to false)yieldControlleris a Boolean you must set totrueif you want to execute some logic when the dialog gets open and/or get access to the dialog controllerrejectOnCancelis a Boolean you must set totrueif you want to handle cancellations as rejection. The reason will be instance ofDialogCancelError- the propertywasCancelledwill be set totrueand if cancellation data was provided it will be set to thereasonproperty.enableEscCloseallows pressings escape to close the modal withoutlock: false. (optional, defaults to true)
Warning: Plugin authors are advised to be explicit with settings that change behavior(
yieldControllerandrejectOnCancel).
export class Prompt {
static inject = [DialogController];
constructor(controller){
this.controller = controller;
this.answer = null;
controller.settings.lock = false;
controller.settings.centerHorizontalOnly = true;
}
}###Getting access to DialogController API outside
It is possible to resolve and close (using cancel/ok/error methods) dialog in the same context where you open it.
import {EditPerson} from './edit-person';
import {DialogService} from 'aurelia-dialog';
export class Welcome {
static inject = [DialogService];
constructor(dialogService) {
this.dialogService = dialogService;
}
person = { firstName: 'Wade', middleName: 'Owen', lastName: 'Watts' };
submit(){
this.dialogService.open({yieldController: true, viewModel: EditPerson, model: this.person}).then(openDialogResult => {
// Note you get here when the dialog is opened, and you are able to close dialog
// Promise for the result is stored in openDialogResult.closeResult property
openDialogResult.closeResult.then((response) => {
if (!response.wasCancelled) {
console.log('good');
} else {
console.log('bad');
}
console.log(response);
})
setTimeout(() => {
openDialogResult.controller.cancel('canceled outside after 3 sec')
}, 3000)
});
}
}Bootstrap adds 50% opacity and a background color of black to the modal. To achieve this in dialog you can simply add the following CSS -
ai-dialog-overlay.active {
background-color: black;
opacity: .5;
}