Mat-Image-Overlay

An Angular Material based standalone component that shows images in an overlay. The component is based on Rafasantos angular-material-image-overlay.

Demo

Try out the demo page.

Quick Start

Install the package:

npm install mat-image-overlay

Configure your angular application module (e.g: app.module.ts):

...
import { MatImageOverlayModule } from 'mat-image-overlay';

@NgModule({
  ...
  imports: [
    ...
    MatImageOverlayModule
  ]
})
export class AppModule { }

Define a class based on MatImageDetailsProvider to get information about the images and create an instance of it in the mat-image-overlay configuration. Examples for classes based on MatImageDetailsProvider can be found in the 'examples/provider' directory of the mat-image-overlay component.

images = [
    'https://url/of/first/image.jpg',
    'https://url/of/second/image.jpg',
    'https://url/of/third/image.jpg',
    'https://url/of/fourth/image.jpg'
];

constructor(private imageOverlay: MatImageOverlay) {
}

openImageOverlay(imageIndex?: number): void {
  const config = {
    imageDetails: new StringSourceImageDetailsProvider(this.images),
    startImageIndex: imageIndex,
    backdropClass: 'demo-backdrop-class'
  } as MatImageOverlayConfig;
  const imageOverlayRef = this.imageOverlay.open(config);
}

Open the overlay via a clickable element in your html template (e.g. app.component.html)

  <p>
    Click <a href="#" (click)="openImageOverlay()">here to open the overlay</a>
  </p>

Navigation

When the overlay is shown, the keyboard can be used to navigate between the images (even when no navigational buttons are displayed on the image). The following keys are available:

| key | function | |-----|----------| | Arrow Right | show next image | | Arrow Down | show next image | | Arrow Left | show previous image | | Arrow Up | show previous image | | Home | show first image | | End | show last image | | Escape | close overlay |

Used assets

The component is based on Angular Material and uses Google Fonts and Google Material Icons. Both fonts are part of the project and not fetched via https.

Some special icons are stored in the code as strings representing the icons as svg graphics.

Mat-Image-Overlay Demo

Demo project to show how mat-image-overlay works.

git clone [email protected]:BePo65/mat-image-overlay.git
cd mat-image-overlay
npm start

Navigate to http://localhost:4200

API reference for Mat-Image-Overlay

Services

MatImageOverlay

Service to open Mat-Image-Overlay as a modal overlay.

Properties | Name | Description | |---|---| | imageOverlayRef: MatImageOverlayRef | undefined | Reference of the opened image overlay. | | afterOpened: Subject<MatImageOverlayRef> | Stream that gets notified when the image overlay has been opened. | | afterClosed: Subject<number> | Stream that gets notified when the image overlay has been closed. |

Methods | open | | |---|--| | Opens the image overlay. | | | Parameters | | | configMatImageOverlayConfig | Extra configuration options. | | Returns | | | MatImageOverlayRef | Reference to opened image overlay.

| imageOverlayExists | | |---|--| | Checks whether the image overlay already exists. | | | Returns | | | boolean | true = image overlay exists |

Interfaces

MatImageOverlayConfig

Configuration for opening a modal image overlay with the MatImageOverlay service.

Properties | Name | Description | |---|---| | imageDetails | Instance of a class derived from MatImageDetailsProvider. | | startImageIndex | Index of the first image to be displayed (0 based). | | backdropClass | CSS class to add to the backdrop, replacing the default backdrop css. This CSS class must be in the global styles of the application.Default style is 'background: rgba(0 0 0 / 32%);'Optional parameter. | | margin | Minimal margin in px around the loaded image.Default value: 32Optional parameter. | | overlayButtonsStyle | Style of the buttons in the image overlay (using enum ElementDisplayStyle: never, onHover, always).Default value: ElementDisplayStyle.onHover.Optional parameter. | | descriptionDisplayStyle | Style of the image description in the image overlay (using enum ElementDisplayStyle: never, onHover, always). Using this option requires a property named 'description' in the data source.Default value: ElementDisplayStyle.never.Optional parameter. | | descriptionDisplayPosition | Position of the image description in the image overlay (using enum ElementDisplayPosition: bottomLeft, bottomCenter, bottomRight, topLeft, topCenter, topRight). Using this option requires a property named 'description' in the data source.Default value: ElementDisplayPosition.bottomRight.Optional parameter. | | imageClickedAdditionalData | Object with arbitrary data that will be returned by the imageClicked event (added to the data returned by the 'imageDetails.imageInformation' method).Optional parameter. |

MatImageDetailsProvider

Abstract base class to be derived by a real image details provider. This class is used to get all the required information about an image.

Properties | Name | Description | |---|---| | numberOfImages | Number of images that can be displayed (this property is readonly). |

Methods | urlForImage | | |---|--| | Gets the url for an image. | | | Parameters | | | imageIndex | Index of the image to be displayed (0 based). | | Returns | | | string | Url for the image to be displayed. |

| descriptionForImage | | |---|--| | Gets the description for an image. | | | Parameters | | | imageIndex | Index of the image to be displayed (0 based). | | Returns | | | string | Url for the image to be displayed. |

| imageInformation | | |---|--| | Gets a record that contains information about an image. | The returned object is part of the data returned by the imageClicked event. | | Parameters | | | imageIndex | Index of the clicked image (0 based). | | Returns | | | Record<string, unknown> | Object with additional data about the image. |

