# Modals modal.js

`mgcrea.ngStrap.modal`

## Examples

Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.

### Live demo clog.info

    $scope.modal = {{modal | json}};

### 508 Usage

For modal dialogs to be 508 and screen reader compliant please use the following examples. The `backdrop` must be set to static and `keyboard` must be set to a truthy value. Please be aware that the directive use-case handles returning focus to the item which opens the modal dialog. In scenarios where the `$modal` service is used it will be up to the implementation to return focus to the element which initiated the action to open the dialog.

#### Backdrop animation

Backdrop animation being powered by `ngAnimate`, it requires custom CSS.

            .modal-backdrop.am-fade {
              opacity: .5;
              transition: opacity .15s linear;
              &.ng-enter {
                opacity: 0;
                &.ng-enter-active {
                  opacity: .5;
                }
              }
              &.ng-leave {
                opacity: .5;
                &.ng-leave-active {
                  opacity: 0;
                }
              }
            }

## Usage

Append a `bs-modal`attribute to any element to activate the directive.

#### The module also exposes a `$modal`service

Available for programmatic use (inside a directive/controller).

              angular.module('myApp')
              .controller('DemoCtrl', function($scope, $modal) {
                // Show a basic modal from a controller
                var myModal = $modal({title: 'My Title', content: 'My Content', show: true});

                // Pre-fetch an external template populated with a custom scope
                var myOtherModal = $modal({scope: $scope, template: 'modal/docs/modal.demo.tpl.html', show: false});
                // Show when some event occurs (use $promise property to ensure the template has been loaded)
                $scope.showModal = function() {
                  myOtherModal.$promise.then(myOtherModal.show);
                };
              })

### Options

Options can be passed via data-attributes on the directive or as an object hash to configure the service. For data attributes, append the option name to `data-`, as in `data-animation=""`.

For directives, you can naturally inherit the contextual `$scope` or leverage a custom one with an AngularJS expression to evaluate as an object directly on the `bs-modal` attribute

Name | type | default | description
--- | --- | --- | ---
animation | string | am-fade | apply a CSS animation powered by ngAnimate
backdropAnimation | string | am-fade | apply a CSS animation to backdrop powered by ngAnimate
placement | string | 'top' | how to position the modal - top | bottom | center (requires custom CSS).
title | string | '' | default title value if `title`attribute isn't present
content | string | '' | default content value if `data-content`attribute isn't present
html | boolean | false | replace `ng-bind` with `ng-bind-html`, requires `ngSanitize` to be loaded
backdrop | boolean or the string `'static'` | true | Includes a modal-backdrop element. Alternatively, specify `static`for a backdrop which doesn't close the modal on click.
keyboard | boolean | true | Closes the modal when escape key is pressed
show | boolean | true | Shows the modal when initialized.
container | string | false | false | Appends the popover to a specific element. Example: `container: 'body'`. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.
controller | string|function | false | Controller fn that should be associated with newly created scope or the name of a registered controller if passed as a string.
controllerAs | string | false | A controller alias name. If present the controller will be published to scope under the `controllerAs` name.
resolve | object | false | Object containing dependencies that will be injected into the controller's constructor when all the dependencies have resolved. The controller won't load if the promise is rejected.
locals | object | false | Object containing dependencies that will be injected into the controller's constructor. Similar to resolve but expects literal values instead of promises.
template | string | '' | Provide an html template as a string (when templateUrl is falsy).
templateUrl | path | 'modal/modal.tpl.html' | If provided, overrides the default template, can be either a remote URL or a cached template id. It should be a `div.modal` element following Bootstrap styles conventions (like this).
contentTemplate | path | false | If provided, fetches the partial and includes it as the inner content, can be either a remote URL or a cached template id.
prefixEvent | string | 'modal' | If provided, prefixes the events '.hide.before' '.hide' '.show.before' and '.show' with the passed in value. With the default value these events are 'modal.hide.before' 'modal.hide' 'modal.show.before' and 'modal.show'
id | string | '' | The modal instance id for usage in event handlers.
onShow | function |  | If provided, this function will be invoked after the modal is shown.
onBeforeShow | function |  | If provided, this function will be invoked before the modal is shown.
onHide | function |  | If provided, this function will be invoked after the modal is hidden.
onBeforeHide | function |  | If provided, this function will be invoked before the modal is hidden.
zIndex | number | 1050 | CSS z-index value for the modal.

#### Default options

You can override global defaults for the plugin with `$modalProvider.defaults`

              angular.module('myApp')
              .config(function($modalProvider) {
                angular.extend($modalProvider.defaults, {
                  animation: 'am-flip-x'
                });
              })

### Scope methods

Methods available inside the directive scope to toggle visibility.

#### $show()

Reveals the modal.

#### $hide()

Hides the modal.

#### $toggle()

Toggles the modal.