angular-modal

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

Install

bower install angular-modal

Usage

Include the modal.js script provided by this component into your app.
Optional: Include the modal.css style provided by this component into your html.
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

joeljeske / angular-modal