ng2-modal-module

1. Description
2. Installation
3. Usage
4. Ng2ModalWindow static methods
5. ModalWindow Options
6. Examples
7. Git repository
8. Build
9. Publish to npm
10. Version

1. Description

ng2-modal-module or ModalModule is a module for angular2+ which exposes the bootstrap (3.3.*) modal component (no jQuery required!!!) with the util class Ng2ModalWindow which makes the component usage easier.
It is based on pubsub-distinct.

2. Installation

Install the module into your application and save it as a dev dependency in your package.json file

npm install ng2-modal-module --save-dev

WARNIGNG Don't forget to include the bootstrap (3.3.*) styles!

3. Usage

In order to use the ModalModule module you have to include/import it into your application:

import {ModalModule} from 'ng2-modal-module';

Add the module into the app's module imports section:

import { ModalModule } from 'ng2-modal-module';

@NgModule({
  //...
  imports: [
	//...
	ModalModule // <<--- HERE
  ],
  //...
})

Include the modal component into your template:

<ng2-modal-window id="{{modalId}}"></ng2-modal-window>

where modalId is a unique ID of the modal component.

Call the modal component (display or hide it) using the Ng2ModalWindow util class:

import { Component, OnInit } from '@angular/core';
import { Ng2ModalWindow } from 'ng2-modal-module';

export class AppComponent  implements OnInit {  
  modalId: string = 'modalId';  
  
  constructor() {  
  }  
  
  ngOnInit() {  
    Ng2ModalWindow.showModal(this.modalId, {  
      title: 'Modal title',  
      htmlContent: 'Modal content'  
    });  
  }  
}

4. Ng2ModalWindow static methods

showModal(modalId: string, options: any = {}): void

Display the Ng2ModalWindowComponent

Parameters:
modalId - Id of the modal window which should be displayed
options - Options used to customize the displayed modal window The options list is described here.

Return:
Method returns nothing - void.

hideModal(modalId: string): void

Hide the Ng2ModalWindowComponent

Parameters:
modalId - Id of the modal window which should be hidden

Return:
Method returns nothing - void.

resetEventsSubscribers(eventsList: any[]): void

Reset (remove) the events subscribers of the Ng2ModalWindowComponent actions buttons if such events are provided using the options parameter.

Parameters:
eventsList - List of events name which should be removed/unsubscribed

Return:
Method returns nothing - void.

5. ModalWindow Options

| Option | Type | Default | Description | Example | |:------------------------|:--------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------| | componentInputs | Object | NULL | Properties list of the dynamically injected component into the modal's body | {title: 'new value of the title property of the injected component'} | | componentSelector | String | NULL | Selector of the component which should be injected dynamically into the modal's body | {componentSelector: 'test-component'} | | customClass | String | NULL | Custom class which will be attached to the modal window. Here can be passed the bootstraps classes which handle the size of the modal (modal-lg, modal-sm etc.) | {customClass: 'modal-lg'} | | hide | Boolean | NULL | Forcibly hide the modal window when its value is true | {hide: true} | | htmlContent | String | Empty | The HTML content which should be injected in the modal's body as innerHTML content (HTML tags are not escaped!) | {htmlContent: '<strong>test content</strong>'} | | overlayClick | Boolean | true | Enable/disable the click over the modal's overlay. If it's true then the click over the overlay hides/closes the modal window. | {overlayClick: false} // disable the overlay click | | show | Boolean | NULL | Forcibly shows/display the modal window if its value is true | {show: true} | | showEvent | String | NULL | Name of the event which will be triggered when the modal window is displayed | {showEvent: 'show-event'} | | title | String | Empty | Title of the modal window | {title: 'Modal window title'} | | buttons.visible | Boolean | true | Display or hide the footer section with the action buttons (cancel/success). true - buttons are visible false - buttons are hidden | {buttons: {visible: false}} // hide buttons | | buttons.cancel.visible | Boolean | true | Display or hide the cancel button true - button is visible false - button is hidden | {buttons: {cancel: {visible: false}}} // hide cancel button | | buttons.cancel.label | String | 'Cancel' | Label of the cancel button | {buttons: {cancel: {label: 'Close'}}} | | buttons.cancel.event | String | NULL | Name of the event which will be triggered (using pubsub-distinct) when the cancel button is clicked | {buttons: {cancel: {event: 'cancel-event'}}} | | buttons.success.visible | Boolean | true | Display or hide the success button true - button is visible false - button is hidden | {buttons: {success: {visible: false}}} // hide success button | | buttons.success.label | String | 'Save' | Label of the success button | {buttons: {success: {label: 'Save changes'}}} | | buttons.success.event | String | NULL | Name of the event which will be triggered (using pubsub-distinct) when the success button is clicked | {buttons: {cancel: {event: 'success-event'}}} |

6. Examples

Before using the Ng2ModalWindowComponent don't forget to import the Ng2ModalWindow util class into your component/service:

import { Ng2ModalWindow } from 'ng2-modal-module';

//...
// define an unique ID for the modal component
modalId: string = 'test-modal-window';
//...

1. display simple modal window:

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: 'Modal content'
});

2. display modal with the disabled overlay, HTML content and custom class (large modal window)

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: '<b>test bold</b> and simple text',
  customClass: 'modal-lg',
  overlayClick: false
});

3. display modal window without footer (action buttons are hidden).

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: 'modal content',
  buttons: {
    visible: false
  }
});

4. display modal without the success button:

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: 'modal content',
  buttons: {
    success: {visible: false}
  }
});

5. inject a custom component into the modal's body/content

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  componentSelector: 'app-test'
});

where app-test is the selector of the component which should be injected in the modal window.
WARNING! To make it dynamically injectable, the component app-test should be included in the entryComponents: [] list of the @NgModule(...) of your application module;

6. inject a custom component into the modal's body/content and pass some custom properties to it

Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  componentSelector: 'app-test',
  componentInputs: {componentTitle: 'CUSTOM TITLE'}
});

where componentTitle is a public property of the component app-test.

7. register custom events for the actions buttons of the modal window and subscribe to them

// events names  
let successEventName = 'successEvent';  
let cancelEventName = 'cancelEvent';  
  
// remove previously added subscriber and publisher  
Ng2ModalWindow.resetEventsSubscribers([successEventName, cancelEventName]);  
  
// pass the events name to the modal window component  
Ng2ModalWindow.showModal(this.modalId, {  
  title: 'Modal title',  
  htmlContent: 'listen actions events',  
  buttons: {  
    cancel: { event: cancelEventName },  
    success: { event: successEventName }  
  }  
});  
  
// subscribe to events 
Ng2ModalWindow.subscribe(successEventName, (data) => {  
  console.log('successEventName triggered!', data);  
  // hide modal  
  Ng2ModalWindow.hideModal(this.modalId); 
});  
Ng2ModalWindow.subscribe(cancelEventName, (data) => {  
  console.log('cancelEventName triggered!', data);  
});

Before registering new events listeners, is suggested to remove them if they are already subscribed to the same events:

Ng2ModalWindow.resetEventsSubscribers([successEventName, cancelEventName]);

8. hide already visible modal window

Ng2ModalWindow.hideModal(this.modalId); 

7. Git repository

https://github.com/kageoni/ng2-modal-module

8. Build

To build the final package run this command:

ng build ng2-modal

The build process will generate the packed sources into the dist folder.

9. Publish to npm

To publish the new version to npm, go into the dist folder:

cd ./dist/ng2-modal

and publish it to npm:

npm publish

10. Version

1.0.1