Working with Images in Templates

For outputting one or more images in MetaModels, the File attribute is available. To select a file or multiple files, the input mask provides a button that opens a popup for browsing the file manager.

In the basic attribute settings, various options can be configured such as the base path, single or multiple selection, file types, etc.

In most cases, image files should also be output as actual images. The relevant settings for the attribute are found in the render settings. Here, the checkbox “Use as image field with preview image” must be enabled and an image size selected (this also applies to display in the backend list view). Optionally, a placeholder image can be selected and a lightbox view can be enabled.

This setting applies to both frontend and backend display (if images are shown there).

In a custom FE template, the html5 node must be output for image rendering —
e.g. <?= $arrItem['html5']['my_image'] ?>.

By selecting or customising the attribute template, additional output requirements can be met such as listing as ul or div, markup for galleries or sliders, etc.

These output options cover a wide range of requirements. However, if images need to be output that are included via a relation — through the raw node — they are only available as the original image via path or UUID.

To also manipulate these images in a custom template, the following snippets provide guidance.

More on the available methods can be found in the Contao documentation under Image processing.

On the topic of responsive images, there is a (still relevant) talk by Peter Müller from CK2016.

Outputting an Image Included via Single Select

Insert Tags

see Insert Tags

1<?php if (!empty($arrItem['raw']['speaker']['biography_image']): ?>
2    {{image::<?= $arrItem['raw']['speaker']['biography_image'] ?>?width=180&height=180&mode=crop&class=img--circle}}
3    <!-- OR -->
4    {{picture::<?= $arrItem['raw']['speaker']['biography_image'] ?>?size=_image_circle}}
5    <!-- OR -->
6    {{figure::<?= $arrItem['raw']['speaker']['biography_image'] ?>?size=_image_circle&metadata[title]=<?= $arrItem['raw']['speaker']['full_name'] ?>}}
7<?php endif; ?>

Example for $size (see):

 1# config/config.yml
 2contao:
 3    image:
 4        sizes:
 5            _defaults:
 6                formats:
 7                    jpg: [webp, jpg]
 8                    webp: [webp, jpg]
 9                    png: [webp, png]
10                densities: 0.5x, 2x, 3x
11                lazy_loading: true
12                resize_mode: proportional
13            image_circle:
14                width: 180
15                height: 180
16                resize_mode: crop
17                zoom: 100
18                css_class: img--circle

Image Studio FigureRenderer

  • $from: path to the file

  • $size: see above

  • $configuration: configuration options e.g. metadata

  • $template: output template

1<?php
2if (!empty($arrItem['raw']['speaker']['biography_image'])) {
3   $from          = $arrItem['raw']['speaker']['biography_image'];
4   $size          = '_image_circle';
5   $configuration = [];
6   $template      = 'image';
7   echo $container->get('contao.image.studio.figure_renderer')->render($from, $size, $configuration, $template);
8}
9?>

Image Studio FigureBuilder

see FigureBuilder

  • fromPath: path to the file

  • setSize: see above

  • $configuration: configuration options e.g. metadata

  • $template: output template

 1<?php
 2if (!empty($arrItem['raw']['speaker']['biography_image'])) {
 3    $figure = $container
 4      ->get('contao.image.studio')
 5      ->createFigureBuilder()
 6      ->fromPath($arrItem['raw']['speaker']['biography_image'])
 7      ->setSize('_image_circle')
 8      ->build();
 9
10    $template = new FrontendTemplate('image');
11
12    $figure->applyLegacyTemplateData($template);
13    //$template->setData($figure->getLegacyTemplateData()); // Alternative
14    echo $template->parse();
15}
16?>

Image Studio PictureFactory

see PictureFactory

  • setSize: see above

  • $data: image data + metadata

  • $pictureTemplate: output template

 1<?php
 2// would typically be extracted into a helper
 3use Contao\FrontendTemplate;
 4use Contao\StringUtil;
 5use Contao\System;
 6
 7$container      = System::getContainer();
 8$rootDir        = $container->getParameter('kernel.project_dir');
 9$pictureFactory = $container->get('contao.image.picture_factory');
10
11// ...
12if (!empty($arrItem['raw']['speaker']['biography_image'])) {
13   $staticUrl = $container->get('contao.assets.files_context')->getStaticUrl();
14   $picture   = $pictureFactory->create($rootDir . '/' . $arrItem['raw']['speaker']['biography_image'], '_image_circle');
15
16   $data = [
17      'img'     => $picture->getImg($rootDir, $staticUrl),
18      'sources' => $picture->getSources($rootDir, $staticUrl),
19      'alt'     => StringUtil::specialcharsAttribute(''),
20      'class'   => StringUtil::specialcharsAttribute(''),
21   ];
22
23   $pictureTemplate = new FrontendTemplate('picture_default');
24   $pictureTemplate->setData($data);
25
26   echo $pictureTemplate->parse();
27}
28?>

Note

This page is open to further snippets — once MM also supports Twig templates, the page will be updated accordingly.