Today, I am going to show you how to create a reusable modal overlay/dialog using Angular CDK Overlay that can be reused inside our Angular project multiple times with ease. We are going to try and match the behavior and the functionality of Angular Material Dialog component, but using the UI Framework of our choice.
This is going to be the first of a few articles, focusing on ways you can utilize Angular CDK to implement common interaction patterns within your application.
Demo and Source Code
You can find the link to the demo here and the GitHub repo for this post here.
Prerequisites
Install Angular CLI and Create an Angular Project – Link.
Setup Bulma inside your Angular Project.
Install Angular CDK –
npm i @angular/cdk
oryarn add @angular/cdk
The article is divided into two sections:
- The Basics - a Quick look at how to use Angular CDK Overlay
- Building a Reusable Modal Overlay - A detailed guide into building a reusable modal overlay.
The Basics
Let us get the basics out of the way first. Assuming you have installed Angular CDK you will need to import OverlayModule
into your app module.
import {OverlayModule} from '@angular/cdk/overlay';
And then, inject the Overlay
service and ViewContainerRef into your component.
constructor(private overlay: Overlay, private viewContainerRef: ViewContainerRef) {}
To show a modal overlay, you need either a Template or an Angular Component holding the content you would like to show. Let’s look at how you can use both below:
Using a Template
Inside the template of our component, let’s define a new template and add our overlay content:
<ng-template #tpl>
<div class="modal-card">
<header class="modal-card-head">
…
</header>
<section class="modal-card-body">
…
</section>
<footer class="modal-card-foot">
…
</footer>
</div>
</ng-template>
Then, add a method to show the overlay and it accepts an ng-template
reference as the parameter.
openWithTemplate(tpl: TemplateRef<any>) {}
Then, Inside the above method, we are going to create an overlay. We will start by defining the configs of the overlay – OverlayConfig
. In our case, we will just set the hasBackdrop
and backdropClass
properties. For backdropClass
we are using modal-background
a Bulma CSS Framework class. You can find all the Overlay Configurations you can add here.
const configs = new OverlayConfig({
hasBackdrop: true,
backdropClass: 'modal-background'
});
Then, let’s create an OverlayRef
, by using the create
method of the Overlay service and pass the configs we just created above:
const overlayRef = this.overlay.create(configs);
And then we can attach our template, using TemplatePortal, passing our template and ViewContainerRef
which we injected into our component:
overlayRef.attach(new TemplatePortal(tpl, this.viewContainerRef));
Now, we can trigger the method with a click of a button:
<button (click)="openWithTemplate(tpl)" >
Show
</button>
Using a Component
The difference between the two is that we will be using ComponentPortal
instead of TemplatePortal
to attach the component to the OverlayRef
.
this.overlayRef.attach(
new ComponentPortal(OverlayComponent, this.viewContainerRef)
);
NB: The component must be added to the list of entryComponents
in your App Module.
Closing Modal Overlay on Backdrop Clip
You can close the overlay when the backdrop is clicked by subscribing to the backdropClick()
and then calling the dispose
method.
overlayRef.backdropClick().subscribe(() => overlayRef.dispose());
Making a Re-usable Modal Overlay
Building modal overlays as shown above works very well if you are building one or two of them, however, it does not scale very well. Wouldn’t it be nice if you could build a re-usable modal overlay that you can then use across your Angular project or projects? Wouldn’t it also be nice if we could be able to pass data to and receive data from the modal?
Objective
A service to open the modal, than can be injected into any component
A way to subscribe to when the modal is closed and access the response.
Pass data to the modal
Pass data as a String, Template or Component.
Overlay Ref Class
We are going to start by extending the OverlayRef
. We will create a custom OverlayRef
, creatively named MyOverlayRef
, which is going to accept the OverlayRef
, content
and the data to pass to our modal overlay. The content can be of type string
, TemplateRef
or Component
.
// R = Response Data Type, T = Data passed to Modal Type
export class MyOverlayRef<R = any, T = any> {
…
constructor(public overlay: OverlayRef, public content: string | TemplateRef<any> | Type<any>, public data: T ) {
…
}
…
}
Then, Inside the MyOverlayRef
class, we are going to add a BehaviorSubject
property named afterClosed$
which we can subscribe to get data once the overlay is closed.
afterClosed$ = new Subject<OverlayCloseEvent<R>>();
The behavior subject is going to pass back an OverlayCloseEvent
, which contains the data from modal and how the modal was closed. Feel free to modify this to cover your needs.
export interface OverlayCloseEvent<R> {
type: 'backdropClick' | 'close';
data: R;
}
Next, we need to add a private method to close the overlay. The method will dispose off the overlay, pass the OverlayCloseEvent
back to the subscriber and complete the afterClosed$
Observable.
private _close(type: 'backdropClick' | 'close', data: R) {
this.overlay.dispose();
this.afterClosed$.next({
type,
data
});
this.afterClosed$.complete();
}
And then, we are going to add a second public close method. It will only accept data
as a parameter and will call the private _close
method, to close the modal.
close(data?: R) {
this._close('close', data);
}
And finally, we are going to subscribe to backdropClick
and close the modal when clicked. We are adding this subscriber to the MyOverlayRef constructor.
overlay.backdropClick().subscribe(() => this._close('backdropClick', null));
Overlay Component
Next, we are going to add a special component that we will use to show our modal content. If it is a simple string, we will bind it to a div, while we can use either ngTemplateOutlet
and ngComponentOutlet
to load the template
and component
respectively.
Component Class
We are going to start by injecting an instance of our MyOverlayRef
into the component.
constructor(private ref: MyOverlayRef) {}
And then, let’s define 3 more properties inside our component class:
contentType: 'template' | 'string' | 'component' = 'component';
content: string | TemplateRef<any> | Type<any>;
context;
Then, OnInit
, we need to determine the content type and set the above properties appropriately.
ngOnInit() {
if (typeof this.content === 'string') {
this.contentType = 'string';
} else if (this.content instanceof TemplateRef) {
this.contentType = 'template';
this.context = {
close: this.ref.close.bind(this.ref)
};
} else {
this.contentType = 'component';
}
}
And finally, we are going to be adding a global close button, so let’s add a close
method:
close() {
this.ref.close(null);
}
And finally, remember to add the Overlay component as an entryComponent
in your app module.
Component Template
In the template, we are going to use ngSwitch
to switch between content type and add a global close button for our modal.
<div class="modal-content">
<ng-container [ngSwitch]="contentType">
<ng-container *ngSwitchCase="'string'">
<div class="box">
<div [innerHTML]="content"></div>
</div>
</ng-container>
<ng-container *ngSwitchCase="'template'">
…
</ng-container>
<ng-container *ngSwitchCase="'component'">
…
</ng-container>
</ng-container>
</div>
<!-- You can also add a global close button -->
<button (click)="close()" class="modal-close is-large" aria-label="close"></button>
For template content type, we will use ngTemplateOutlet
, passing the template, which is the content
and then pass the context
:
<ng-container *ngTemplateOutlet="content; context: context"></ng-container>
And while for component content type, we will use ngComponentOutlet
, passing the Component, which is the content:
<ng-container *ngComponentOutlet="content"></ng-container>
The Overlay Service
Next, we are going to create an Overlay service, which we can inject into any component we want to use our modal overlay. Where we are going to inject Overlay
Service and the Injector
.
export class OverlayService {
constructor(private overlay: Overlay, private injector: Injector) {}
}
Then, add an open
method, which will accept content and data. The data
param, in this case, is the data you would like to pass to your modal.
open<R = any, T = any>(
content: string | TemplateRef<any> | Type<any>,data: T): MyOverlayRef<R> {
…
}
Inside the method, first, we need to create an OverlayRef
object by using the Overlay
create
method. Feel free to customize the configs to suit your needs.
const configs = new OverlayConfig({
hasBackdrop: true,
backdropClass: 'modal-background'
});
const overlayRef = this.overlay.create(configs);
Then, let’s instantiate our MyOverlayRef
Class passing the OverlayRef
object we created above, then content and the data, both from the method parameters.
const myOverlayRef = new MyOverlayRef<R, T>(overlayRef, content, data);
Create an injector using PortalInjector
, so that we can inject our custom MyOverlayRef
object to the overlay component, we created above.
const injector = this.createInjector(myOverlayRef, this.injector);
And finally use ComponentPortal
, to attach the OverlayComponent
we created above and the newly created injector and return a MyOverlayRef
object.
overlayRef.attach(new ComponentPortal(OverlayComponent, null, injector));
return myOverlayRef;
And here is the method for creating a custom injector using PortalInjector
:
createInjector(ref: MyOverlayRef, inj: Injector) {
const injectorTokens = new WeakMap([[MyOverlayRef, ref]]);
return new PortalInjector(inj, injectorTokens);
}
And that’s it, we now have a re-usable modal overlay, that we can use anywhere inside our application.
Usage
First, inject the Overlay Service in the component where you would like to open a new modal overlay.
constructor(private overlayService: OverlayService) {}
Then, inside the method you would want to trigger the modal overlay, you just
use the open method and pass the content and any data you want to pass to the
modal overlay.
const ref = this.overlayService.open(content, null);
ref.afterClosed$.subscribe(res => {
console.log(res);
});
The content can be a simple string or a Template
or a Component
.
String
const ref = this.overlayService.open("Hello World", null);
Template
<ng-template #tpl let-close="close">
<div class="modal-card">
<section class="modal-card-body">
A yes no dialog, using template
</section>
<footer class="modal-card-foot">
<div class="buttons">
<button (click)="close('yes')" type="button" class="button is-success">Yes</button>
<button (click)="close('no')" type="button" class="button is-danger">No</button>
</div>
</footer>
</div>
</ng-template>
And a button to open the modal:
<button (click)="open(tpl)" class="button is-small is-primary">
Show
</button>
And then open the overlay with an open
method:
open(content: TemplateRef<any>) {
const ref = this.overlayService.open(content, null);
ref.afterClosed$.subscribe(res => {
console.log(res);
});
}
Component
open() {
const ref = this.overlayService.open(YesNoDialogComponent, null);
ref.afterClosed$.subscribe(res => {
console.log(res);
});
}
You can also inject the MyOverlayRef
inside the component to access data and the close method.
constructor(private ref: MyOverlayRef) {}
This allows you to pass data to the component and trigger the closing of the modal from within the component.
close(value: string) {
this.ref.close(value);
}
NB: Please remember to add the component as an entryComponent
inside your App Module.
You can find all of the above code here and the demo here.
Top comments (0)