feat(module:modal): add afterClose and more to improve communication …

…capabilities

close NG-ZORRO#1155

components/modal/demo/async.ts

@@ -6,7 +6,7 @@ import { Component } from '@angular/core';
     <button nz-button nzType="primary" (click)="showModal()">
       <span>Show Modal</span>
     </button>
-    <nz-modal [(nzVisible)]="isVisible" nzTitle="Modal Title" (nzOnCancel)="handleCancel($event)" (nzOnOk)="handleOk($event)" [nzOkLoading]="isOkLoading">
+    <nz-modal [(nzVisible)]="isVisible" nzTitle="Modal Title" (nzOnCancel)="handleCancel()" (nzOnOk)="handleOk()" [nzOkLoading]="isOkLoading">
       <p>Modal Content</p>
     </nz-modal>
   `,
@@ -20,15 +20,15 @@ export class NzDemoModalAsyncComponent {
     this.isVisible = true;
   }
 
-  handleOk($event: MouseEvent): void {
+  handleOk(): void {
     this.isOkLoading = true;
     window.setTimeout(() => {
       this.isVisible = false;
       this.isOkLoading = false;
     }, 3000);
   }
 
-  handleCancel($event: MouseEvent): void {
+  handleCancel(): void {
     this.isVisible = false;
   }
 }

components/modal/demo/basic.ts

@@ -4,7 +4,7 @@ import { Component } from '@angular/core';
   selector: 'nz-demo-modal-basic',
   template: `
     <button nz-button [nzType]="'primary'" (click)="showModal()"><span>Show Modal</span></button>
-    <nz-modal [(nzVisible)]="isVisible" nzTitle="The first Modal" (nzOnCancel)="handleCancel($event)" (nzOnOk)="handleOk($event)">
+    <nz-modal [(nzVisible)]="isVisible" nzTitle="The first Modal" (nzOnCancel)="handleCancel()" (nzOnOk)="handleOk()">
       <p>Content one</p>
       <p>Content two</p>
       <p>Content three</p>
@@ -21,13 +21,13 @@ export class NzDemoModalBasicComponent {
     this.isVisible = true;
   }
 
-  handleOk($event: MouseEvent): void {
+  handleOk(): void {
     console.log('Button ok clicked!');
     this.isVisible = false;
   }
 
-  handleCancel($event: MouseEvent): void {
-    console.log('Button cancel clicked!', $event);
+  handleCancel(): void {
+    console.log('Button cancel clicked!');
     this.isVisible = false;
   }
 }

components/modal/demo/confirm-promise.ts

@@ -1,5 +1,5 @@
 import { Component } from '@angular/core';
-import { ModalPublicAgent, NzModalService } from 'ng-zorro-antd';
+import { NzModalRef, NzModalService } from 'ng-zorro-antd';
 
 @Component({
   selector: 'nz-demo-modal-confirm-promise',
@@ -9,7 +9,7 @@ import { ModalPublicAgent, NzModalService } from 'ng-zorro-antd';
   styles  : []
 })
 export class NzDemoModalConfirmPromiseComponent {
-  confirmModal: ModalPublicAgent; // For testing by now
+  confirmModal: NzModalRef; // For testing by now
 
   constructor(private modal: NzModalService) { }
 

components/modal/demo/footer.ts

@@ -7,7 +7,7 @@ import { Component } from '@angular/core';
     <button nz-button nzType="primary" (click)="showModal()">
       <span>Show Modal</span>
     </button>
-    <nz-modal [(nzVisible)]="isVisible" [nzTitle]="modalTitle" [nzContent]="modalContent" [nzFooter]="modalFooter" (nzOnCancel)="handleCancel($event)">
+    <nz-modal [(nzVisible)]="isVisible" [nzTitle]="modalTitle" [nzContent]="modalContent" [nzFooter]="modalFooter" (nzOnCancel)="handleCancel()">
       <ng-template #modalTitle>
         Custom Modal Title
       </ng-template>
@@ -22,8 +22,8 @@ import { Component } from '@angular/core';
 
       <ng-template #modalFooter>
         <span>Modal Footer: </span>
-        <button nz-button nzType="default" (click)="handleCancel($event)">Custom Callback</button>
-        <button nz-button nzType="primary" (click)="handleOk($event)" [nzLoading]="isConfirmLoading">Custom Submit</button>
+        <button nz-button nzType="default" (click)="handleCancel()">Custom Callback</button>
+        <button nz-button nzType="primary" (click)="handleOk()" [nzLoading]="isConfirmLoading">Custom Submit</button>
       </ng-template>
     </nz-modal>
   `,
@@ -39,15 +39,15 @@ export class NzDemoModalFooterComponent {
     this.isVisible = true;
   }
 
-  handleOk($event: MouseEvent): void {
+  handleOk(): void {
     this.isConfirmLoading = true;
     setTimeout(() => {
       this.isVisible = false;
       this.isConfirmLoading = false;
     }, 3000);
   }
 
-  handleCancel($event: MouseEvent): void {
+  handleCancel(): void {
     this.isVisible = false;
   }
 }

components/modal/demo/service.ts

@@ -1,7 +1,7 @@
 /* entryComponents: NzModalCustomComponent */
 
 import { Component, Input, TemplateRef } from '@angular/core';
-import { ModalPublicAgent, NzModalService } from 'ng-zorro-antd';
+import { NzModalRef, NzModalService } from 'ng-zorro-antd';
 
 @Component({
   selector: 'nz-demo-modal-service',
@@ -37,7 +37,7 @@ import { ModalPublicAgent, NzModalService } from 'ng-zorro-antd';
   `
 })
 export class NzDemoModalServiceComponent {
-  tplModal: ModalPublicAgent;
+  tplModal: NzModalRef;
   tplModalButtonLoading = false;
 
   constructor(private modalService: NzModalService) { }
@@ -80,15 +80,18 @@ export class NzDemoModalServiceComponent {
       },
       nzFooter: [{
         label: 'change component tilte from outside',
-        onClick: (componentInstance: NzModalCustomComponent) => {
+        onClick: (componentInstance) => {
           componentInstance.title = 'title in inner component is changed';
         }
       }]
     });
 
