README

This Twig extension facilitate the integration of responsive images' markup in Twig templates.

It use LiipImagineBundle and his filters to generate HTML markup with all you need to handle responsive images.

It also provide a javascript module to automatically instantiate yall.js on rendered images.

Installation

Use the package manager composer to install the extension.

composer require umanit/twig-image-extension

Load the bundle into your Symfony project.

<?php

# config/bundles.php
return [
    // ...
    Umanit\TwigImage\UmanitTwigImageBundle::class => ['all' => true],
];

(Optionnal) Install bundle assets if you want to use the javascript module for yall.js:

bin/console assets:install --symlink

Configuration

Some functions render HTML markup with ability to use lazy loading on images. It's possible to customize the classes used.

You just need to create a file config/packages/umanit_twig_image.yaml:

umanit_twig_image:
    class_selector: lazy
    placeholder_class_selector: lazy-placeholder
    blur_class_selector: lazy-blur

Usage

The following Twig functions are available in your templates.

umanit_image_figure_lazy_load
umanit_image_figure
umanit_image_picture_lazy_load
umanit_image_picture
umanit_image_srcset
(Optional) Javascript module to instantiate yall.js
(Optional) Import CSS files for blur effect on yall.js lazy images

When a LiipImagine filter is used, the extension will read his configuration and automatically takes the right width to apply in the markup.

When the used function is for lazy load, lazy and lazy-placeholder classes are used but can be customized as explained in the Configuration part.

List of supported filters:

relative_resize: Use the widen value
thumbnail: Use the first value of size

With the use of Thumbnail Filter, width and height attributes are added in the <img> tag (since they are provided in the LiipImagine Filter). By doing this, sudden layout shifts are avoided for a better user experience.

umanit_image_figure_lazy_load

Generates a figure tag with an img inside and his noscript version. The lazy, lazy-placeholder and lazy-blur classes are add to facilitate the integration with yall.js for example.

Parameters

Name	Explanation
path	Path to the image, used to generated the browser path with LiipImagine
srcFilter	Name of the LiipImagine filter used to generate the path for `data-src`
placeholderFilter	Name of the LiipImagine filter used to generate the path for `src`
srcsetFilters	A list of LiipImagine filters used to generate the `data-srcset`
alt	The text to put in the `alt` attribute of the `img`
imgClass	Classes to add on the `img`
sizes	Value of the `sizes` attribute (`100vw` if not defined)
figureClass	Classes to add on the `figure`

Example

Click to show

    umanit_image_figure_lazy_load(
      image.path,
      'small_thumbnail',
      'tiny_thumbnail',
      ['thumbnail', 'large_thumbnail'],
      'image alt',
      'img img--cover img--zoom',
      '(min-width: 768px) 33.3vw, 100vw',
      'class-figure',
    )

HTML generated

<figure class="class-figure">
  <img
    alt="image alt"
    class="lazy lazy-placeholder lazy-blur img img--cover img--zoom"
    src="https://domain.tld/media/cache/tiny_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    data-src="https://domain.tld/media/cache/resolve/small_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    sizes="(min-width: 768px) 33.3vw, 100vw"
    data-srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w"
  >
  <noscript>
    <img
      class="img img--cover img--zoom"
      alt="home"
      src="https://domain.tld/media/cache/resolve/small_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
      sizes="(min-width: 768px) 33.3vw, 100vw"
      srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w"
    >
  </noscript>
</figure>

umanit_image_figure

Generates a figure tag with an img inside.

Parameters

Name	Explanation
path	Path to the image, used to generated the browser path with LiipImagine
srcFilter	Name of the LiipImagine filter used to generate the path for `src`
srcsetFilters	A list of LiipImagine filters used to generate the `srcset`
alt	The text to put in the `alt` attribute of the `img`
imgClass	Classes to add on the `img`
sizes	Value of the `sizes` attribute (`100vw` if not defined)
figureClass	Classes to add on the `figure`

Example

Click to show

    umanit_image_figure(
      image.path,
      'small_thumbnail',
      ['thumbnail', 'large_thumbnail'],
      'image alt',
      'img img--cover img--zoom',
      '(min-width: 768px) 33.3vw, 100vw',
      'class-figure',
    )

HTML generated

<figure class="class-figure">
  <img
    alt="image alt"
    class="lazy lazy-placeholder lazy-blur img img--cover img--zoom"
    src="https://domain.tld/media/cache/resolve/small_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    sizes="(min-width: 768px) 33.3vw, 100vw"
    srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w"
  >
</figure>

umanit_image_picture_lazy_load

Generates a picture tag with an img inside and X source. Each source can have a media and sizes attribute if needed. The lazy and lazy-placeholder classes are add to facilitate the integration with yall.js for example.

Parameters

Name	Explanation
path	Path to the image, used to generated the browser path with LiipImagine
srcFilter	Name of the LiipImagine filter used to generate the path for `data-src`
placeholderFilter	Name of the LiipImagine filter used to generate the path for `src`
srcsetFilters	A list of LiipImagine filters used to generate the `data-srcset`
sources	A list of LiipImagine filters used to generate the `sources` tags. The key of the array is the path to the image and the value can be a list of filters name or, if you need to define a `media` or `sizes` attribute on the source, an array with `filters` and `media` and/or `sizes` key.
alt	The text to put in the `alt` attribute of the `img`
imgClass	Classes to add on the `img`
pictureClass	Classes to add on the `picture`

