Skip to content

Home

Jump to bottom
Roland Toth Pal edited this page Dec 20, 2018 · 4 revisions

Installation and usage

  1. Install the module

  2. Use method $image->srcset(parameters...) in template files to generate markup

Note: the module got a major rewrite in version 0.1. Syntax and usage instructions have been completely changed, please read the docs carefully.

Syntax

$image->srcset($sets [, $options])
  • $sets: comma-separated image sizes, optionally with a multiplier or divisor (see the section on Sets below)
  • $options: ProcessWire image resize option array (optional)

Parameters

Sets

Sets are comma-separated list of the desired image variation dimensions. For convenience reasons it is possible to use a number as a multiplier/divisor to calculate additional sets.

The first set is the base size and needs to be in a width x height format (eg. 640x210). It doesn't have to be the smallest set, you can start with any size.

The rest of the sets can be specified in either the same format or using multipliers/divisors, eg. *2 or /3. This way you can easily add new sizes without calculating the exact dimensions.

There is no limit on the number of sets.

Set examples:

  • 120* 0x900, 600x450, 300x225

  • 1200x900, /2, /3 => 1200x900, 600x450, 400x300

  • 800x400, /2, *2 => 800x400, 400x200, 1600x800

  • 800x0, /2, *2 => 800x200, 400x100, 1600x400 (provided that the original ratio was 4:1)

One exception to the "WxH should be first" rule is that you can use the keyword original:

  • original, 600x0, 300x0 => 900x600, 600x400, 300x200 (if the input image is 900x600px)

Tips:

  • set the base set to the largest image size you need and use divisors for smaller ones (it's easier to understand)
  • use 0 for width or height and the other dimension will be calculated by ProcessWire from the image ratio
  • use original as the first set to use the original dimensions of the image

Options

Array of ProcessWire's image resize options.

Examples

<?php $img = $page->featured_image; ?>

<img data-srcset="<?php echo $img->srcset('200x300,500x750,*3') ?>"
    src="..."
    data-sizes="auto" 
    class="lazyload"
    alt="" />

<img data-srcset="<?php echo $img->srcset('200x300,*2,*3') ?>"
    src="..." 
    data-sizes="auto" 
    class="lazyload"
    alt="" />

<div data-bgset="<?php echo $img->srcset('1200x900,/2,/3') ?>"
    data-sizes="auto" 
    class="lazyload">
</div>

Example output:

<img data-srcset="/site/assets/files/1/photo.250x200.jpg 250w,/site/assets/files/1/photo.500x400.jpg 500w,/site/assets/files/1/photo.800x640.jpg 800w"
    src="..."
    data-sizes="auto" 
    class="lazyload"
    alt="" />

The "lazyload" class and the "data-sizes" attributes need to be added to the markup when used together with Lazysizes. The latter can be set to "auto" unless you need specific needs (read the Lazysizes docs for more).

Important: if you are using data-sizes="auto" it is recommended to add this into your CSS (from here):

img[data-sizes="auto"] {
    display: block;
    width: 100%;
}

Use data-srcset or data-bgset tag if you would like to use Lazysizes, otherwise use srcset.

Example: setting image quality to 80:

<img data-srcset="<?php echo $page->featured_image->srcset('200x300,*2,*3', array('quality' => 80)); ?>"
    src="..."
    data-sizes="auto" 
    class="lazyload"
    alt="" />

The src attributes in the above examples were left empty but you should fill them with data according to the markup pattern strategy of your choice. See the Helpers section below on how the module can help you with this.

Helpers

The module comes with some helpers to support markup patterns.

$img->srcsetUrls

Access individual image set urls

After calling $img->srcset(...) the $img object will get a temporary srcsetUrls property. This is an array of image sets to retrieve the smallest, largest or any other image set's url:

$img->srcsetUrls['smallest']
$img->srcsetUrls[0]
$img->srcsetUrls[1]
$img->srcsetUrls[2]
$img->srcsetUrls['largest']

This can come handy when setting the fallback src attribute:

<?php $img = $page->featured_image; ?>

<img data-srcset="<?php echo $img->srcset('200x300,*2,*3'); ?>" 
    src="<?php echo $img->srcsetUrls['smallest']; ?>" 
    data-sizes="auto" 
    class="lazyload"
    alt="" />

...or setting bgset fallback image with inline style:

<?php $img = $page->featured_image; ?>

<div data-bgset="<?php echo $img->srcset('200x300,*2,*3'); ?>"
    style="background-image: url('<?php echo $img->srcsetUrls[0]; ?>');"
    data-sizes="auto" 
    class="lazyload">
</div>

...or adding fallback image in a noscript tag:

<?php $img = $page->featured_image; ?>

<img data-srcset="<?php echo $img->srcset('200x300,*2,*3'); ?>"
    data-sizes="auto" 
    class="lazyload"
    alt="" />

<noscript>
    <img src="<?php echo $img->srcsetUrls['largest']; ?>" />
</noscript>

Remember that $img->srcsetUrls is available only after the srcset() method was called!

$config->srcsetFallbackDataUri

Global variable for data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==

Use this if you prefer a transparent image src as a fallback. You can overwrite it in your code if you wish.

<?php $img = $page->featured_image; ?>

<img data-srcset="<?php echo $img->srcset(); ?>"
    src="<?php echo $config->srcsetFallbackDataUri; ?>"
    data-sizes="auto" 
    class="lazyload"
    alt="" />

Using MarkupSrcSet with CroppableImage3

The module plays together nicely with CroppableImage3 module. Just add the crop size into the chain and that's all:

<img data-srcset="<?php echo $page->images->first()->getCrop('work-thumb')->srcset('original, /2'); ?>"
    src="..."
    data-sizes="auto" 
    class="lazyload"
    alt="" />

Note that the original keyword refers to the original dimensions of the image - in this case the one you've set for the "work-thumb" crop size in CroppableImage3.

Module settings

Loading scripts

The module loads the 'markupsrcset.js' file that consists of the following files (combined and minified):

  • ls.respimg.js
  • ls.bgset.js
  • ls.attrchange.js
  • lazysizes.js

The script is loaded only if the page markup contains "data-srcset" or "data-bgset".

You can disable loading the script at the module's settings page (eg. if you would like to load it manually).

Clone this wiki locally