+    // Return a result when closed
+    modal.afterClose().subscribe((result) => console.log('[afterClose] The result is:', result));
+
     // delay until modal instance created
     window.setTimeout(() => {
-      const instance = modal.getContentComponentRef().instance as NzModalCustomComponent;
+      const instance = modal.getContentComponent();
       instance.subtitle = 'sub title is changed';
     }, 2000);
   }
@@ -149,9 +152,9 @@ export class NzModalCustomComponent {
   @Input() title: string;
   @Input() subtitle: string;
 
-  constructor(private modal: ModalPublicAgent) { }
+  constructor(private modal: NzModalRef) { }
 
   destroyModal(): void {
-    this.modal.destroy();
+    this.modal.destroy({ data: 'this the result data' });
   }
 }

components/modal/doc/index.en-US.md

@@ -14,7 +14,7 @@ getting feedback or information purposes.
 Additionally, if you need show a simple confirmation dialog, you can use `NzModalService.confirm()`,
 and so on.
 
-It is recommended to use the `Component` way to pop up the Modal, so that the component logic of the popup layer can be completely isolated from the outer component, and can be reused at any time. In the popup layer component, you can obtain Modal's component instance by injecting `ModalPublicAgent` to control the behavior of the modal box.
+It is recommended to use the `Component` way to pop up the Modal, so that the component logic of the popup layer can be completely isolated from the outer component, and can be reused at any time. In the popup layer component, you can obtain Modal's component instance by injecting `NzModalRef` to control the behavior of the modal box.
 
 
 ## API
@@ -30,7 +30,7 @@ The dialog is currently divided into 2 modes, `normal mode` and `confirm box mod
 | nzOkLoading       | Whether to apply loading visual effect for OK button or not | boolean | false |
 | nzCancelLoading   | Whether to apply loading visual effect for Cancel button or not | boolean | false |
 | nzFooter          | Footer content, set as footer=null when you don't need default buttons. <i>1. Only valid in normal mode.<br>2. You can customize the buttons to the maximum extent by passing a `ModalButtonOptions` configuration (see the case or the instructions below).</i> | string<br>TemplateRef<br>ModalButtonOptions | OK and Cancel buttons |
-| nzGetContainer    | The mount node for Modal | HTMLElement / () => HTMLElement| Handled by overlay container |
+| nzGetContainer    | The mount node for Modal | HTMLElement / () => HTMLElement| A default container |
 | nzMask            | Whether show mask or not. | boolean | true |
 | nzMaskClosable    | Whether to close the modal dialog when the mask (area outside the modal) is clicked | boolean | true |
 | nzMaskStyle       | Style for modal's mask element. | object | - |
@@ -42,8 +42,8 @@ The dialog is currently divided into 2 modes, `normal mode` and `confirm box mod
 | nzWidth           | Width of the modal dialog. <i>When using numbers, the default unit is `px`</i> | string<br>number | 520 |
 | nzWrapClassName   | The class name of the container of the modal dialog | string | - |
 | nzZIndex          | The z-index of the Modal | number | 1000 |
