Skip to content

Latest commit

 

History

History
268 lines (223 loc) · 11.7 KB

README.md

File metadata and controls

268 lines (223 loc) · 11.7 KB

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'
});
  1. 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
});
  1. display modal window without footer (action buttons are hidden).
Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: 'modal content',
  buttons: {
    visible: false
  }
});
  1. display modal without the success button:
Ng2ModalWindow.showModal(this.modalId, {
  title: 'Modal title',
  htmlContent: 'modal content',
  buttons: {
    success: {visible: false}
  }
});
  1. 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;

  1. 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.

  1. 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]);
  1. 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