2. Configuration array

Here comes the most important part, you need to configure it very carefully. I will try to explain how to create this array step-by-step. Configuration array is an associative multidimensional array.

*All examples is based on the second option of configuration settings - as a separate configuration file.

Main image sizes

The first level indicates the main image sizes, which should be registered with the Wordpress add_image_size() function. We recommend re-writing standard sizes as well, like thumbnail, medium, and large. Each main size should be an array as well, so it looks like this:

<?php
return array(
    'thumbnail' => array( ... ),
    'medium'    => array( ... ),
    'large'     => array( ... ),
    'hd'        => array( ... ),
);

In this example we overwrite the 3 standard WordPress sizes: thumbnail, medium and large, and register a new one called 'hd'.

Single image size

For small images you don't need to add any responsive tags, because they are smaller than any screen size (even mobile). For example, you have a post featured image displayed on a blog listing in a 250 x 200 size. In this case, you should specify the size array under your main image size:

<?php
return array(
    'thumbnail' => array(
        array( 250, 200, true ), // single size, dimensions set here
    ),
    ...
);

The dimensions array looks the same as parameters passed to the WordPress add_image_size() function. function. So they are:

• integer width
• integer height
• boolean crop option or array, which set crop position, default false.

Crop option with position

Cropping an image has several options for positioning using CSS parameters: left/center/right horizontal and top/middle/bottom vertical. It should be remembered that the plugin can crop the image if the size of the original image is larger than the size defined in the configuration array. Thus, if the image is smaller, cropping and positioning will not be applied to the image.

Usage rules:

array(
    int width,
    int height,
    array(
        string horizontal alignment,
        string vertical alignment,
    )
);

Example:

'visual' => array(
    array(
        array( 1920, 500, array( 'left', 'top' ) ),
        // responsive options:
        ...
        ),
        'tablet' => array(
            array( 1024, 300, true ),
            // responsive options:
            ...
        ),
        'mobile' => array(
            array( 414, 200, true ),
            // responsive options:
            ...
        ),
    ),
);    

How does it work?

In the configuration array, you can determine how the image should be positioned after the crop function:

array ( 300, 200, array ('left', 'top') );

In this example, the initial position of the image will be set in the upper left corner, just like in CSS.

Therefore, if we change left to right, the initial positioning of the image after cropping will change to the upper right corner.

The center option works the same way. It's all about horizontal positioning. The horizontal positioning only works if the height is greater than width.

Vertical positioning only works, if the width is greater than the height. The rest works the same way.

Nested sizes

Let's imagine a more complex example. You have a full-width visual image at the top of your single post. For desktop versions you will use a 1920px or even 2400px image. However, if you use a phone to browse the site, the user doesn't like to wait while such big images load because what he sees is 320-400px on his screen. So we need to set, that for big visual images we should use smaller versions on smaller resolutions.

Here we will use a more complex configuration. Now all arrays inside the main size will be much more complex and will have a special structure like this:

<?php 
return array(
    'visual' => array(
        array(
            array( 1920, 500, true ),
            // responsive options:
            ...
        ),
        'tablet' => array(
            array( 1024, 300, true ),
            // responsive options:
            ...
        ),
        'mobile' => array(
            array( 414, 200, true ),
            // responsive options:
            ...
        ),
    ),
);

As you can see here we registered a new image size "visual" with the size of 1920x500px, and it has lower resolutions which has it’s own name:

• 1024x300 (the full qualified name will be "visual-tablet")
• 414x200 (the full qualified name will be "visual-mobile")

In addition, each size has to have responsive options.

Responsive options

These are options, which will be used to generate <picture>, <img> or background HTML/CSS. Let's start with an example:

return array(
    'visual' => array(
        array(
            array( 1920, 500, true ),
            'picture' => '<source srcset="{src}" media="(min-width: 1281px)">',
            'bg'      => '', // main image, no media wrapper will be used.
            'srcset'  => '1920w', // descriptor
            'sizes'   => '(min-width: 1281px) 1920px', // condition
        ),
        'tablet' => array(
            array( 980, 9999 ),
            'picture' => '<img src="{single-src}" srcset="{src}" alt="{alt}">',,
            'bg'      => '@media screen and (max-width:980px)',
            'srcset'  => '980w',
            'sizes'   => '(min-width: 415px) 980px',
        ),
    ),
);

For each image size you can specify any of the following 4 keys:

• picture - a code part to generate <source> or <img> tags inside a <picture> tag.
• bg - media query to be used to wrap the css selector. Keep blank to set default image here.
• srcset - <img> attribute part - width descriptor for this image size.
• sizes - <img> attribute part - condition when current dimension should be visible.

If you use only one way to print your image (for example <picture> tag) - you can skip all other parts and set only 1 key picture inside responsive options.

Re-usable sizes

