ngDialog

Modal dialogs and popups provider for AngularJS applications.

ngDialog is ~10KB (minified), has minimalistic API, is highly customizable through themes and has only AngularJS as dependency.

Demo

Install

You can download all necessary ngDialog files manually, or install it with bower:

bower install ng-dialog

or npm:

npm install ng-dialog

Usage

You need only to include ngDialog.js, ngDialog.css and ngDialog-theme-default.css (as minimal setup) to your project and then you can start using the ngDialog provider in your directives, controllers and services. For example:

<link rel="stylesheet" href="https://github.com/likeastore/ngDialog/raw/v1.4.0/lib/ng-dialog/css/ngDialog.min.css">
<link rel="stylesheet" href="https://github.com/likeastore/ngDialog/raw/v1.4.0/lib/ng-dialog/css/ngDialog-theme-default.min.css">
<script src="https://github.com/likeastore/ngDialog/raw/v1.4.0/lib/ng-dialog/js/ngDialog.min.js"></script>

Define the className to be the ngDialog-theme-default.

For example in controllers:

var app = angular.module('exampleApp', ['ngDialog']);

app.controller('MainCtrl', function ($scope, ngDialog) {
    $scope.clickToOpen = function () {
        ngDialog.open({ template: 'popupTmpl.html', className: 'ngdialog-theme-default' });
    };
});

Collaboration

Your help is appreciated! If you've found a bug or if something is not clear, please raise an issue.

Ideally, if you've found an issue, you will submit a PR that meets our [contributor guidelines][contributor-guidelines].

Running Tests

git clone git@github.com:likeastore/ngDialog.git
cd ngDialog
npm i
npm run test

API

ngDialog service provides easy to use and minimalistic API, but in the same time it's powerful enough. Here is the list of accessible methods that you can use:

===

.open(options)

Method allows to open dialog window, creates new dialog instance on each call. It accepts options object as the only argument.

Options:

template {String}

Dialog template can be loaded through path to external html template or <script> tag with text/ng-template:

<script type="text/ng-template" id="templateId">
    <h1>Template heading</h1>


Content goes here


</script>

ngDialog.open({ template: 'templateId' });

Also it is possible to use a simple string as template together with plain option.

Pro Tip about templates

It's not always necessary to place your external html template inside <script> tag. You could put these templates into $templateCache like this:

angular.module('dialog.templates').run(['$templateCache', function($templateCache) {
    $templateCache.put('templateId', 'template content');
}]);

Then it would be possible to include the dialog.templates module into the dependencies of your main module and start using this template as templateId.

There is no need to do these actions manually. You could use one of the plugins specifically for these purposes. They are available for different build systems including most popular Gulp / Grunt:

• gulp-angular-templatecache
• gulp-ng-html2js
• grunt-html2js
• broccoli-html2js

You could find more detailed examples on each of these pages.

plain {Boolean}

If true allows to use plain string as template, default false:

ngDialog.open({
    template: '

my template

',
    plain: true
});

controller {String} | {Array} | {Object}

Controller that will be used for the dialog window if necessary. The controller can be specified either by referring it by name or directly inline.

ngDialog.open({
    template: 'externalTemplate.html',
    controller: 'SomeController'
});

or

ngDialog.open({
    template: 'externalTemplate.html',
    controller: ['$scope', 'otherService', function($scope, otherService) {
        // controller logic
    }]
});

controllerAs {String}

You could optionally specify controllerAs parameter for your controller. Then inside your template it will be possible to refer this controller by the value specified by controllerAs.

Usage of controllerAs syntax is currently recommended by the AngularJS team.

resolve {Object.<String, Function>}

An optional map of dependencies which should be injected into the controller. If any of these dependencies are promises, ngDialog will wait for them all to be resolved or one to be rejected before the controller is instantiated.

If all the promises are resolved successfully, the values of the resolved promises are injected.

The map object is: - key – {String}: a name of a dependency to be injected into the controller. - factory - {String | Function}: If String then it is an alias for a service. Otherwise if Function, then it is injected using $injector.invoke and the return value is treated as the dependency. If the result is a promise, it is resolved before its value is injected into the controller.

ngDialog.open({
    controller: function Ctrl(dep) {/*...*/},
    resolve: {
        dep: function depFactory() {
            return 'dep value';
        }
    }
});

scope {Object}

Scope object that will be passed to the dialog. If you use a controller with separate $scope service this object will be passed to the $scope.$parent param:

$scope.value = true;

ngDialog.open({
    template: 'externalTemplate.html',
    className: 'ngdialog-theme-plain',
    scope: $scope
});

<script type="text/ng-template" id="externalTemplate.html">


External scope: <code>{{value}}</code>


</script>

scope.closeThisDialog(value)

In addition .closeThisDialog(value) method gets injected to passed $scope. This allows you to close the dialog straight from the handler in a popup element, for example:

    <input type="text"/>
    <input type="button" value="OK" ng-click="checkInput() && closeThisDialog('Some value')"/>

