@creative-web-solution/express-layer-picture-helper v0.0.2

Picture Helper for ExpressLayer

• Dependencies
• Install
• Configuration
• Complete configuration example
• Twig extension
• Debug

This module use Sharp.

This plugin only works with ExpressLayer.

Dependencies

• sharp

Install

Install package:

npm install @creative-web-solution/express-layer-picture-helper

Then, in the expressLayerConfiguration.ts of your project:

import PictureHelperFactory from "@creative-web-solution/express-layer-picture-helper";

export const expressLayerConfiguration: ExpressLayerOptions = {
    ...,
    "addPlugins": async (expressLayer: ExpressLayer) => {
      return [new PictureHelperFactory(expressLayer)]
    }
};

Configuration

The file config/packages/pictureHelper.json is created when the package is installed.

Set the destination folder in (Mandatory):

It will be relative to the public folder.

{
  "exportFolder": "path/to/destination/folder",
  ...
}

Set default export param:

{
    "defaultExportParams": {
        "png": {
            "compressionLevel": 5, // 0 -> 9
            "progressive": false
        },
        "jpeg": {
            "quality": 70, // 0 -> 100
            "progressive": false
        },
        "webp": {
            "quality": 70, // 0 -> 100
            "alphaQuality": 100, // 0 -> 100
            "lossless": false
        }
    },
    ...
}

Set actions (Mandatory):

In the actions array you can add all the function of Sharp in the order you want.

{
    "filters": {
        "myWonderfullFilter": {
            "actions": [
                {
                    "name": "SharpFunctionName",
                    "params": {
                        "param1": "value1",
                        "param2": "value2",
                        ...
                    }
                },
                {
                    "name": "SharpFunctionName2",
                    "params": [ "param1", "param2", ... ]
                },
                ...
            ]
        },
        ...
    }
}

Scale

A scale function was added in addition of all Sharp action. It can take 2 parameters:

• x: size factor of the width
• y: size factor of the height

{
  "filters": {
    "halfSize": {
      "actions": [
        {
          "name": "scale",
          "params": {
            "x": 0.5
          }
        }
      ]
    }
  }
}

Allow insecure connection to remote server when loading images:

If you have certificate issue with the remote server, set this to true. It's not recommended. Default false.

{
  "allowInsecureRemote": true,
  ...
}

Image that will be used to display if an error occured when processing a picture

Those path are relative to the project root.

{
  "errorImageReplacement": {
    "jpg": "path-to-replacement/image.jpg",
    "webp": "path-to-replacement/image.webp",
    "png": "path-to-replacement/image.png",
    "avif": "path-to-replacement/image.avif",
  }
  ...
}

avif and webp can be optional if you're not using them in your project

Complete example

{
  "allowInsecureRemote": false,
  "exportFolder": "/media/cache",
  // Set the default for all export format
  "defaultExportParams": {
    "png": {
      "compressionLevel": 5, // 0 -> 9
      "progressive": false
    },
    "jpeg": {
      "quality": 70, // 0 -> 100
      "progressive": false
    },
    "webp": {
      "quality": 70, // 0 -> 100
      "alphaQuality": 100, // 0 -> 100
      "lossless": false
    }
  },
  "filters": {
    "sample": {
      "actions": [
        // Resize a picture
        {
          "name": "resize",
          "params": {
            "width": 320,
            "height": 320,
            "fit": "cover", // cover, contain, fill, inside or outside
            "position": "centre", // centre, top, right top, right, right bottom, bottom, left bottom, left, left top
            "background": { "r": 0, "g": 0, "b": 0, "alpha": 1 }
          }
        },
        // Set quality for this filter only
        {
          "name": "jpeg",
          "params": {
            "quality": 90
          }
        }
      ]
    }
  },
  "errorImageReplacement": {
    "jpg": "path-to-replacement/image.jpg",
    "webp": "path-to-replacement/image.webp",
    "png": "path-to-replacement/image.png"
  }
}

Twig extension

Use the getSrcset twig extension to create a srcset for <picture> and <img srcset="..." >:

<picture>
    <source srcset="{{ getSrcset( asset('assets/images/img-1.jpg'), { "320w": "widen_320", "640w": "widen_640", "1024w": "widen_1024" }) }}" media="(max-width: 1023px)" sizes="100vw">
    <source srcset="{{ getSrcset( asset('assets/images/img-2.jpg'), { "1024w": "widen_1024", "1280w": "widen_1280", "1440w": "widen_1440" }) }}" media="(min-width: 1024px)" sizes="100vw" >
    <img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" alt="">
</picture>

You can use it with remote images:

<picture>
    <source srcset="{{ getSrcset( 'https://www.distant-domain.com/images/image-small.jpg', { "320w": "widen_320", "640w": "widen_640", "1024w": "widen_1024" }) }}" media="(max-width: 1023px)" sizes="100vw">
    <source srcset="{{ getSrcset( 'https://www.distant-domain.com/images/image-big.jpg', { "1024w": "widen_1024", "1280w": "widen_1280", "1440w": "widen_1440" }) }}" media="(min-width: 1024px)" sizes="100vw" >
    <img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" alt="">
</picture>

It will download the image and save it in var/cache/picture-helper-cache.

Use the getSrc twig extension to create an url from a source and one filter:

<img src="{{ getSrc( asset('assets/images/img-1.jpg'), "widen_320" ) }}" alt="">

Debug

You can add a pictureHelperDebug key in the parameter.json to activate debug:

{
  "pictureHelperDebug": true
}