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
└── Partials/Image/
    ├── Tag.html             # <img> element partial
    ├── TagInFigure.html     # <img> without class (for figures)
    ├── Link.html            # <a> wrapper partial
    └── Figure.html          # <figure> wrapper partial

Note

This extension stores partials in Templates/Partials/ rather than the standard TYPO3 location Partials/. When overriding, you can use either location by configuring your partialRootPaths accordingly. For standard TYPO3 structure in your site package, use Resources/Private/Partials/.

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.tags.img {
    # Add your templates with higher priority (higher number = higher priority)
    settings.templateRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Templates/
    }
    settings.partialRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Partials/
    }
    settings.layoutRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Layouts/
    }
}

Note

The configuration must be placed within lib.parseFunc_RTE.tags.img (not directly in lib.parseFunc_RTE). The same configuration can be added to tags.a and tags.figure to control the templates used for images that are already wrapped in <a> or <figure> elements.

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"
         decoding="async" />
    <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"
         decoding="async" />
</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}"')}
     decoding="async" />

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.
CSS classes move to figure: When images have captions, CSS classes defined on the <img> element are applied to the <figure> wrapper instead. This ensures valid HTML5 semantics. If you need classes specifically on the <img> within a figure, create a custom WithCaption.html template override.
Decoding attribute: The default templates include decoding="async" on all images to improve rendering performance by allowing the browser to decode images off the main thread. This is a modern best practice that does not affect visual output.
Whitespace is stripped: The rendering service removes whitespace between HTML tags to prevent parseFunc_RTE from creating <p> </p> artifacts. Templates can use readable multi-line formatting; it will be normalized. However, deliberate spacing between inline elements will be removed.

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