joeljeske / angular-modal

Simple AngularJS service for creating modals

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

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>

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.

config.open

function (optional): Callback function when the modal is opened.

config.close

function (optional): Callback function when the modal is closed.

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>. The return is a promise that resolves whenever deactivate is called with the parameter passed to deactivate. It only rejects if the the activate and attach service fails.

modalService.deactivate

Removes the modal (DOM and scope) from the DOM. The parameter passed to this object is the resolve parameter for promise returned by the activate function.

modalService.active

Returns whether or not the modal is currently activated.

Tests

You can run the tests with karma:

karma start karma-unit.conf.js

License

MIT