@creative-web-solution/picture-filter v1.1.3

Picture filter

This module use Sharp.

This generic bundle only works with the website socle.

• Install
• Route
• Configuration
• Fake pictures
• Example
• Twig extension

Install

On installation (npm i), this bundle will copy some files if they do not already exist:

• config/packages/pictureFilter.json
• config/routes/1-pictureFilter.js
• resources/fake-picture-filter-images/no-image.jpg
• resources/fake-picture-filter-images/no-image.png
• resources/fake-picture-filter-images/no-image.webp

Route

The file config/routes/1-pictureFilter.js is created when the package is installed.

You can change the number at the start of the filename to manage the order of the routes creation.

Configuration

Configuration in parameters.json.

Those 2 parameters are not mandatory, they are false by default.

{
    ...
    "picture_filter_allow_insecure_remote": true,
    "picture_filter_fake_in_dev": true,
    ...
}

See below for their purpose.

Configuration in config/packages/pictureFilter.json.

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

Set the destination folder in (Mandatory):

It will be relative to the public folder.

{
    "pictureFilter": {
        "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
                    }
                }
            ]
        }
    }
}

If you have certificate issue with the remote server, you can add picture_filter_allow_insecure_remote: true in the parameters.json. It's not recommended.

Fake pictures

The files resources/fake-picture-filter-images/no-image.* are created when the package is installed.

In production mode, some fake pictures are sent in case where the wanted picture can't be exported.

You can customize these pictures by changing the three in resources/fake-picture-filter-images. DO NOT change their name. Their size should be at least 1920px x 1080px.

You can force the display of these pictures in development mode by adding picture_filter_fake_in_dev: true in parameters.json

Example

{
    "exportFolder": "",
    // 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,
                    }
                }
            ]
        }
    }
}

Twig extension

Use the getSrcset twig extension (core/Twig/Extension/PictureFunction.js) 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-filter-cache.

Use the getSrc twig extension (core/Twig/Extension/PictureFunction.js) to create an url from a source and one filter:

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