Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/m-e-conroy/angular-dialog-service

A complete AngularJS service with controllers and templates for generating application modals and dialogs for use with Angular-UI-Bootstrap and Twitter Bootstrap
https://github.com/m-e-conroy/angular-dialog-service

Last synced: 3 months ago
JSON representation

A complete AngularJS service with controllers and templates for generating application modals and dialogs for use with Angular-UI-Bootstrap and Twitter Bootstrap

Awesome Lists containing this project

README

        

Angular Dialog Service
======================

>**Please use one of the release versions rather than the Master Branch**. The Master Branch has untested merges and changes and is a work in progress. I urge you to always use a release version rather than linking directly to the Master Branch, as the Master Branch may change and may not always be backward compatible.

**v4.x.x + is not backward compatible with versions 1,2,3,3.1 Please refer to the changes section to view what is different in v4.0**

A complete AngularJS service with controllers and templates for generating application modals and dialogs for use with Angular-UI-Bootstrap, Twitter Bootstrap and Font-Awesome. Supports, i18n, language translations for dialog headers, messages and buttons via angular-translate.

Installation
-----
Bower
```bower install angular-dialog-service --save```

Npm
```npm install angular-dialog-service --save ```

Importing to project **( ES6 )**

```import 'angular-dialog-service';```

Usage
-----

```javascript
var app = angular.module("MyApp", ['dialogs.main']);

app.controller("MyCtrl", function(dialogs){
// open dialogs here
});
```

```dialogs.error('Error','An unknown error occurred preventing the completion of the requested action.');```

```dialogs.wait('Creating User','Please wait while we attempt to create user "Michael Conroy."

This should only take a moment.',50);```

```dialogs.notify('Something Happened','Something happened at this point in the application that I wish to let you know about');```

```dialogs.create('url/to/a/template','ctrlrToUse',{data: topass,anotherVar: 'value'},{},'ctrl');```

### API

All Dialogs return a object with property `result` which is a promise `OK/Yes` resolves the promise `Close/Reject/No` rejects the promise

#### dialogs.error, dialogs.notify, dialogs.confirm

```dialogs.error(header, msg, opts)```

```dialogs.notify(header, msg, opts)```

```dialogs.confirm(header, msg, opts)```

| Name | Type | Description |
|---|---|---|
| header | `string` | Dialog header text. |
| msg | `string` | Dialog body text. |
| opts | `object` | Options for the dialog |

#### dialogs.wait

```dialogs.wait(header, msg, progress, opts)```

| Name | Type | Description |
|---|---|---|
| header | `string` | Dialog header text. |
| msg | `string` | Dialog body text. |
| progress | `int` | progress in percentage |
| opts | `object` | Options for the dialog |

#### dialogs.create

```dialogs.create(url, ctrlr, data, opts, ctrlAs)```

| Name | Type | Description |
|---|---|---|
| url | `string` | Template Url |
| ctrlr | `string` | Dialog Controller |
| data | `object` | data available as a "data" service in the controller |
| opts | `object` | Options for the dialog with the addition of `copy: false|true` which will copy the data instead of passing reference |
| ctrlAs | `string` | `controllerAs` reference

#### IDialogOptions Properties

Note: All properties are optional

| Name | Type | Description |
| --- | --- | --- |
| animation | `boolean` | Set to false to disable animations on new modal/backdrop. Does not toggle animations for modals/backdrops that are already displayed. |
| backdrop | `boolean|string` | controls the presence of a backdrop Allowed values: - true (default) - false (no backdrop) - 'static' backdrop is present but modal window is not closed when clicking outside of the modal window |
| keyboard | `boolean` | indicates whether the dialog should be closable by hitting the ESC key |
| backdropClass | `string` | additional CSS class(es) to be added to a modal backdrop template |
| windowClass | `string` | additional CSS class(es) to be added to a modal window template |
| size | `string` | Optional suffix of modal window class. The value used is appended to the `modal-` class, i.e. a value of `sm` gives `modal-sm`. |
| btnMessages | `object` | Optional map object redefining the text of a dialog button. This is only passed to built-in dialogs. The key to this object should be the same as the translation key. (ex. `DIALOGS_YES` and `DIALOGS_NO` for the `confirm` dialog) |

