Media Twig Tools

CONTENTS OF THIS FILE
---------------------

* Introduction
* Requirements
* Installation
* Configuration
* Maintainers

INTRODUCTION
------------

The Media Twig Tools modules brings some features to facilitate the integration
of media entity in twig template, especially for images and pictures. By
default, media are rendered with the drupal rendering process, bringing
potential unnecessary tags to display simple image and picture tags. Media Twig
Tools clean the default rendered markup of images.

It also brings some tools to decouple the theme sources and the configuration
for images. By the default, Drupal brings the image style configuration to deal
with the adaptive / responsive image. This can be very difficult to a front end
developper to integrate these practices when he has to deal with a lot of
several configurations for several image sizes and rendering pecularities. Media
Twig Tools provides tools to integrate srcSet settings, and picture settings
(with media queries) directly in twig without needing the definition of specific
configuration for each breakpoint, each image style etc... Media Twig Tools
allow front-end developpers to generate styled images at runtime.

REQUIREMENTS
------------

This module requires drupal/media modules.

INSTALLATION
------------

Install the Media Twig Tools module as you would normally install a contributed
Drupal module. Visit https://www.drupal.org/node/1897420 for further
information.

USE
-------------

### Render an image tag with srcset

Here is an example of how to render an image with src set and a customise the
DOM in twig.

{{ imgFromMedia(
        content.field_media_1,              // The media to display.

        // Les options
        {
            style: 'landscape',             // The image style base.
            class:'bordered grow',          // Custom image class.
            attributes:{ title:'Title', alt:'Overriden alt', 'data-other':'other data'}, // Custom attributes

            // Source set :
            srcset: {
              '1x': {                       // media query
                style: 'portrait',          // Base image style
                rules: [                    // List of new image style rules to apply
                  {
                    id: 'image_crop',       // Rule type
                    data: {
                      'width': 100,         // Rule data
                      'height': 200,
                    }
                  }
                ]
              },
              '2x': 'default'               // 'default' to display the default image.
          }
    } ) }}

Result :

<img title="Title" alt="Overriden alt" data-ok="other data"
     class="bordered grow"
     srcset="/sites/default/files/builder/portrait/width100height200image_crop/1_image.png 1x, /sites/default/files/styles/landscape/public/images/image.png?h=dae1a89e 2x"
     src="/sites/default/files/styles/landscape/public/images/image.png?h=dae1a89e"
     loading="lazy"/>

### Render a picture tag

Here is an example of how to render a picture tag with src set and a customise
the DOM in twig.

{{ pictureFromMedia(
    content.field_media_1,
    {
      style:'landscape',
      class:'class1 class2',
      attributes: {
        'data-other': 'other data',
        'title': 'Title'
      },
      settings: {
        '(min-width: 1024px)':{
          style: 'landscape',
          srcset: {
            '2x': 'default',
            '1x': {
              rules: [
                {
                  id: 'image_scale',
                  data: {
                    width: 2000,
                    height: 1000
                  }
                }
              ]
            }
          }
        },
        '(max-width: 1024px)': {
          style: 'portrait',
          srcset: {
            '2x': 'default',
            '1x': {
              rules: [
                {
                  id: 'image_scale_and_crop',
                  data: {
                    width: 200,
                    height: 300
                  }
                }
              ]
            }
          }
        }
      }
    })
  }}

Result :

<picture>
  <source
    srcset="/sites/default/files/styles/landscape/public/images/mac_logo-noir-bleu.png?h=dae1a89e 2x,/sites/default/files/builder/landscape/width2000height1000image_scale/4_mac_logo-noir-bleu.png 1x"
    media="(min-width: 1024px)">
  <source
    srcset="/sites/default/files/styles/portrait/public/images/mac_logo-noir-bleu.png?h=251a1d33 2x,/sites/default/files/builder/portrait/width200height300image_scale_and_crop/4_mac_logo-noir-bleu.png 1x"
    media="(max-width: 1024px)">
  <img
    data-other="other data" title="Title" class="class1 class2"
    alt="Move and co"
    src="/sites/default/files/styles/landscape/public/images/mac_logo-noir-bleu.png?h=dae1a89e"
    loading="lazy">
</picture>

CONFIGURATION
-------------

1. Navigate to Administration > Configuration > Media > Media Twig Tools.

Configurable parameters:

* Settings / Built image directory name : The directory where custom images are
built.
* Settings / No image style identifier : The default identifier to indicate
Media Twig Tools to not use any image style. Make sure it does not match an
existing image style name.

MAINTAINERS
-----------

* Thomas Sécher : https://www.drupal.org/u/tsecher