README

A gallery extension for TYPO3 v13 and v14 built around one core idea: image sizes are calculated mathematically from your Bootstrap grid configuration, and all variants are pre-generated via CLI — so the first page load after a cache clear is just as fast as every subsequent one.

Why another gallery extension?

Most TYPO3 gallery extensions generate processed images on the first frontend request — which means a slow, blocking page load whenever the TYPO3 cache is cleared. They also require you to manually specify image widths that match your grid, or they produce srcset values that don't match the actual rendered size.

OT Gallery takes a different approach:

• Sizes are derived from your grid, not guessed. You configure your Bootstrap 5 container widths, gutters and column counts once in the SiteSet. The extension calculates exact pixel widths for every breakpoint — including HiDPI variants — and generates a mathematically correct sizes attribute.

• A CLI command pre-generates every variant before deployment. gallery:process uses the same internal processing pipeline as the frontend renderer, so the browser's first request hits the file system cache directly. No cold-start penalty, no server spike on cache clear.

• SiteSet configuration — TypoScript is provided as a TYPO3 v13 SiteSet; no manual TypoScript includes required, just add the extension as a SiteSet dependency.

• Minimal JavaScript. The gallery itself requires only Bootstrap 5 (which you likely already have) and optionally Fancybox 5 for the lightbox. No custom gallery framework, no jQuery.

• Server-side pagination means the gallery works correctly with hundreds of images and remains SEO-friendly — no JavaScript rendering required for content that search engines need to index.

Features

• Responsive images — <img srcset> with WebP format, calculated from container widths, gutter and column configuration
• Lightbox — Fancybox, enable/disable per content element via checkbox; caption fields (title/description/copyright) configurable via SiteSet
• Two image sources — FAL file selection or folder (including recursive subfolders, multiple folders)
• Three layout modes — Grid, Masonry (CSS columns, no CLS), Justified (planned)
• Aspect ratio + rendering — Free, 1:1, 4:3, 3:2, 16:9 with cover/contain/fill per content element
• Server-side pagination — Cached, SEO-friendly URLs via TYPO3 Route Enhancer
• FAL metadata — Figcaption (title/description/copyright, optional visually-hidden) and three-dot context menu ( title/description/copyright) — each field toggled independently per content element
• Per-image download — Optional download button in three-dot context menu
• CLI pre-processing — Pre-generate all image variants to avoid server load on cache clear; uses ImageService to guarantee identical cache keys with the frontend
• SiteSet configuration — All defaults configurable via TYPO3 v13 SiteSets (no TypoScript)
• Bootstrap 5 — Grid, pagination, dropdown components
• Accessible — ARIA labels, keyboard navigation, visually-hidden screen reader text

Requirements

Installation

composer require oliverthiele/ot-gallery

Then run the TYPO3 setup:

vendor/bin/typo3 extension:setup -e ot_gallery
# or via DDEV:
ddev typo3 extension:setup -e ot_gallery

Configuration

1. Add SiteSet

Include the SiteSet in your site configuration (config/sites/yoursite/config.yaml):

dependencies:
    - oliverthiele/ot-gallery

2. Add Routing

Include the pagination route enhancer to get SEO-friendly pagination URLs (?tx_otgallery_page=2 → /page-2):

imports:
    - { resource: 'EXT:ot_gallery/Configuration/Routes/Default.yaml' }

3. Add SCSS

Copy or import the example stylesheet into your project build:

@use 'path/to/EXT:ot_gallery/Resources/Private/Scss/Example' as gallery;

Or copy Resources/Private/Scss/Example.scss into your project and adapt as needed.

4. Initialize Bootstrap JavaScript

The three-dot context menu (description, copyright, download) uses Bootstrap Dropdown. Ensure Bootstrap JS is initialized on your page:

// If not using bootstrap.bundle.js (which auto-initializes):
document.querySelectorAll('[data-bs-toggle="dropdown"]').forEach(el => {
    new bootstrap.Dropdown(el);
});

5. Include Fancybox

If you use the lightbox feature, include Fancybox 5 in your project:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fancyapps/ui@5/dist/fancybox/fancybox.css">
<script src="https://cdn.jsdelivr.net/npm/@fancyapps/ui@5/dist/fancybox/fancybox.umd.js"></script>

Then initialize:

Fancybox.bind('[data-fancybox]');

SiteSet Settings

All settings can be configured in your site's SiteSet or overridden per content element via FlexForm.

Grid & Breakpoints

Thumbnail Defaults

Lightbox

Pagination

Processing (CLI)

FlexForm Options (per content element)

Layout tab

• Layout — Grid / Masonry
• Aspect ratio — Free / 1:1 / 4:3 / 3:2 / 16:9
• Rendering — Cover / Contain / Fill (visible only when aspect ratio is not free)
• Column override — Override default columns per breakpoint

Sort tab

• Sort field — By filename / date / custom (FAL sort order)
• Sort direction — Ascending / Descending
• Items per page — Override SiteSet default (0 = use SiteSet default)

Features tab

• Enable lightbox — Checkbox; activates Fancybox for all images in this element
• Figcaption group — Show title / description / copyright below each image; optionally visually-hidden (screen readers only)
• Menu group — Show title / description / copyright in the three-dot context menu per image
• Enable download — Per-image download button in the three-dot context menu

CLI: Image Pre-Processing

Pre-process all gallery images to avoid server load when caches are cleared:

# Process all galleries
vendor/bin/typo3 gallery:process

# Process a specific content element
vendor/bin/typo3 gallery:process --content-uid=42

# Only process galleries where configuration has changed
vendor/bin/typo3 gallery:process --unprocessed-only

# Dry run (show what would be processed)
vendor/bin/typo3 gallery:process --dry-run

# Verbose output (show widths and column info per breakpoint)
vendor/bin/typo3 gallery:process -v

The command uses a configuration hash (MD5) stored per content element to detect when image dimensions need to be recalculated (e.g. after changing column counts or SiteSet grid settings).

The CLI uses ImageService::applyProcessingInstructions() — identical to the frontend ViewHelpers — so the pre-generated files produce exact cache hits on the first page load. No images are re-processed by the frontend.

Template Customization

The extension follows TYPO3's template override convention. Override paths in your TypoScript:

tt_content.ot_gallery {
    templateRootPaths.20 = EXT:your_sitepackage/Resources/Private/Templates/
    partialRootPaths.20 = EXT:your_sitepackage/Resources/Private/Partials/
    layoutRootPaths.20 = EXT:your_sitepackage/Resources/Private/Layouts/
}

Available template variables

ViewHelpers

SiteKit Integration (optional)

If your project uses OT SiteKit Base, the extension ships with a Configuration/SiteKit.yaml that registers ot_gallery with the SiteKit grid system:

elements:
    -   ctype: ot_gallery
        groups: [ group_content_wide ]
        grid: { minCols: 6, requiresFullWidth: false }

This tells SiteKit that the gallery requires at least 6 grid columns and does not need to span the full width. Without SiteKit installed, this file is simply ignored.

Planned Features

• Fancybox across pagination pages — Show all images in lightbox slideshow regardless of current page
• Subfolder galleries — Subfolders as nested gallery entries with cover image
• Folder/image sidecar files — gallery.json per folder, image.jpg.json per image for metadata without EXIF
• ZIP download — Pre-generated ZIP via CLI, served by middleware
• EXIF display — Camera, aperture, shutter speed, ISO, date in metadata overlay
• Search / Filter — Server-side via middleware or Extbase plugin (client-side not feasible with server-side pagination)

License

GPL-2.0-or-later — see LICENSE

Author

Oliver Thiele — oliver-thiele.de