Example

Click to show

  umanit_image_picture_lazy_load(
    image.path,
    'small_thumbnail',
    'tiny_thumbnail',
    ['thumbnail', 'large_thumbnail'],
    {
      (image.path): {
        'media': '(min-width: 768px)',
        'sizes': '(min-width: 1400px) 25vw, 50vw',
        'filters': ['thumbnail', 'large_thumbnail']
      },
      (image2.path): ['thumbnail', 'large_thumbnail']
    },
    'alt img',
    'img img-fluid',
    'class-picture'
  )

HTML generated

<picture class="class-picture">
  <source media="(min-width: 768px)" sizes="(min-width: 1400px) 25vw, 50vw" srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w">
  <source srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg2 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg2 2880w">
  <img
    class="img img-fluid"
    alt="alt img"
    src="https://domain.tld/media/cache/tiny_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    data-src="https://domain.tld/media/cache/resolve/small_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    data-srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w"
  >
</picture>

umanit_image_picture

Generates a picture tag with an img inside and X source. Each source can have a media and sizes attribute if needed.

Parameters

Name	Explanation
path	Path to the image, used to generated the browser path with LiipImagine
srcFilter	Name of the LiipImagine filter used to generate the path for `src`
srcsetFilters	A list of LiipImagine filters used to generate the `srcset`
sources	A list of LiipImagine filters used to generate the `sources` tags. The key of the array is the path to the image and the value can be a list of filters name or, if you need to define a `media` or `sizes` attribute on the source, an array with `filters` and `media` and/or `sizes` key.
alt	The text to put in the `alt` attribute of the `img`
imgClass	Classes to add on the `img`
pictureClass	Classes to add on the `picture`

Example

Click to show

  umanit_image_picture(
    image.path,
    'small_thumbnail',
    ['thumbnail', 'large_thumbnail'],
    {
      (image.path): {
        'media': '(min-width: 768px)',
        'sizes': '(min-width: 1400px) 25vw, 50vw',
        'filters': ['thumbnail', 'large_thumbnail']
      },
      (image2.path): ['thumbnail', 'large_thumbnail']
    },
    'alt img',
    'img img-fluid',
    'class-picture'
  )

HTML generated

<picture class="class-picture">
  <source media="(min-width: 768px)" sizes="(min-width: 1400px) 25vw, 50vw" srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w">
  <source srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg2 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg2 2880w">
  <img
    class="img img-fluid"
    alt="alt img"
    src="https://domain.tld/media/cache/resolve/small_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg"
    srcset="https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w"
  >
</picture>

umanit_image_srcset

Generates the content of a srcset attribute if you wan to use it in your own markup.

Parameters

Name	Explanation
path	Path to the image, used to generated the browser path with LiipImagine
filters	A list of LiipImagine filters used to generate the `srcset`

Example

Click to show

umanit_image_srcset(image.path, ['thumbnail', 'large_thumbnail'])

HTML generated

https://domain.tld/media/cache/resolve/thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 260w, https://domain.tld/media/cache/resolve/large_thumbnail/99/30/c1f268bbf1487fb88734f2ba826b.jpeg 2880w

(Optional) Javascript module to instantiate yall.js

If you want to use yall.js to manage the lazy load of your images, the bundle provides a javascript module that can be called in your application.

yall.js needs to be installed manually: yarn add yall-js

Then you need to import the module and instantiate it by passing the yall library. An optional argument loadEventCallback is available if you want to add more customization. It will be called in the load event of yall.js.

import yall from 'yall-js';
import umanitImageLazyLoad from '../../public/bundles/umanittwigimage/js/umanit-image-lazy-loading';

umanitImageLazyLoad(yall);

(Optional) Import CSS files for blur effect on yall.js lazy images

You can import the CSS file for adding a blur effect on lazy images.

<link rel="stylesheet" href="{{ asset('bundles/umanittwigimage/css/umanit-image-lazy-loading.css') }}">

Example in webpack

import '../../public/bundles/umanittwigimage/css/umanit-image-lazy-loading.css';

⚠ For a best usage for the users without javascript you should add a no-js class on the html element

<html class="no-js">

Finally, add this one line <script> before any <link> or <style> elements in the document <head>

<!-- Remove the no-js class on the <html> element if JavaScript is on -->
<script>document.documentElement.classList.remove("no-js");</script>

See https://github.com/malchata/yall.js/#what-about-users-without-javascript for more details.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

umanit / twig-image-extension

Maintainers

Details

README

Installation

Configuration

Usage

umanit_image_figure_lazy_load

Parameters

Example

umanit_image_figure

Parameters

Example

umanit_image_picture_lazy_load

Parameters

Example

umanit_image_picture

Parameters

Example

umanit_image_srcset

Parameters

Example

(Optional) Javascript module to instantiate yall.js

(Optional) Import CSS files for blur effect on yall.js lazy images

Contributing

License