### Callbacks

Every dialog method ( confirm, wait,error,create ) return object with **result** property, **result** is Promise. Example usage with confirm:

```javascript
dialogs.confirm("Confirmation",'Do you want really do this action?')
.result
.then( function(){ console.log("Yes"); } )
.then( function(){ console.log("No"); } );
```

TODO: Add more usage explanations.

Demos
-----
- v4.2 : [Codepen: http://codepen.io/m-e-conroy/pen/rkIqv](http://codepen.io/m-e-conroy/pen/rkIqv)
- v4.2 : [Codepen: with UI-Bootstrap Date Picker directive](http://codepen.io/m-e-conroy/pen/DAxzs)
- v2.0 : [Codepen: http://codepen.io/m-e-conroy/pen/AmBpL](http://codepen.io/m-e-conroy/pen/AmBpL)
- v1.0 : [Codepen: http://codepen.io/m-e-conroy/pen/ALsdF](http://codepen.io/m-e-conroy/pen/ALsdF)

Release Versions
----------------
- v5.2.8 : Patched problem with animations when ngAnimate is available and using Angular-Bootstrap 0.13.0 [(issue #117)](https://github.com/m-e-conroy/angular-dialog-service/issues/117)
- v5.2.5 : Better detection of Font-Awesome if style sheet has been concatentated. Tested against Angular 1.3.0 & Angular-Bootstrap 0.11.2
- v5.2.2 - v5.2.4 : small bugs fixes
- v5.2.1 : supports Font-Awesome
- v5.2.x : Angular-Translate made optional
- v4.2.0 - v5.x.x+ : supports AngularJS 1.2 +, Angular UI Bootstrap 0.11.0, Bootstrap 3.1 +
- v4.0.0 - v4.1.0 : supports AngularJS 1.2 +, Angular UI Bootstrap 0.10.0, Bootstrap 3 +
- v3.0 : supports AngularJS 1.2 +, Angular UI Bootstrap 0.10.0
- v2.0 : supports AngularJS 1.2 +
- v1.0 : supports AngularJS 1.1.5 and below.

v5.2.8
------
1. Added support for these options: animation & backdropClass - because there is a problem when using Angular-Bootstrap 0.13.0's modal with ngAnimate (Angular v1.4) animation is turned off by default (https://github.com/angular-ui/bootstrap/issues/3633)

v5.2.1
------
1. Added support for Font-Awesome.
2. Added Example/faChk.html to show font-awesome inclusion.

v5.2.0
------
1. Made Angular-Translate dependency optional.
2. Added Example/index2.html to show dialog service working without including Angular-Translate.

v5.1.3
------
1. Bug fixes with regards to v5.1.2 #2 (issue #64)

v5.1.2
------
1. Bug fix for _setOpts (issue #61).
2. Changed the way resolved *header* and *msg* data is passed to the controller, so it would be easier to **decorate** each service if one so desires (issue #60).

v5.1.0
------
1. Fixed Wait dialog template, header should now display a passed parameter header to the wait service. Prior to this it would always display the default header whether or not a passed header parameter was used or not.
2. Default translations have been removed from the dialogs.main module to their own module, in order to support applications that were already using Angular-Translate and had already defined translation lists for 'en-US.' Previously including dialogs.main would have overwritten those translation lists supplied elsewhere in an application. To use the default translations:
- Include the dialogs-default-translations.min.js file in your HTML file and add 'dialogs.default-translations' to your application's dependency list along with 'dialogs.main'
- OR If you already had a translation list setup elsewhere in your application just copy the $translationProvider translation list in the dialogs-default-translations module to where-ever it is that you have your list configured

v5.0.0
------
Re-introduction of the [opts] parameter to dialogs methods. I had many complaints about removing method level options in favor of wholly using the provider instead.

1. dialogs.error(header,msg[,opts])
2. dialogs.wait(header,msg,progress[,opts])
3. dialogs.notify(header,msg[,opts])
4. dialogs.confirm(header,msg[,opts])
5. dialogs.create(url,ctrlr,data[,opts])

v4.2.0
------
Bootstrap 3.1.1 / Angular UI Bootstrap 0.11.0 introduced a size property for dialogs. This can be controlled via the provider or by the optional *sz* parameter to the dialog methods.

1. dialogs.error(header,msg[,sz])
2. dialogs.wait(header,msg,progress[,sz])
3. dialogs.notify(header,msg[,sz])
4. dialogs.confirm(header,msg[,sz])
5. dialogs.create(url,ctrlr,data[,sz])

v4.0.0 - 4.1.0
--------------
Removed *opts* and *static* parameters from dialog methods in favor of provider settings. The dialogs service is now longer **$dialogs**, the *\$* has be removed as this is reserved for Angular core services.

1. dialogs.error(header,msg)
2. dialogs.wait(header,msg,progress)
3. dialogs.notify(header,msg)
4. dialogs.confirm(header,msg)
5. dialogs.create(url,ctrlr,data)

v1.0 - v3.1.0
-------------
Predefined dialogs/modals.

1. $dialogs.error(header,msg,[static])
2. $dialogs.wait(header,msg,progess,[static])
3. $dialogs.notify(header,msg,[static])
4. $dialogs.confirm(header,msg,[static])
5. $dialogs.create(url,ctrlr,data,opts)

Dependencies
------------

v5.2.1 +
--------
1. [Font-Awesome](http://fortawesome.github.io/Font-Awesome/) is now an optional CSS inclusion.

v5.2.x +
--------
1. [Angular Translate](https://github.com/angular-translate) is now optional.

v4.2.0 & v5.x.x
---------------
Same as v4.0.0 with the exception of the following:

1. [Angular UI Bootstrap Modal 0.11.0, with templates](http://angular-ui.github.io/bootstrap/#/modal)
2. [Twitter Bootstrap CSS 3.1.x](http://getbootstrap.com)

v4.0.0 - v4.1.0
---------------
1. AngularJS 1.2 +
2. [Angular UI Bootstrap Modal 0.10.0, with templates](http://angular-ui.github.io/bootstrap/#/modal)
3. Twitter Bootstrap CSS 3 + (includes 3.1.1)
4. Angular ngSanitize
5. [Angular Translate](https://github.com/angular-translate)

v3.0
----
1. AngularJS 1.2 +
2. Angular UI Bootstrap 0.10.0
3. Twitter Bootstrap CSS 3.0.3
4. AngularJS ngSanitize

v2.0 Additional Dependencies
----------------------------
1. All version 1.0 dependencies.
2. [Angular JS ngSanitize](http://code.angularjs.org/1.2.1/angular-sanitize.min.js)
- [ngSanitize](http://docs.angularjs.org/api/ngSanitize) (needed for ng-bind-html)

v1.0
----
1. [Angular JS](http://www.angularjs.org) (version 1.1.5 and less)
2. [Angular UI Bootstrap](http://angular-ui.github.io/bootstrap/#/modal) (version <= 0.6.0, Non-Bootstrap 3 Branch) with embedded templates.
3. [Twitter Bootstrap CSS](http://getbootstrap.com) (version 2)

CSS
---
Included a css file that has a .modal class fix for Bootstrap and also has some predefined styles for the various modals described in the service.

**v3.0 css file has the .modal class removed that had been a fix for a Bootstrap 3 display problem. This has since been rectified by Angular UI and Bootstrap.**

Changes
-------

- v5.2.1
1. If you use Font-Awesome, support is now provided for the icons used in the headers of each predefined dialog. The dialog service will automatically detect whether you have Font-Awesome loaded or not and use FA icons or the Bootstrap's glyphicons accordingly. If for some reason the detection doesn't work correctly you can force the use of FA icons by injecting *dialogsProvider* into your module's config function and calling **dialogsProvider.useFontAwesome()**.

- v5.2.x
1. Angular-Translate is now optional, however in order to keep support for Angular-Translate and be able to switch it on and off easily without having to add lines of code to your modules I created a substitute module that is automatically included and used when Angular-Translate is not found. This subsitute (*translate-substitution.js : translate.sub*) is a provider service (*$translateProvider*) with the same *translations* method as the Angular-Translate provider service does. The provider service is also named *$translate* and has its own *instant* method. I did this such that, if in the future you do decide to use Angular-Translate all you will have to do is load the module before the dialog's service is loaded.
2. The *dialogs-default-translations.js* file is also now an optional dependency.

- v5.1.0
1. Separated out the default translations into their own module: **dialogs-default-translations.js** Include this or the "min" version in your application if you are not already using $translationProvider elsewhere, otherwise just copy the translation list within the module to your translation list for 'en-US.'

- v5.0.0
1. Optionally pass in options object, possible overrides are as follows

```
opts = {
'keyboard': true or false
'backdrop': 'static' or true or false
'size': 'sm' or 'lg' //small or large modal size
'windowClass': 'dialogs-default' // additional CSS class(es) to be added to a modal window
'copy': true or false // used only with create custom dialog
}
```

- v4.2.0
1. Supports everything described above in v4.0.0 - v4.1.0 and added the following

2. dialogsProvider.setSize(['sm','lg']) - This will set modal size application wide, but can be overridden using the *sz* parameter added to each dialog method call.

- v4.0.0 - v4.1.0
1. Removed *\$* from the *\$dialogs* service as this is reserved for core AngularJS naming. The service is now just *dialogs.* Include **dialogs.main** in your application module in order to use the the *dialogs* service
2. Changed *dialogs* service from factory to provider, you can now use **dialogsProvider** to set various options of the modals that were previously passed as parameters to the dialogs' service methods.
- **dialogsProvider.useBackdrop([true,false,'static'])** - True or false to use a backdrop for the modal, 'static' to use a backdrop and disallow closing on mouse click of the backdrop.
- **dialogsProvider.useEscClose([true,false])** - Whether or not to allow the use of the 'ESC' key to close the modal
- **dialogsProvider.useClass([string])** - Sets an additional CSS class to the modal window
- **dialogsProvider.useCopy([true,false])** - Determines whether to use angular.copy or not when passing a data object to the custom dialog service. Setting this to false will allow the modal to retain the two-way binding with the calling controller - thus changing data in the modal will automatically change it in the calling controller's scope. The default is setting is true, so if you want the two-way binding you need to set this to false.
3. Main module is no longer *dialogs* as this would conflict with the new naming of the service. It is now *dialogs.main,* include that in your application's module definition to use the *dialogs* service.
4. Added i18n support via [Angular-Translate](https://github.com/angular-translate), use the *$translateProvider* to set language specific defaults. Default language is currently *en-US.* An example is provided in the example folder that will show you how to change the defaults from English to Spanish. Translations can be set on the following:
- DIALOGS_ERROR (modal header)
- DIALOGS_ERROR_MSG
- DIALOGS_CLOSE (modal button)
- DIALOGS_PLEASE_WAIT (modal header)
- DIALOGS_PLEASE_WAIT_ELIPS (modal header)
- DIALOGS_PLEASE_WAIT_MSG
- DIALOGS_PERCENT_COMPLETE (modal message partial)
- DIALOGS_NOTIFICATION (modal header)
- DIALOGS_NOTIFICATION_MSG
- DIALOGS_CONFIRMATION (modal header)
- DIALOGS_CONFIRMATION_MSG
- DIALOGS_OK (modal button)
- DIALOGS_YES (modal button)
- DIALOGS_NO (modal button)

- v3.0
1. Added support for Angular UI Bootstrap 0.10.0.
2. Added the ability to customize the header on the error and wait dialogs.
3. Added example files.

Notes
-----

- Angular Translate: v4.0 requires [Angular-Translate](https://github.com/angular-translate) be included.
- Bootstrap 3: There's a problem with the actual modal being displayed even though it appears in the HTML code to be present. I found that adding a "display: block" to Bootstrap 3's .modal class solved the problem. *(v3.0 of this service no longer requires this fix)*
- It should not rely on including the Bootstrap JS.
- For version 2.0 + of this service module do not forget to include the *ngSanitize* Angular module.

Contributing
------------

Install Dependencies

```
npm install --dev
bower install
```

For Browser Testing `gulp watch`

For Unit Testing `npm test`

> Written with [StackEdit](https://stackedit.io/).