-| nzOnCancel        | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button. <i>Note: When created with `NzModalService.create`, this parameter should be passed into the type of function (callback function). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | EventEmitter | - |
-| nzOnOk            | Specify a EventEmitter that will be emitted when a user clicks the OK button | EventEmitter | 无 |
+| nzOnCancel        | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button (If nzContent is Component, the Component instance will be put in as an argument). <i>Note: When created with `NzModalService.create`, this parameter should be passed into the type of function (callback function). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | EventEmitter | - |
+| nzOnOk            | Specify a EventEmitter that will be emitted when a user clicks the OK button (If nzContent is Component, the Component instance will be put in as an argument). <i>Note: When created with `NzModalService.create`, this parameter should be passed into the type of function (callback function). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | EventEmitter | 无 |
 | nzContent         | Content | string / TemplateRef / Component / ng-content | - |
 | nzComponentParams | When nzContent is a Component, the attributes in this parameter will be passed to the nzContent instance | object | - |
 | nzIconType        | Icon type of the Icon component. <i>Only valid in confirm box mode</i> | string | question-circle |
@@ -71,32 +71,33 @@ Consistent with the above API, some property types or initial values are differe
 
 | Property   | Description    | Type             | Default       |
 |------------|----------------|------------------|---------------|
-| nzOnOk          | Specify a EventEmitter that will be emitted when a user clicks the OK button. <i>This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | function | - |
-| nzOnCancel      | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button. <i>This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | function | - |
+| nzOnOk          | Specify a EventEmitter that will be emitted when a user clicks the OK button (If nzContent is Component, the Component instance will be put in as an argument.). <i>This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | function | - |
+| nzOnCancel      | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button (If nzContent is Component, the Component instance will be put in as an argument.). <i>This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return `false` to prevent closing)</i> | function | - |
 | nzWidth         | Width of the modal dialog | string / number | 416 |
 | nzMaskClosable  | Whether to close the modal dialog when the mask (area outside the modal) is clicked | boolean | false |
 
 All the `NzModalService.method`s will return a reference, and then we can close the popup by the reference.
 
 ```ts
 constructor(modal: NzModalService) {
-  const ref: ModalPublicAgent = modal.info();
+  const ref: NzModalRef = modal.info();
   ref.destroy(); // Note: This dialog will be destroyed directly
 }
 ```
 
 ### Related type definition
 
-#### ModalPublicAgent (used for control dialogs)
+#### NzModalRef (used for control dialogs)
 
-The dialog created by the service method `NzModalService.xxx()` will return a `ModalPublicAgent` object that is used to manipulate the dialog (this object can also be obtained by dependency injection `ModalPublicAgent` if `nzContent` is used as Component) , This object has the following methods:
+The dialog created by the service method `NzModalService.xxx()` will return a `NzModalRef` object that is used to manipulate the dialog (this object can also be obtained by dependency injection `NzModalRef` if `nzContent` is used as Component) , This object has the following methods:
 
 | Method | Description |
 |----|----|
 | open()                    | Open (display) dialog box. <i>Calling this function will fail if the dialog is already destroyed</i> |
 | close()                   | Close (hide) the dialog. <i>Note: When used for a dialog created as a service, this method will destroy the dialog directly (as with the destroy method)</i> |
 | destroy()                 | Destroy the dialog. <i>Note: Used only for dialogs created by the service (non-service created dialogs, this method only hides the dialog)</i> |
-| getContentComponentRef()  | Gets a Component reference (of type `ComponentRef`) in the contents of the dialog for `nzContent`. <i> Note: When the dialog is not initialized (`ngOnInit` is not executed), this function will return `undefined`</i> |
+| afterClose() | Returns an Observable object to get the result parameter passed in close/destroy (will fire after the dialog is closed) |
+| getContentComponent()  | Gets the Component instance in the contents of the dialog for `nzContent`. <i> Note: When the dialog is not initialized (`ngOnInit` is not executed), this function will return `undefined`</i> |
 
 #### ModalButtonOptions (used to customize the bottom button)