shel / neos-sqip
Neos CMS SQIP image renderer
Installs: 340
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 5
Forks: 1
Open Issues: 2
Type:neos-plugin
Requires
- neos/neos: ~4.3 || ~5.0 || ~7.0 || ~8.0
This package is auto-updated.
Last update: 2024-10-12 18:30:14 UTC
README
Description
This package provides a fusion object for Neos CMS to render svg image placeholders based on the SQIP technique. They can be used to show a blurry or abstract version of an image while the real image is still lazy loading.
You can see it in action here.
Learn more about SQIP is a method to generate SVG based placeholders for images here:
- Original node.js version sqip used by this package.
- The go variant which is also supported via configuration.
Attention: the node.js based sqip
is not released in version 1 yet.
Therefore breaking changes might happen when you use the global binary and you might need to adjust
the arguments in the settings or wait for an update of this package.
Installation
Requires npm (node.js) to work out of the box, although binaries can also be installed manually without it.
composer require shel/neos-sqip
Ensure the image manipulation library sqip
is installed globally.
Alternatively install them using npm
:
Globally
npm install -g sqip
Locally
npm install --prefix Packages/Plugins/Shel.Neos.Sqip/Resources/Private/Library
How to use
Use the provided fusion object Shel.Neos.Sqip:ImageTag
to render an image with placeholder and use
the lazy image loader layzr to lazy load the actual images.
This object already provides the necessary attributes to make layzr
work out of the box.
You can also use the provided Shel.Neos.Sqip:SqipImage
fusion object to just render the SVG data which you can
put into the src
attribute of an img
tag or in a inline style as background image.
The fusion object Shel.Neos.Sqip:SqipCaseRenderer
provides a renderer for your src
attribute which checks
if the user is in the backend and then decides to render the original image uri instead of the SQIP image.
You can use this for example to modify the Carbon.Image:Tag object like this:
prototype(Carbon.Image:Tag) {
attributes {
src >
src = Shel.Neos.Sqip:SqipCaseRenderer {
asset = ${asset}
}
srcset >
data-normal = Carbon.Image:ImageUri
data-srcset = Carbon.Image:Srcset
}
}
Compatible image formats
This package was tested with pngs, jpegs and svgs. Possibly other formats work well too.
Performance
Processing the SQIP placeholders is quite slow and takes several seconds per image.
To speed this up a thumbnail will be generated first (which can also be prerendered with CLI commands) to reduce the image dimensions. By default the preset from the Media Browser will be used which has dimensions of 250x250. So this is also a bit faster as the media module reuses the same thumbnails.
You can change the preset via configuration.
Configuration
Default options
Shel:
Neos:
Sqip:
useGlobalBinary: false # use globally installed binaries
globalBinaryPath: ''
library: 'sqip'
binaryPath: '.bin/sqip'
arguments: "${'node ' + binaryPath + ' -n ' + numberOfPrimitives + ' -m ' + mode + ' -b ' + blur + ' ' + file}"
parameters:
# Customize the number of primitive SVG shapes (default=8) to influence bytesize or level of detail
numberOfPrimitives: 8
# Specify the type of primitive shapes that will be used to generate the image
# 0=combo, 1=triangle, 2=rect, 3=ellipse, 4=circle, 5=rotatedrect, 6=beziers, 7=rotatedellipse, 8=polygon
mode: 0
# Set the gaussian blur
blur: 12
thumbnailPreset: 'Neos.Media.Browser:Thumbnail'
Using the go variant
The go version is faster than the node.js version and has less dependencies but currently doesn't provide the blur parameter. Both binaries have the same cli output and therefore work fine.
-
Install the
sqip
binary like described in their instructions. -
Override the package settings in your own package like this:
Shel: Neos: Sqip: useGlobalBinary: true globalBinaryPath: '/path/to/your/go/bin/' # Adapt this to your system arguments: "${binaryPath + ' -n ' + numberOfPrimitives + ' -mode ' + mode + ' ' + file}" parameters: # Customize the number of primitive SVG shapes (default=8) to influence bytesize or level of detail numberOfPrimitives: 8 # Specify the type of primitive shapes that will be used to generate the image # 0=combo, 1=triangle, 2=rect, 3=ellipse, 4=circle, 5=rotatedrect, 6=beziers, 7=rotatedellipse, 8=polygon mode: 0
Caching
The generated SVGs will be cached in the filesystem as strings.
To speed the Cache up you can switch to use Redis like this in your Caches.yaml
:
ShelNeosSqip_ImageCache:
backend: Neos\Cache\Backend\RedisBackend
backendOptions:
database: 0
You can make the cache persistent to keep cached images when temporary caches are flushed:
ShelNeosSqip_ImageCache:
persistent: true