Template Overrides

New in version 13.1.5

The new Fluid-based rendering architecture allows complete customization of image output via template overrides.

Override the default Fluid templates to customize image rendering output for your site's design requirements.

Table of contents

Overview

The extension provides six Fluid templates for different rendering contexts:

Template directory structure

Resources/Private/Templates/Image/
├── Standalone.html      # Basic image without wrapper
├── WithCaption.html     # Image with <figure>/<figcaption>
├── Link.html            # Image wrapped in <a> tag
├── LinkWithCaption.html # Linked image with caption
├── Popup.html           # Image with lightbox/popup link
└── PopupWithCaption.html # Popup image with caption

Template selection

The ImageRenderingService automatically selects the appropriate template:

Condition	Template
No link, no caption	`Standalone.html`
No link, has caption	`WithCaption.html`
Has link, no popup, no caption	`Link.html`
Has link, no popup, has caption	`LinkWithCaption.html`
Has popup, no caption	`Popup.html`
Has popup, has caption	`PopupWithCaption.html`

Setting up overrides

Step 1: Create template directory

In your site package, create the override directory:

Create template override directory

mkdir -p packages/my_sitepackage/Resources/Private/Templates/Image/

Step 2: Configure TypoScript

Add the template path to your TypoScript setup:

EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript

lib.parseFunc_RTE {
    # Add your templates with higher priority (lower number = higher priority)
    settings.templateRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Templates/
    }
}

Step 3: Create override templates

Copy and modify only the templates you need to customize.

Available DTO properties

All templates receive the image variable containing an ImageRenderingDto:

Available template variables

<!-- Core properties -->
{image.src}                    <!-- Processed image URL -->
{image.width}                  <!-- Display width in pixels -->
{image.height}                 <!-- Display height in pixels -->
{image.alt}                    <!-- Alternative text -->
{image.title}                  <!-- Title attribute -->
{image.caption}                <!-- Caption text (XSS-sanitized) -->
{image.isMagicImage}           <!-- Whether TYPO3 processing applied -->

<!-- HTML attributes -->
{image.htmlAttributes.class}   <!-- CSS classes -->
{image.htmlAttributes.style}   <!-- Inline styles -->
{image.htmlAttributes.loading} <!-- lazy/eager -->

<!-- Link properties (when linked) -->
{image.link.url}               <!-- Link URL -->
{image.link.target}            <!-- Link target (_blank, etc.) -->
{image.link.class}             <!-- Link CSS classes -->
{image.link.isPopup}           <!-- Whether popup/lightbox -->

See ImageRenderingDto for complete property documentation.

Example overrides

Bootstrap 5 responsive image

Override Standalone.html for Bootstrap 5 responsive images:

EXT:my_sitepackage/Resources/Private/Templates/Image/Standalone.html

<img src="{image.src}"
     alt="{image.alt}"
     width="{image.width}"
     height="{image.height}"
     class="img-fluid {image.htmlAttributes.class}"
     {f:if(condition: image.title, then: 'title="{image.title}"')}
     {f:if(condition: image.htmlAttributes.style, then: 'style="{image.htmlAttributes.style}"')}
     loading="lazy"
     decoding="async" />

Figure with custom styling

Override WithCaption.html for custom figure styling:

EXT:my_sitepackage/Resources/Private/Templates/Image/WithCaption.html

<figure class="content-image{f:if(condition: image.htmlAttributes.class, then: ' {image.htmlAttributes.class}')}">
    <img src="{image.src}"
         alt="{image.alt}"
         width="{image.width}"
         height="{image.height}"
         class="content-image__img"
         {f:if(condition: image.title, then: 'title="{image.title}"')}
         loading="lazy" />
    <figcaption class="content-image__caption">
        {image.caption}
    </figcaption>
</figure>

PhotoSwipe lightbox integration

Override Popup.html for PhotoSwipe v5 integration:

EXT:my_sitepackage/Resources/Private/Templates/Image/Popup.html

<a href="{image.link.url}"
   class="pswp-gallery__item {image.link.class}"
   data-pswp-width="{image.width}"
   data-pswp-height="{image.height}"
   {f:if(condition: image.link.target, then: 'target="{image.link.target}"')}>
    <img src="{image.src}"
         alt="{image.alt}"
         width="{image.width}"
         height="{image.height}"
         {f:if(condition: image.title, then: 'title="{image.title}"')}
         {f:if(condition: image.htmlAttributes.class, then: 'class="{image.htmlAttributes.class}"')}
         loading="lazy" />
</a>

Lazy loading with placeholder

Override Standalone.html for progressive image loading:

Lazy loading with SVG placeholder

<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 {image.width} {image.height}'%3E%3C/svg%3E"
     data-src="{image.src}"
     alt="{image.alt}"
     width="{image.width}"
     height="{image.height}"
     class="lazyload {image.htmlAttributes.class}"
     {f:if(condition: image.title, then: 'title="{image.title}"')}
     {f:if(condition: image.htmlAttributes.style, then: 'style="{image.htmlAttributes.style}"')} />

Best practices

Only override what you need: Copy only templates requiring changes.
Preserve accessibility: Always include alt attribute and maintain semantic HTML.
Keep security intact: The DTO properties are pre-sanitized. Do not apply additional encoding that could double-escape content.
Test all contexts: Verify overrides work with captions, links, and popups.
Use native lazy loading: Prefer loading="lazy" over JavaScript solutions.

Debugging templates

Enable Fluid debugging to inspect available variables:

Debug all template variables

<f:debug>{_all}</f:debug>

Or in TypoScript:

Enable debug mode via TypoScript

lib.parseFunc_RTE.settings.debug = 1