Overlay

A module to create and manage overlays.

Demo

A demo can be found here: https://ngx-overlay-demo.stackblitz.io

Stackblitz demo: https://stackblitz.com/edit/ngx-overlay-demo

Installation

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

Versions

• 1.0.1 - Angular 15

Simply import the OverlayModule from "@maestroinfo/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, OverlayService } from '@maestroinfo/ngx-overlay';
import { OverlayComponent } from './components/overlay.component';

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

Overlay styles

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

@import '~@maestroinfo/ngx-overlay/styles/base.scss';

This is only needed if you don't 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.

import { MstrOverlayRef, OverlayService } from '@maestroinfo/ngx-overlay';
...
constructor(private overlayService: OverlayService) {}
...
public openOverlay(): void {
  this.overlay.open(OverlayComponent);
}

Configuring an overlay

When creating an overlay, an optional configuration object can be provided.

  this.overlay.open(OverlayComponent, {
    panelClass: 'overlay',
    hasBackdrop: false,
    fullHeight: false,
    positionVertical: {
      placement: 'center'
    },
    positionHorizontal: {
      placement: 'center'
    },
  });

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(OverlayComponent, { data: { menuItems: [] } });

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

export class OverlayComponent implements OnInit {
    constructor(
        public overlayRef: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

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

Closing an overlay

By default, the overlay will close automatically 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: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

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

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

<button mst-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: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

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

Or with the mst-dialog-close directive

<button [mst-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 MstrOverlayLeave {
  animationState: 'void' | 'enter' | 'leave' = 'enter';
  animationStateChanged = new EventEmitter<AnimationEvent>();
  ...
}

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

export class SidebarComponent implements MstrOverlayLeave {
  ...
  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 MstrOverlayConfig<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: {})
}