Any value passed to this function will be attached to the object which resolves on the close promise for this dialog. For dialogs opened with the openConfirm() method the value is used as the reject reason.

data {String | Object | Array}

Any serializable data that you want to be stored in the controller's dialog scope. ($scope.ngDialogData). From version 0.3.6 $scope.ngDialogData keeps references to the objects instead of copying them.

Additionally, you will have the dialog id available as $scope.ngDialogId. If you are using $scope.ngDialogData, it'll be also available under $scope.ngDialogData.ngDialogId.

className {String}

This option allows you to control the dialog's look, you can use built-in themes or create your own styled modals.

This example enables one of the built-in ngDialog themes - ngdialog-theme-default (do not forget to include necessary css files):

ngDialog.open({
    template: 'templateId',
    className: 'ngdialog-theme-default'
});

Note: If the className is not mentioned, the dialog will not display correctly.

Check themes block to learn more.

appendClassName {String}

Unlike the className property, which overrides any default classes specified through the setDefaults() method (see docs), appendClassName allows for the addition of a class on top of any defaults.

For example, the following would add both the ngdialog-theme-default and ngdialog-custom classes to the dialog opened:

ngDialogProvider.setDefaults({
    className: 'ngdialog-theme-default'
});

ngDialog.open({
    template: 'template.html',
    appendClassName: 'ngdialog-custom'
});

disableAnimation {Boolean}

If true then animation for the dialog will be disabled, default false.

overlay {Boolean}

If false it allows to hide the overlay div behind the modals, default true.

showClose {Boolean}

If false it allows to hide the close button on modals, default true.

closeByEscape {Boolean}

It allows to close modals by clicking the Esc key, default true.

This will close all open modals if there are several of them opened at the same time.

closeByNavigation {Boolean}

It allows to close modals on state change (history.back, $state.go, etc.), default false. Compatible with ui-router and angular-router. Set this value to true if you want your modal to close when you go back or change state. Set this value to false if you want your modal to stay open when you change state within your app.

This will close all open modals if there are several of them opened at the same time.

closeByDocument {Boolean}

It allows to close modals by clicking on overlay background, default true. If Hammer.js is loaded, it will listen for tap instead of click.

appendTo {String}

Specify your element where to append dialog instance, accepts selector string (e.g. #yourId, .yourClass). If not specified appends dialog to body as default behavior.

cache {Boolean}

Pass false to disable template caching. Useful for developing purposes, default is true.

name {String} | {Number}

Give a name for a dialog instance. It is useful for identifying specific dialog if there are multiple dialog boxes opened.

onOpenCallback {String} | {Function}

Provide either the name of a function or a function to be called after the dialog is opened. This callback can be used instead of the ngdialog.opened event. It provides with a way to register a hook for when the dialog is appended to the DOM and about to be shown to the user.

preCloseCallback {String} | {Function}

Provide either the name of a function or a function to be called before the dialog is closed. If the callback function specified in the option returns false then the dialog will not be closed. Alternatively, if the callback function returns a promise that gets resolved the dialog will be closed.

The preCloseCallback function receives as a parameter value which is the same value sent to .close(id, value).

The primary use case for this feature is a dialog which contains user actions (e.g. editing data) for which you want the ability to confirm whether to discard unsaved changes upon exiting the dialog (e.g. via the escape key).

This example uses an inline function with a window.confirm call in the preCloseCallback function:

ngDialog.open({
    preCloseCallback: function(value) {
        if (confirm('Are you sure you want to close without saving your changes?')) {
            return true;
        }
        return false;
    }
});

In another example, a callback function with a nested confirm ngDialog is used:

ngDialog.open({
    preCloseCallback: function(value) {
        var nestedConfirmDialog = ngDialog.openConfirm({
            template:'\


Are you sure you want to close the parent dialog?

\


\
                    <button type="button" class="ngdialog-button ngdialog-button-secondary" ng-click="closeThisDialog(0)">No</button>\
                    <button type="button" class="ngdialog-button ngdialog-button-primary" ng-click="confirm(1)">Yes</button>\


',
            plain: true
        });

        // NOTE: return the promise from openConfirm
        return nestedConfirmDialog;
    }
});

trapFocus {Boolean}

When true, ensures that the focused element remains within the dialog to conform to accessibility recommendations. Default value is true

preserveFocus {Boolean}

When true, closing the dialog restores focus to the element that launched it. Designed to improve keyboard accessibility. Default value is true

ariaAuto {Boolean}

When true, automatically selects appropriate values for any unspecified accessibility attributes. Default value is true

See Accessibility for more information.

ariaRole {String}

Specifies the value for the role attribute that should be applied to the dialog element. Default value is null (unspecified)

See Accessibility for more information.

ariaLabelledById {String}

Specifies the value for the aria-labelledby attribute that should be applied to the dialog element. Default value is null (unspecified)

If specified, the value is not validated against the DOM. See Accessibility for more information.

ariaLabelledBySelector {String}

Specifies the CSS selector for the element to be referenced by the aria-labelledby attribute on the dialog element. Def