angular-modal

A modal factory service for AngularJS that makes it easy to add modals to your app.

Install

bower install angular-modal

Usage

1. Include the modal.js script provided by this component into your app.
2. Optional: Include the modal.css style provided by this component into your html.
3. Add btford.modal as a module dependency to your app.

Examples

Plunker demo

Plunker demo (with animations)

Typical Use

app.js

angular.module('myApp', ['btford.modal']).

// let's make a modal called `myModal`
factory('myModal', function (btfModal) {
  return btfModal({
    controller: 'MyModalCtrl',
    controllerAs: 'modal',
    templateUrl: 'my-modal.html'
  });
}).

// typically you'll inject the modal service into its own
// controller so that the modal can close itself
controller('MyModalCtrl', function (myModal) {
  this.closeMe = myModal.deactivate;
}).

controller('MyCtrl', function (myModal) {
  this.showModal = myModal.activate;
});

my-modal.html

<div class="btf-modal">
  <h3>Hello {{name}}</h3>
  <p><a href ng-click="modal.closeMe()">Close Me</a></p>
</div>

index.html

<div ng-app="myApp" ng-controller="MyCtrl as ctrl">
  <a href ng-click="ctrl.showModal()">Show the modal</a>
</div>

Animations

With Angular 1.2, ngAnimate needs to be loaded as a separate module and injected as a dependency. Upon modal activate and deactivate, animation css classes are automatically added to the element.

app.js

angular.module('myApp', ['btford.modal', 'ngAnimate']).
// ...

modal.css

// ...
.btf-modal.ng-enter {
  transition: 1s linear all;
  opacity: 0;
}
.btf-modal.ng-enter.ng-enter-active {
  opacity: 1;
}
.btf-modal.ng-leave {
  transition: 1s linear all;
  opacity: 1;
}
.btf-modal.ng-leave.ng-leave-active {
  transition: 1s linear all;
  opacity: 0;
}

Note: the container in which the element is attached to must be under ng-app where ngAnimate is injected.

Cleaning up

If you add any listeners within the modal's controller that are outside the modal's scope, you should remove them with $scope.$on('$destroy', fn () { ... }) to avoid creating a memory leak.

Building on the example above:

app.js

// ...
controller('MyModalCtrl', function (myModal, $timeout) {

  var ctrl = this,
      timeoutId;

  ctrl.tickCount = 5;

  ctrl.closeMe = function () {
    cancelTick();
    myModal.deactivate();
  };

  function tick() {
    timeoutId = $timeout(function() {
      ctrl.tickCount -= 1;
      if (ctrl.tickCount <= 0) {
        ctrl.closeMe();
      } else {
        tick();
      }
    }, 1000);
  }

  function cancelTick() {
    $timeout.cancel(timeoutId);
  }

  $scope.$on('$destroy', cancelTick);

  tick();
}).
// ...

Inline Options

Note: The best practice is to use a separate file for the template and a separate declaration for the controller, but inlining these options might be more pragmatic for cases where the template or controller is just a couple lines.

angular.module('myApp', []).

// let's make a modal called myModal
factory('myModal', function (btfModal) {
  return btfModal({
    controller: function () {
      this.name = 'World';
    },
    controllerAs: 'ctrl',
    template: '<div class="btf-modal">Hello {{ctrl.name}}</div>'
  });
}).

controller('MyCtrl', function (myModal) {
  this.showModal = myModal.activate;
});

<div ng-app="myApp" ng-controller="MyCtrl">
  <a href ng-click="ctrl.showModal()">Show the modal</a>
</div>

API

btfModal

The modal factory. Takes a configuration object as a parameter:

var modalService = btfModal({
  /* options */
})

And returns a modalService object that you can use to show/hide the modal (described below).

The config object must either have a template or a templateUrl option.

These options work just like the route configuration in Angular's $routeProvider.

config.template

string: HTML string of the template to be used for this modal. Unless the template is very simple, you should probably use config.templateUrl instead.

config.templateUrl

string (recommended): URL to the HTML template to be used for this modal.

config.controller

string|function (optional): The name of a controller or a controller function.

config.controllerAs

string (optional, recommended): Makes the controller available on the scope of the modal as the given name.

config.container

DOM Node (optional): DOM node to prepend . Defaults to document.body.

modalService

A modalService has just two methods: activate and deactivate.

modalService.activate

Takes a hash of objects to add to the scope of the modal as locals. Adds the modal to the DOM by prepending it to the <body>. Returns a promise that resolves once the modal is active.

modalService.deactivate

Removes the modal (DOM and scope) from the DOM. Returns a promise that resolves once the modal is removed.

modalService.active

Returns whether or not the modal is currently activated.

Tests

You can run the tests with karma:

karma start karma.conf.js

License

MIT