Home

Awesome

ngx-advanced-img

Angular attribute directives suite that provides various HTML img feature extensions.

Table of contents

About This Package

This package was built to provide easy to use feature directives that are meant to be used with HTML img tags. The first features being created are fallback image loading and progressive image loading and caching. Additionally, it provides helper classes that allow image data to be cached in application memory for quick HTML5 Canvas usage and the library also provides an easy to use interface for encoding images with new mime types and optimize them to meet certain conditions or file sizes.

Installation

npm install ngx-advanced-img --save

Usage

  1. Import NgxAdvancedImgModule in your app module (or other Angular module) and place it in your imports section:

    import { NgxAdvancedImgModule } from "ngx-advanced-img";
    
    @NgModule({
       imports: [
         ...,
         NgxAdvancedImgModule,
       ],
       ...
    })
    export class AppModule { }
    
  2. Import ngx-advanced-img.scss to your application's styles or add it to your angular.json if you use the CLI tools.

Directives

ngxAdvancedImgFallback

This directive extends HTML img nodes to provide some special fallback loading functionality. If the initial load of the image src value fails, this directive will automatically swap to the provided fallback URL or data URI. Alternatively, you may provide a special value of cache-bust and it will handle reloading prevoiusly failed src but with a unique cache busting query parameter attached to the URL (assuming it is a valid URL).

ngxAdvancedImgFallback {'cache-bust' | string}

ngxAdvancedImgFallbackActive {read-only boolean}

Classes

These classes require no import of the module, but you can import the classes directly into your source code.

NgxAdvancedImgBitmap

This class is used to load image data into application memory using HTML5 canvas technology. This allows a user of this class to efficiently load and draw images to screen. It additionally provides extra support for dealing with SVGs in HTML5 and also provides the ability to optimize a given image file to reduce its file size in browser.

Creating Bitmap

const bitmap: NgxAdvancedImgBitmap = new NgxAdvancedImgBitmap(
  src,
  resolution,
  revision,
  ttl,
);

Optimizing Bitmaps

You can optimize an already loaded image bitmap by using the optimize function.

bitmap.load().finally(() => {
  console.log('bitmap loaded with size (B):', bitmap.fileSize);

  bitmap.optimize(
    bitmap.mimeType,
    +this.quality,
    +this.scale / 100,
    +this.maxDimension,
    {
      sizeLimit: +this.size,
      mode: this.mode,
      strict: !!this.strictMode,
    },
    options?: INgxAdvancedImgOptimizationOptions,
  ).then((data: INgxAdvancedImgBitmapOptimization) => {
    // ... save the file? use that resultant data in other canvases?
  }).catch(() => {
    // ... if things fail
  });
});

Important Note

The resultant bitmap data will have all exif meta data stripped from it since the optimization procedure uses HTML5 canvas operations to manipulate the data. All exif meta data is included in the response object of the function call so that you may work with it as necessary if you are in a controlled server environment where you have reliable and efficient means for writing exif data back to images. In the browser environment, this isn't really the case without limiting our output mime types. Therefore, such considerations should be those of the wielder of this library.