Most sites contains images that are viewed in different display sizes (desktops/laptops, mobile phones, tablets, of which comes in different sizes, etc.). To ensure the same experience on your site through various display sizes, the images would need to be converted to different sizes and formats. Crafter CMS supports automatic image processing that allows you to upload just one image that gets converted to the different sizes or formats required by your site for various display sizes. This automatic image processing is one form of asset processing and can be configured in Studio through the Asset Processing configuration file.
Asset processing allows you to define transformations for static assets (currently only images), through a series of processor pipelines that are executed when the assets are uploaded to Studio. A processor is an application that can manipulate your assets to your desired formats such as compress and optimize JPEG and PNG images, etc. Each processor pipeline in the configuration let’s you manipulate the asset to a desired format/size. You can specify just one or as many processors as needed. You can also specify just one or as many pipelines as required by your site. (Say, you want an image appropriate for mobile devices and an image appropriate for desktop browsers, you’ll have two pipelines setup in the configuration.)
Configuring Asset Processing¶
The pipelines can be configured by
going to the Sidebar in Studio, then from the Sidebar, go to
Site Config > Configurations > Asset Processing. Each pipeline has the following structure:
<pipeline> <inputPathPattern/> <keepOriginal/> <processors> <processor> <type/> <params/> <outputPathFormat/> </processor> </processors> </pipeline>
inputPathPattern:regex that the assets need to match in order to be processed by the pipeline. Groups that are captured by this regex are available later to the
keepOriginal (optional):if the original asset (without changes) should be saved.
type:the type of the processor. Right now 2 types are supported:
outputPathFormat (optional): the format of the output path. Variables that have a dollar sign ($) and an index are later replaced by groups that resulted during input path matching, to form the final output path. If not specified, then the same input path is used as the output path.
Please note the following:
We currently support 2 types of image processors, ImageMagickTransformer and TinifyTransformer
You can have one or multiple pipelines setup, but, a pipeline must have at least one processor configured.
Asset Processing Example¶
The following example specifies 2 different asset processing pipelines: the first one converts any image put
/static-assets/images/upload/ into another one that’s compressed and suitable to be displayed in a desktop
browser, while the second one converts the same image for display on mobile devices:
<assetProcessing> <pipelines> <!-- Web transformer pipeline --> <pipeline> <inputPathPattern>^/static-assets/images/upload/(.+)\.jpg$</inputPathPattern> <keepOriginal>false</keepOriginal> <processors> <processor> <type>ImageMagickTransformer</type> <params> <options>-level 0,100%,1.3 -gaussian-blur 0.05 -quality 20% -strip</options> </params> <outputPathFormat>/static-assets/images/compressed/web/$1-compressed.jpg</outputPathFormat> </processor> </processors> </pipeline> <!-- Mobile transformer pipeline --> <pipeline> <inputPathPattern>^/static-assets/images/upload/(.+)\.jpg$</inputPathPattern> <keepOriginal>false</keepOriginal> <processors> <processor> <type>ImageMagickTransformer</type> <params> <options>-level 0,100%,1.3 -gaussian-blur 0.05 -quality 20% -strip -resize 226x164</options> </params> <outputPathFormat>/static-assets/images/compressed/mobile/$1-compressed.png</outputPathFormat> </processor> <processor> <type>TinifyTransformer</type> </processor> </processors> </pipeline> </pipelines> </assetProcessing>
Using the above example, if an image called
logo.jpg would be put under
Studio would generate 2 files: the web version, under
and the mobile version, under
/static-assets/images/compressed/mobile/logo-compressed.png. The original file
would be discarded.
You need to have image ImageMagick installed in the machine, with the
convertcommand in the path. For more information on ImageMagick options, please see https://imagemagick.org/script/command-line-options.php
The Tinify API key must be specified in the
studio-config-overrides.yamlfile (found in your Authoring installation, under
shared/classes/crafter/studio/extension). Add the line below and remember to replace
<your Tinify API key>with the actual value of your Tinify API key:
studio.configuration.asset.processing.tinify.apiKey:<your Tinify API key>. For more information on Tinify, please see https://tinypng.com/developers/reference/java