ThumbnailProvider

Interface to add the handling of thumbnail images to a class derived from MatImageDetailsProvider.

Properties | Name | Description | |---|---| | thumbnailHeight | Height of the thumbnail images in px. |

Methods | urlForThumbnail | | |---|--| | Gets the url for a thumbnail image. | | | Parameters | | | imageIndex | Index of the thumbnail image to be displayed (0 based). | | Returns | | | string | Url for the thumbnail image to be displayed. |

Classes

MatImageOverlayRef

Reference to an image overlay opened via the MatImageOverlay service.

Properties | Name | Description | |---|---| | numberOfImages | number of images that can be displayed. | | keydownEvents$ | Observable that is notified by keydown events on the overlay. Navigation buttons don't get emitted. |

Methods | afterOpened | | |---|--| | Gets an observable that is notified when the image overlay is finished opening. | | | Returns | | | Observable<void> | Observable that fires, when the overlay has been opened. |

| afterClosed | | |---|--| | Gets an observable that is notified when the image overlay is finished closing. | | | Returns | | | Observable<number> | Observable that returns the index of the last image displayed. |

| imageChanged | | |---|--| | Gets an observable that is notified when a new image has been selected. | | | Returns | | | Observable<number> | Observable that returns the index of the image displayed. |

| imageClicked | | |---|--| | Gets an observable that is notified when an image has been clicked. | | | Returns | | | Observable<ImageClickedEvent> | Observable that returns the object with data of the clicked image and the imageClickedConfiguration object from the config object. |

| gotoNextImage | | |---|--| | Display the next image in the datasource. | |

| gotoPreviousImage | | |---|--| | Display the previous image in the datasource. | |

| gotoFirstImage | | |---|--| | Display the first image in the datasource. | |

| gotoLastImage | | |---|--| | Display the last image in the datasource. | |

| gotoImage | | |---|--| | Display the image in the datasource selected by the imageIndex. | | | Parameters | | | imageIndex | Index of the image to be displayed. |

| close | | |---|--| | Close the image overlay. | |

API reference for Mat-Image-Overlay testing

import { MatImageOverlayHarness } from 'mat-image-overlay/testing';

Classes

MatImageOverlayHarness extends ContentContainerComponentHarness

Harness for interacting with a standard MatImageOverlay in tests.

Properties | Name | Description | |---|---| | static hostSelector: '.mat-image-overlay-container' | The selector for the host element of a MatImageOverlay instance. |

Methods | async overlayIsLoaded | | |---|--| | Gets a promise that fulfills to true, when the image overlay is visible. | | | Returns | | | Promise<boolean> | Promise that fulfills to a flag that shows, if the image overlay is visible.

| async close | | |---|--| | Closes the image overlay by pressing escape. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async clickBackdrop | | |---|--| | Closes the image overlay by clicking the backdrop of the image overlay. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async buttonCloseVisible | | |---|--| | Gets a promise that fulfills to true, when the 'close' button is visible. | | | Returns | | | Promise<boolean> | Promise that fulfills to a flag that shows, if the 'close' button is visible.

| async buttonPreviousVisible | | |---|--| | Gets a promise that fulfills to true, when the 'previous' button is visible. | | | Returns | | | Promise<boolean> | Promise that fulfills to a flag that shows, if the 'previous' button is visible.

| async buttonNextVisible | | |---|--| | Gets a promise that fulfills to true, when the 'next' button is visible. | | | Returns | | | Promise<boolean> | Promise that fulfills to a flag that shows, if the 'next' button is visible.

| async descriptionVisible | | |---|--| | Gets a promise that fulfills to true, when the 'description' of the image is visible. | | | Returns | | | Promise<boolean> | Promise that fulfills to a flag that shows, if the 'description' is visible.

| async clickCloseButton | | |---|--| | Clicks the 'close overlay' button of the image overlay. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async clickPreviousButton | | |---|--| | Clicks the 'goto previous image' button of the image overlay. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async clickNextButton | | |---|--| | Clicks the 'goto next image' button of the image overlay. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async figureHover | | |---|--| | Sets the figure tag of the overlay (the content of the overlay) into the hover state. | | | Returns | | | Promise<void> | Promise that fulfills, when the action completes.

| async imageUrl | | |---|--| | Gets a promise that fulfills to the url of the current image in the overlay. | | | Returns | | | Promise<boolean> | Promise that fulfills to the url of the image or to an empty string.

| async sendKeys | | |---|--| | Send keys to the overlay. | | | Parameters | | | ...keys | Array of 'TestKey' to be sent. Possible values are the arrow keys, the home and the end key. | | Returns | | | Promise<void> | Promise that resolves when the action completes.

| async hasBackdropClass | | |---|--| | Gets a promise that fulfills to true, when the backdrop contains the given css class. | | | Parameters | | | classname | Name of the css class to be evaluated. | | Returns | | | Promise<boolean> | Promise fulfills to a flag that shows, if the backdrop contains the given css class.

License

Copyright © 2024 Bernhard Pottler.

Distributed under the MIT License. See LICENSE for more information.

This project uses the fonts 'Roboto' and 'Material Icons' from the Google Fonts Library that are licensed under the Apache License Version 2.0.