angular-modal-service

Modal service for AngularJS - supports creating popups and modals via a service. See a quick fiddle or a full set of samples at dwmkerr.github.io/angular-modal-service.

1. Usage
2. Developing
3. Tests
4. FAQ & Troubleshooting
5. Thanks

Usage

Install with Bower (or NPM):

bower install angular-modal-service
# or...
npm install angular-modal-service

Then reference the minified script:

<script src="bower_components/angular-modal-service/dst/angular-modal-service.min.js"></script>

Specify the modal service as a dependency of your application:

var app = angular.module('sampleapp', ['angularModalService']);

Now just inject the modal service into any controller, service or directive where you need it.

app.controller('SampleController', ["$scope", "ModalService", function($scope, ModalService) {

  $scope.showAModal = function() {

  	// Just provide a template url, a controller and call 'showModal'.
    ModalService.showModal({
      templateUrl: "yesno/yesno.html",
      controller: "YesNoController"
    }).then(function(modal) {
      // The modal object has the element built, if this is a bootstrap modal
      // you can call 'modal' to show it, if it's a custom modal just show or hide
      // it as you need to.
      modal.element.modal();
      modal.close.then(function(result) {
        $scope.message = result ? "You said Yes" : "You said No";
      });
    });

  };

}]);

Calling showModal returns a promise which is resolved when the modal DOM element is created and the controller for it is created. The promise returns a modal object which contains the element created, the controller, the scope and two promises: close and closed. Both are resolved to the result of the modal close function, but close is resolved as soon as the modal close function is called, while closed is only resolved once the modal has finished animating and has been completely removed from the DOM.

The modal controller can be any controller that you like, just remember that it is always provided with one extra parameter - the close function. Here's an example controller for a bootstrap modal:

app.controller('SampleModalController', function($scope, close) {

 $scope.dismissModal = function(result) {
 	close(result, 200); // close, but give 200ms for bootstrap to animate
 };

});

The close function is automatically injected to the modal controller and takes the result object (which is passed to the close and closed promises used by the caller). It can take an optional second parameter, the number of milliseconds to wait before destroying the DOM element. This is so that you can have a delay before destroying the DOM element if you are animating the closure.

Now just make sure the close function is called by your modal controller when the modal should be closed and that's it. Quick hint - if you are using Bootstrap for your modals, then make sure the modal template only contains one root level element, see the FAQ for the gritty details of why.

To pass data into the modal controller, use the inputs field of the modal options. For example:

ModalService.showModal({
  templateUrl: "exampletemplate.html",
  controller: "ExampleController",
  inputs: {
    name: "Fry",
    year: 3001
  }
})

injects the name and year values into the controller:

app.controller('ExampleController', function($scope, name, year, close) {
});

You can also provide a controller function directly to the modal, with or without the controllerAs attribute. But if you provide controller attribute with as syntax and controllerAs attribute together, controllerAs will have high priority.

ModalService.showModal({
  template: "<div>Fry lives in {{futurama.city}}</div>",
  controller: function() {
    this.city = "New New York";
  },
  controllerAs : "futurama"
})

ShowModal Options

The showModal function takes an object with these fields:

• controller: The name of the controller to created. It could be a function.
• controllerAs : The name of the variable on the scope instance of the controller is assigned to - (optional).
• templateUrl: The URL of the HTML template to use for the modal.
• template: If templateUrl is not specified, you can specify template as raw HTML for the modal.
• inputs: A set of values to pass as inputs to the controller. Each value provided is injected into the controller constructor.
• appendElement: The custom angular element to append the modal to instead of default body element.
• scope: Optional. If provided, the modal controller will use a new scope as a child of scope (created by calling scope.$new()) rather than a new scope created as a child of $rootScope.

The Modal Object

The modal object returned by showModal has this structure:

• modal.element - The DOM element created. This is a jquery lite object (or jquery if full jquery is used). If you are using a bootstrap modal, you can call modal on this object to show the modal.
• modal.scope - The new scope created for the modal DOM and controller.
• modal.controller - The new controller created for the modal.
• modal.close - A promise which is resolved when the modal close function is called.
• modal.closed - A promise which is resolved once the modal has finished animating out of the DOM.

