@impactdk/ngx-overlay

Overlay

A module to create and manage overlays.

Installation

npm install --save @impactdk/ngx-overlay @angular/cdk

Versions

• Angular 8+ - Use ^3.0.0
• Angular versions lower than 8 - Use ^2.0.0

Simply import the OverlayModule from "@impactdk/ngx-overlay" in your AppModule. Any component that needs to be injected into the overlay needs to be placed into the entryComponents of a given module.

import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { BrowserModule } from '@angular/platform-browser';

import { OverlayModule } from '@impact/overlay';
import { SidebarComponent } from './sidebar/sidebar.component';

@NgModule({
    imports: [BrowserModule, OverlayModule],
    declarations: [AppComponent, SidebarComponent],
    bootstrap: [AppComponent],
    providers: [],
    entryComponents: [SidebarComponent],
})
export class AppModule {}

Overlay styles

In order for the overlay to have the proper styles you must import @impactdk/overlay/base into your main style file.

@import '~@impactdk/ngx-overlay/base';

This is only needed if you dont use material theme already as it is included in the core.

Opening an overlay

To open an overlay simply inject the overlay service into your component and trigger the open method on the class and pass in the component you want to inject.

this.overlay.open(SidebarComponent);

Passing data to the injected component

In order to send data to the component that was opened simply pass in the config object with the parameter "data" with what ever data you want to share.

this.overlay.open(SidebarComponent, { data: { menuItems: [] } });

You can then use this data within the injected component by using the IMPACT_OVERLAY_DATA injection token

export class SidebarComponent implements OnInit {
    constructor(
        public overlayRef: ImpactOverlayRef,
        @Inject(IMPACT_OVERLAY_DATA) public data: any
    ) {}

    ngOnInit() {
        console.log(this.data);
    }
}

Closing an overlay

By default the overlay will close automaticly when the backdrop is pressed. If you want to manually close the overlay simply invoke the close method on the overlayRef

export class SidebarComponent implements OnInit {
    constructor(
        public overlayRef: ImpactOverlayRef,
        @Inject(IMPACT_OVERLAY_DATA) public data: any
    ) {}

    closeSidebar() {
        this.overlayRef.close();
    }
}

Alternatively you can use the directive imp-dialog-close on a button to close a dialog

<button imp-dialog-close>Close</button>

Emitting a result outside the dialog

Is is possible to emit a result outside the overlay, i.e. when using the overlay as a confirm dialog.

export class SidebarComponent implements OnInit {
    constructor(
        public overlayRef: ImpactOverlayRef,
        @Inject(IMPACT_OVERLAY_DATA) public data: any
    ) {}

    closeSidebar() {
        this.overlayRef.close(true);
    }
}

Or with the imp-dialog-close directive

<button [imp-dialog-close]="true">Accept</button>

The result can be acted upon by subscribing to the beforeClose or afterClose events:

const overlayRef = this.overlay.open(SidebarComponent);

overlayRef
    .afterClose()
    .subscribe(response =>
        console.log('Received result from overlay', response)
    );

Animating in and out

In order to animate in, simply use the Angular Animations library to create a :enter animation.

Animating out

Animating out however is not as easy as a cause of the limitations within the CDK.

First you must add the following properties to your component.

export class SidebarComponent implements ImpactOverlayLeave {
  animationState: 'void' | 'enter' | 'leave' = 'enter';
  animationStateChanged = new EventEmitter<AnimationEvent>();
  ...
}

After that you must implement the following methods in your component.

export class SidebarComponent implements ImpactOverlayLeave {
  ...
  onAnimationStart(event: AnimationEvent) {
    this.animationStateChanged.emit(event);
  }

  onAnimationDone(event: AnimationEvent) {
    this.animationStateChanged.emit(event);
  }

  startExitAnimation() {
    this.animationState = 'leave';
  }
  ...
}

And finally you must implement the animation triggers for start and done on the element you trigger your animations on like this.

<section [@slideContent]="animationState"
         (@slideContent.start)="onAnimationStart($event)"
         (@slideContent.done)="onAnimationDone($event)">
</section>

Settings

At this time the service supports several config settings.

export interface ImpactOverlayConfig<T = any> {
    panelClass?: string | string[]; // Class around the panel wrapping the injected components (default: '')
    fullHeight?: boolean; // Decides if a panel should be full height or dependent on the component size (default: false)
    hasBackdrop?: boolean; // True/False if you want a backdrop or not (default: true)
    blockScroll?: boolean; // True/False if you want the backdrop to block scroll (default: true)
    backdropClass?: string; // Add a class to the backdrop (default: ''cdk-overlay-dark-backdrop)
    positionVertical?: {
        placement: 'bottom' | 'top' | 'center'; // Decides the vertical position of the component within the backdrop (default: 'center')
        offset?: string; // Offset can be in any given css unit. (default: '0px')
    };
    positionHorizontal?: {
        placement: 'left' | 'right' | 'center'; // Decides the horizontal position of the component within the backdrop (default: 'center')
        offset?: string; // Offset can be in any given css unit. (default: '0px')
    };
    positionStrategy?: PositionStrategy; // Provide either a CDK or a custom PositionStrategy (https://material.angular.io/cdk/overlay/api#PositionStrategy)
    scrollStrategy?: ScrollStrategy; // Provide either a CDK or a custom ScrollStrategy (https://material.angular.io/cdk/overlay/api#ScrollStrategy)
    data?: T; // Any data that should be injected into the component (default: {})
}