PhotoSwipe for 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 vollständige Bildergalerie mit Pinch-to-Zoom, Swipe-Navigation, Deep-Linking 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.

Typical use cases 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 URL hat, die geteilt oder verlinkt werden kann. Das ist für SEO relevant, weil Google die Bilder über die Deep-Link-URLs indexieren kann.

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.

Technical architecture bindet PhotoSwipe als TYPO3 Content Element ein

Die Extension registriert ein eigenes Content-Element im TYPO3-Backend. Redakteure wählen Bilder aus der FAL-Mediathek, definieren die Sortierung und setzen optionale Bildunterschriften. Das Rendering übernehmen Fluid-Templates, die die PhotoSwipe-JavaScript-Library initialisieren und die Bild-URLs als JSON-Array übergeben.

PhotoSwipe selbst hat keine Abhängigkeiten, kein jQuery, kein Framework. Die Library besteht aus einer CSS-Datei und einer JS-Datei. Die TYPO3-Extension lädt beide über TypoScript-AssetCollector, sodass sie nur auf Seiten eingebunden werden, die tatsächlich eine Galerie enthalten. Das vermeidet unnötige Requests auf Seiten ohne Galerie.

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

Common problems involve Konflikte mit anderen Lightbox-Extensions und fehlende Bildgrössen

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össen. 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össe. 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, die v13-Kompatibilität requires ein 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 ein Update der Fluid-Templates und der TypoScript-Konfiguration nötig, weil v13 den AssetCollector-Workflow leicht verändert hat. 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.