<!-- ### LOOKING FOR MAINTAINER. PLEASE PING [@voronianski](https://twitter.com/voronianski)! -->
# ngDialog
[![build status](http://img.shields.io/travis/likeastore/ngDialog.svg)](https://travis-ci.org/likeastore/ngDialog)
[![npm version](http://badge.fury.io/js/ng-dialog.svg)](http://badge.fury.io/js/ng-dialog)
[![github tag](https://img.shields.io/github/tag/likeastore/ngDialog.svg)](https://github.com/likeastore/ngDialog/tags)
[![Download Count](https://img.shields.io/npm/dm/ng-dialog.svg)](http://www.npmjs.com/package/ng-dialog)
[![Code Climate](https://codeclimate.com/github/likeastore/ngDialog/badges/gpa.svg)](https://codeclimate.com/github/likeastore/ngDialog)
> Modal dialogs and popups provider for [AngularJS](http://angularjs.org/) applications.
ngDialog is ~10KB (minified), has minimalistic API, is highly customizable through themes and has only AngularJS as dependency.
### [Demo](http://likeastore.github.io/ngDialog)
## Install
You can download all necessary ngDialog files manually, or install it with bower:
```bash
bower install ng-dialog
```
or npm:
```bash
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:
```html
<link rel="stylesheet" href="lib/ng-dialog/css/ngDialog.min.css">
<link rel="stylesheet" href="lib/ng-dialog/css/ngDialog-theme-default.min.css">
<script src="lib/ng-dialog/js/ngDialog.min.js"></script>
```
Define the className to be the ``ngDialog-theme-default``.
For example in controllers:
```javascript
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
```bash
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``:
```html
<script type="text/ng-template" id="templateId">
<h1>Template heading</h1>
<p>Content goes here</p>
</script>
```
```javascript
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:
```javascript
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](https://github.com/miickel/gulp-angular-templatecache)
- [gulp-ng-html2js](https://www.npmjs.com/package/gulp-ng-html2js)
- [grunt-html2js](https://github.com/karlgoldstein/grunt-html2js)
- [broccoli-html2js](https://www.npmjs.com/package/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``:
```javascript
ngDialog.open({
template: '<p>my template</p>',
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.
```javascript
ngDialog.open({
template: 'externalTemplate.html',
controller: 'SomeController'
});
```
or
```javascript
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.
```javascript
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:
```javascript
$scope.value = true;
ngDialog.open({
template: 'externalTemplate.html',
className: 'ngdialog-theme-plain',
scope: $scope
});
```
```html
<script type="text/ng-template" id="externalTemplate.html">
<p>External scope: <code>{{value}}</code></p>
</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:
```html
<div class="dialog-contents">
<input type="text"/>
<input type="button" value="OK" ng-click="checkInput() && closeThisDialog('Some value')"/>
</div>
```
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](https://github.com/likeastore/ngDialog#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):
```javascript
ngDialog.open({