The Modal Controller

The controller that is used for the modal always has one extra parameter injected, a function called close. Call this function with any parameter (the result). This result parameter is then passed as the parameter of the close and closed promises used by the caller.

Animation

ModalService cooperates with Angular's $animate service to allow easy implementation of custom animation. Specifically, showModal will trigger the ng-enter hook, and calling close will trigger the ng-leave hook. For example, if the ngAnimate module is installed, the following CSS rules will add fade in/fade out animations to a modal with the class modal:

.modal.ng-enter {
  transition: opacity .5s ease-out;
  opacity: 0;
}
.modal.ng-enter.ng-enter-active {
  opacity: 1;
}
.modal.ng-leave {
  transition: opacity .5s ease-out;
  opacity: 1;
}
.modal.ng-leave.ng-leave-active {
  opacity: 0;
}

Error Handing

As the ModalService exposes only one function, showModal, error handling is always performed in the same way. The showModal function returns a promise - if any part of the process fails, the promise will be rejected, meaning that a promise error handling function or catch function can be used to get the error details:

ModalService.showModal({
  templateUrl: "some/template.html",
  controller: "SomeController"
}).then(function(modal) {
  // only called on success...
}).catch(function(error) {
  // error contains a detailed error message.
  console.log(error);
});

Developing

To work with the code, just run:

npm install
npm test
npm start

The dependencies will install, the tests will be run (always a useful sanity check after a clean checkout) and the code will run. You can open the browser at localhost:8080 to see the samples. As you change the code in the src/ folder, it will be re-built and the browser will be updated.

The easiest way to adapt the code is to play with some of the examples in the samples folder.

Tests

Run tests with:

npm test

A coverage report is written to build\coverage.

Debug tests with:

npm run test-debug

This will run the tests in Chrome, allowing you to debug.

FAQ

Having problems? Check this FAQ first.

I'm using a Bootstrap Modal and the backdrop doesn't fade away

This can happen if your modal template contains more than one top level element. Imagine this case:

<!-- Some comment -->
<div>...some modal</div>

When you create the modal, the Angular Modal Service will add both of these elements to the page, then pass the elements to you as a jQuery selector. When you call bootstrap's modal function on it, like this:

modal.element.modal();

It will try and make both elements into a modal. This means both elements will get a backdrop. In this case, either remove the extra elements, or find the specific element you need from the provided modal.element property.

I don't want to use the 'data-dismiss' attribute on a button, how can I close a modal manually?

You can check the 'Complex' sample (complexcontroller.js). The 'Cancel' button closes without using the data-dismiss attribute. All you need to do is grab the modal element in your controller, then call the bootstrap modal function to manually close the modal. Then call the close function as normal:

app.controller('ExampleModalController', [
  '$scope', '$element', 'close',
  function($scope, $element, close) {

  $scope.closeModal = function() {

    //  Manually hide the modal using bootstrap.
    $element.modal('hide');

    //  Now close as normal, but give 500ms for bootstrap to animate
    close(null, 500);
  };

}]);

I'm using a Bootstrap Modal and the dialog doesn't show up

Code is entered exactly as shown the example but when the showAModal() function fires the modal template html is appended to the body while the console outputs:

TypeError: undefined is not a function

Pointing to the code: modal.element.modal();. This occurs if you are using a Bootstap modal but have not included the Bootstrap JavaScript. The recommendation is to include the modal JavaScript before AngularJS.

Thanks

Thanks go the the following contributors:

• joshvillbrandt - Adding support for $templateCache.
• cointilt - Allowing the modal to be added to a custom element, not just the body.
• kernowjoe - controllerAs
• poporul - Improving the core logic around compilation and inputs.
• jonasnas - Fixing template cache logic.
• maxdow - Added support for controller inlining.
• kernowjoe - Robustness around locationChange
• arthur-xavier - Robustness when body element changes.