Imager X 5.0

# Usage

If you've ever done an image transform in a Craft template, this probably looks familiar:

{% set image = craft.assets().one() %}
<img src="{{ image.getUrl({ width: 1000 }) }}">

The same code using Imager would look like this:

{% set image = craft.assets().one() %}
{% set transformedImage = craft.imagerx.transformImage(image, { width: 1000 }) %}
<img src="{{ transformedImage.url }}">

So far, it's more code than the Craft way. But, let's say you need to resize the image to six different widths, because you're using srcset to serve up responsive images. You want the aspect ratio to be 16:9, and we want to force jpg format with a quality of 60.

Here's how the code would look with Imager:

{% set transformedImages = craft.imagerx.transformImage(image, [
    { width: 400 }
    { width: 600 }, 
    { width: 800 }, 
    { width: 1000 }, 
    { width: 1200 }, 
    ], { ratio: 16/9, format: 'jpg', jpegQuality: 60 }) %}

TIP

Notice that if you pass in a single transform object as the second parameter to transformImage, a single transformed image will be returned. If you pass an array of transform objects, an array of transformed images will be returned.

Even better, there's a convenient fillTransforms config setting which makes the above code even simpler:

{% set transformedImages = craft.imagerx.transformImage(image, [
    { width: 400 },
    { width: 1200 } 
    ], { ratio: 16/9, format: 'jpg', jpegQuality: 60 }, 
    { fillTransforms: true, fillInterval: 200 }) %}

See the fillTransforms, fillAttribute and fillInterval settings for more information.

# Quick syntax

The example above shows Imager's full syntax, which will unlock all of Imager's functionality. But as of 4.3.0, there is also a quick syntax that makes things even easier if all you need is a range of transforms based on width, and optionally an aspect ratio or format.

{% set transformedImages = craft.imagerx.transformImage(image, [400, 1200, 16/9, 'jpg']) %}

The quick syntax will automatically set fillTransforms to auto, and use autoFillCount to determine how many transforms to make (go crazy and set it to auto too). The third parameter of the quick syntax can also be an object with default transform parameters, like this:

{% set transformedImages = craft.imagerx.transformImage(image, [400, 1200, { ratio: 16/9, format: 'jpg', jpegQuality: 60 }]) %}

TIP

The quick syntax is also available in your auto generate config alongside named transforms.

The plugin also includes some additional methods that helps you streamline the creation of responsive images. With the above transformed images, you can output the appropriate srcset like this, with a base64-encoded placeholder in the src attribute:

<img src="{{ craft.imagerx.placeholder({ width: 160, height: 90 }) }}" 
     sizes="100vw" 
     srcset="{{ transformedImages|srcset }}">

TIP

To unleash even more developer productivity power, check out the Imager X Power Pack (opens new window), which will help you create complex responsive images in a flash.

Additional information about the template variables can be found in Templating.

# Transform the transform

In the above examples, an Asset element is passed to the transformImage method. You can also pass a transformed image returned by Imager, a path or an url to an image that has already been transformed by Imager. This can be useful for increasing performance, or simplifying your template code. In the below example, an image is first resized and have effects applied to it, before being resized to the final sizes:

{% set newBaseImage = craft.imagerx.transformImage(selectedImage, { 
    width: 1200, 
    height: 1200, 
    effects: { modulate: [110, 100, 100], colorBlend: ['#ffcc33', 0.3], gamma: 1.2 },
    jpegQuality: 95 }) %}

{% set transformedImages = craft.imagerx.transformImage(newBaseImage, [
    { width: 600 },
    { width: 500 },
    { width: 400 }
    ], { ratio: 1 }) %}

# Transforming external images

You can also transform remote images by passing an url for an image to transformImage:

{% set externalImage = 'http://www.nasa.gov/sites/default/files/styles/full_width_feature/public/thumbnails/image/pia19808-main_tight_crop-monday.jpg' %}

{% set transformedImages = craft.imagerx.transformImage(externalImage, [
    { width: 600, height: 600 },
    { width: 500, height: 500 },
    { width: 400, height: 400 }
    ]) %}

When transforming external images, the remote image is downloaded to your storage folder, usually storage/runtime, and cached for the duration selected in the cacheDurationRemoteFiles config parameter. If you don't want to cache remote images, you can set cacheRemoteFiles to false, which will result in any downloaded files being deleted at the end of the session.