Some images can have similar small sizes inside. In this case you can use previously defined keys inside other main sizes. Imagine that we already have the code for "visual" image size, as shown above, then we can re-use it like this:

return array(
    'visual' => array( ... ),
    'big-banner' => array(
        array(
            array( 2400, 500, true ),
            'picture' => '<source srcset="{src}" media="(min-width: 1281px)">',
            'bg'      => '', // main image, no media wrapper will be used.
            'srcset'  => '1920w', // descriptor
            'sizes'   => '(min-width: 1281px) 1920px', // condition
        ),
        'visual-tablet' => 'inherit',
    ),
);

Retina support

To support retina screens and print both usual and bigger images you should add retina multiplier to your size name, separated with space:

return array(
    'visual 2x' => array( ... ),
);

You can add more different multipliers for the same size to generate even more retina sizes:

return array(
    'visual 2x 3x' => array( ... ),
);

However we recommend to use one retina size - 2x, this size provides good visual image quality on screen and keep your file spaceless (comparing to setting several retina multipliers).

Retina background @media queries

By default plugin search such patterns inside 'bg' property:

(min-width: XXXpx) or (max-width: XXXpx)

If such entries found, then plugin replace them with the structure below to generate @media retina query:

(min-width: XXXpx) and <min device pixel ratio query>, (min-width: XXXpx) and <min resolution query>

If you want to set your own specific media query for retina size you can use 'bg_retina' property like this:

return array(
    'big-banner 2x' => array(
        array(
            array( 2400, 500, true ),
            ...
            'bg' => '@media (min-width:1281px)',
            'bg_retina' => '@media (min-width:1281px) and {dpr}, (min-width:1281px) and {min_res}',
            ...
        ),
        ...
    ),
);

Special tokens {dpr} and {min_res} will be automatically replaced with a corresponding min device pixel ratio and min resolution values based on retina multiplier (2x or 3x).

Pre-defined RWD set

The plugin has its own set of rwd styles, which are optimal for big images display and resize them to smaller resolutions, which passed Google Page Speed tests well. This set has retina 2x support by default. It looks like this:

return array(
    'rwd 2x' => array(
	'desktop' => array(
	    array( 1920, 9999 ),
		'picture'   => '<source srcset="{src}" media="(min-width: 1281px)">',
		'bg'        => '@media (min-width:1281px)',
		'bg_retina' => '@media (min-width:1281px) and {dpr}, (min-width:1281px) and {min_res}',
		'srcset'    => '{w}w',
		'sizes'     => '(min-width: 1281px) {w}px',
	),
	'laptop' => array(
		array( 1280, 9999 ),
		'picture'   => '<source srcset="{src}" media="(min-width: 981px)">',
		'bg'        => '@media (min-width: 981px) ',
		'bg_retina' => '@media (min-width: 981px) and {dpr}, (min-width: 981px) and {min_res}',
		'srcset'    => '{w}w',
		'sizes'     => '(min-width: 981px) {w}px',
	),
	'tablet' => array(
		array( 980, 9999 ),
		'picture'   => '<source srcset="{src}" media="(min-width: 415px)">',
		'bg'        => '@media (min-width: 415px)',
		'bg_retina' => '@media (min-width: 415px) and {dpr}, (min-width: 415px) and {min_res}',
		'srcset'    => '{w}w',
		'sizes'     => '(min-width: 415px) {w}px',
	),
	'mobile' => array(
		array( 414, 9999 ),
		'picture'   => '<img src="{single-src}" srcset="{src}" alt="{alt}">', // mobile-first strategy picture img.
		'bg'        => '',                                                 // mobile-first strategy bg.
		'bg_retina' => '@media {dpr}, {min_res}',
		'srcset'    => '{w}w',
		'sizes'     => '{w}px',
	),
    ),
);

You can use these presets inside your own styles.

Image source modification

Sometimes we need add HTML-class to <img> element inside the <picture> element. Since the plugin can add an HTML-class only to the outer element, we should resort to some trick - add needed class to HTML code directly in configuration array:

For example, add "lazyload" class:

'mobile' => array(
    array( 414, 9999 ),
    'picture'   => '<img class="lazyload" src="{single-src}" srcset="{src}" alt="{alt}">',
    'bg'        => '',
    'bg_retina' => '@media {dpr}, {min_res}',
    'srcset'    => '{w}w',
    'sizes'     => '{w}px',
),

Also, in the case of "lazyload" we should change standard 'src/srcset' attributes to 'data-src/data-srcset'. It can be done exactly the same:

'mobile' => array(
    array( 414, 9999 ),
    'picture'   => '<img class="lazyload" data-src="{single-src}" data-srcset="{src}" alt="{alt}">',
    'bg'        => '',
    'bg_retina' => '@media {dpr}, {min_res}',
    'srcset'    => '{w}w',
    'sizes'     => '{w}px',
),

Important: You should remember, this option will be applied to all images of this size rendered through this plugin.

Next: Template functions