PhotoSwipe für TYPO3

Bildergalerien auf mobilen Geräten funktionieren nur mit touch-optimierten Lightboxen

Die meisten TYPO3-Websites nutzen Lightboxen, die für Desktop-Browser entwickelt wurden: Fancybox, Colorbox, Magnific Popup. Auf Smartphones und Tablets fühlen sich diese Lösungen fremd an, weil Zoom und Navigation nicht auf Touch-Gesten reagieren, sondern auf Mausklicks. PhotoSwipe ist eine JavaScript-Library, die von Grund auf für Touch gebaut wurde. Die TYPO3-Extension integriert PhotoSwipe als Bildergalerie mit Pinch-to-Zoom, Swipe-Navigation und responsivem Layout. Bei unter 30 KB (minified + gzip) ist PhotoSwipe gleichzeitig eine der leichtgewichtigsten Lightbox-Lösungen am Markt.

Für Websites mit hohem Mobile-Anteil, also heute praktisch alle, ist das keine optionale Verbesserung, sondern eine funktionale Anforderung. Besucher erwarten die gleichen Gesten, die sie von der nativen Foto-App ihres Smartphones kennen.

Typische Einsatzszenarien umfassen Portfolio-Galerien, Produktbilder und Medienarchive

Das häufigste Szenario sind Portfolio-Galerien auf Agentur-, Architektur- oder Fotografie-Websites. Ein Fotograf zeigt 20 bis 40 Bilder pro Projekt. Besucher klicken ein Thumbnail, sehen das Bild in voller Auflösung, zoomen per Pinch und wischen zum nächsten Bild. Deep-Linking bedeutet, dass jedes Bild eine eigene Adresse hat, die geteilt oder verlinkt werden kann; seit PhotoSwipe v5 muss man es allerdings selbst einbauen, weil das eingebaute Hash-Modul entfallen ist. Für SEO zählen diese Adressen nicht, denn Fragmente hinter dem #-Zeichen wertet Google nicht als eigene URLs; für die Bildersuche zählen <img>-Elemente mit aussagekräftigem Alt-Text und beschreibende Dateinamen.

Ein zweites Szenario sind Produktdetailseiten in E-Commerce-nahen TYPO3-Installationen. Ein Möbelhersteller zeigt fünf Perspektiven pro Produkt. PhotoSwipe rendert diese als Galerie mit High-Resolution-Zoom, der auf Desktop per Mausrad und auf Touch per Doppeltipp aktiviert wird. Die Zoom-Qualität hängt direkt von der Auflösung des Quellbilds ab. Wir empfehlen mindestens 2000 Pixel Breite für Produktbilder, die per Zoom betrachtet werden sollen.

Drittes Szenario: Medienarchive und Pressebereiche. Eine Universität stellt 500 Eventfotos bereit. PhotoSwipe rendert die Galerie performant, weil Bilder erst beim Aufblättern geladen werden (Lazy Loading). Die Thumbnail-Übersicht zeigt 50 Bilder pro Seite ohne spürbare Ladezeit.

Technische Architektur hängt PhotoSwipe an die Bildvergrößerung von TYPO3

Die Extension bringt kein eigenes Content-Element mit, sondern schaltet PhotoSwipe für die native Bildvergrößerung von TYPO3 frei. Redakteure pflegen Bilder wie gewohnt in den Bild-Inhaltselementen aus der FAL-Mediathek, setzen „Klick-Vergrößern“ und optionale Bildunterschriften. Beim Rendern hängt die Extension Breite und Höhe jedes Bildes als data-Attribute an den Link; daraus baut die PhotoSwipe-JavaScript-Library die Galerie.

PhotoSwipe selbst hat keine Abhängigkeiten, kein jQuery, kein Framework. Die Library besteht aus einer CSS-Datei und einer JS-Datei. Die TYPO3-Extension registriert beide über die PHP-API des AssetCollectors in ihrer ext_localconf.php, also auf jeder Seite, unabhängig davon, ob sie eine Galerie enthält. Wer unnötige Requests vermeiden will, bindet die Dateien stattdessen mit den Fluid-ViewHelpern f:asset.css und f:asset.script im Galerie-Template ein; dann landen sie nur auf Seiten mit Galerie.

Für responsive Bilder unterstützt die Extension srcset-Attribute: Der Browser lädt je nach Viewport die passende Bildgröße. Das TYPO3-Bild-Processing erzeugt die Varianten automatisch. In Kombination mit WebP-Konvertierung (siehe webp-Extension) erreichen PhotoSwipe-Galerien optimale Ladezeiten.

Häufige Probleme betreffen Konflikte mit anderen Lightbox-Extensions und fehlende Bildgrößen

Das häufigste Problem ist der Konflikt mit einer bereits installierten Lightbox-Extension. Wenn Fancybox und PhotoSwipe gleichzeitig aktiv sind, reagieren beide auf Bild-Klicks und erzeugen doppelte Overlays. Die Lösung: Die alte Lightbox-Extension deaktivieren und deren CSS/JS-Includes aus dem TypoScript-Setup entfernen. Ein grep nach “fancybox” oder “colorbox” in den TypoScript-Dateien zeigt, ob Reste der alten Library noch geladen werden.

Zweites Problem: Fehlende Bildgrößen. PhotoSwipe braucht für den Zoom die tatsächlichen Pixel-Dimensionen des Bildes. Wenn die Extension diese nicht aus den FAL-Metadaten lesen kann, funktioniert der Zoom nicht oder springt auf eine falsche Größe. Die Lösung: Die FAL-Metadaten aller Galerie-Bilder prüfen. TYPO3 liest width und height beim Upload automatisch aus, aber importierte oder per CLI eingefügte Bilder haben manchmal leere Metadaten.

PhotoSwipe v5 läuft unter TYPO3 v12 und v13 ohne Template-Update

Die aktuelle PhotoSwipe-Library ist in Version 5. Die TYPO3-Extension wurde für verschiedene TYPO3-Versionen angepasst und läuft unter v12 stabil. Für TYPO3 v13 ist kein Template-Update nötig, denn Version 2.0.10 der Extension unterstützt v12.4 und v13 gleichermaßen. Gosign aktualisiert bei TYPO3-Upgrades alle Frontend-Extensions inklusive Lightbox und prüft, ob die Touch-Gesten auf aktuellen iOS- und Android-Versionen korrekt funktionieren.