Gallery for TYPO3

Why sf_filecollection_gallery solves image galleries in TYPO3 the right way

Image galleries are among the most common requirements on corporate websites - product photos, team pictures, event documentation, reference projects. TYPO3 itself does not include a native gallery element. The standard content element “Images” shows images stacked or in columns but without lightbox, without filtering and without flexible layout options. sf_filecollection_gallery fills this gap by using TYPO3 file collections as a data source for galleries, providing pagination, nested galleries and links for a lightbox.

The decisive advantage over other gallery extensions: editors work with the FAL system they already know. Images are organized in file collections, and the gallery automatically displays all images from the assigned collection. Adding new images means: drag image into the collection, done.

Typical use cases

Reference projects and portfolios. An architecture agency shows 15 to 40 images per project page in a gallery. The editor maintains one file collection per project. sf_filecollection_gallery renders the gallery as a grid with lightbox. Clicking an image opens the full view with navigation to the next and previous image. If enabled, the extension shows the description from the FAL metadata as a caption and sets title and alt text as image attributes.

Event documentation and press photography. A trade show organizer documents each event with 50 to 200 photos. Images are batch-uploaded into a file collection. sf_filecollection_gallery automatically generates thumbnails and spreads large galleries across several pages with pagination.

Product catalogs with visual presentation. A furniture manufacturer shows an ambiance gallery per product category. Through multiple file collections (one per category) and the nested view with one preview image per collection, visitors can switch between galleries.

Technical architecture

sf_filecollection_gallery is an Extbase extension that integrates as a TYPO3 plugin into content elements. The data source is TYPO3 file collections from the File Abstraction Layer (FAL).

The architecture is structured in three layers:

• Data source: the extension reads file collections through the TYPO3 FAL API. Supported are static collections (manually assigned files), folder-based collections (all files in a folder) and category-based collections.
• Rendering engine: Fluid templates control the output. The extension ships templates for image lists and nested galleries, each with pagination. All templates are overridable - through standard TYPO3 mechanisms (TypoScript template paths), custom Fluid templates can be integrated.
• Lightbox integration: sf_filecollection_gallery puts a link with a configurable class for a lightbox on every image. The library itself, such as Fancybox, PhotoSwipe or Lightcase, comes from the sitepackage or another extension. Gosign recommends PhotoSwipe due to better touch support and no jQuery dependency.

Lazy loading can be added in a custom template: images below the visible area are then only loaded when the user scrolls. This uses the native loading="lazy" attribute and optionally Intersection Observer for older browsers.

Dependencies: TYPO3 Core (v9.5), FAL. Lightbox libraries are included through the project’s own asset pipeline. An advantage of the file collection architecture: images can appear in multiple galleries simultaneously without being duplicated. A reference to the same FAL object in different collections suffices. This saves storage space and ensures metadata (alt text, title, copyright) is centrally maintained.

Common problems and solutions

Gallery shows no images despite a filled file collection. Cause is frequently an incorrect storage configuration. The file collection references a storage the frontend cannot access (e.g. a non-public storage or a storage with an incorrect base URL). Solution: check in the TYPO3 backend under File List whether images reside in the correct storage and whether the storage is configured as “public”. Additionally, the correct file collection must be selected in the plugin content element.

Lightbox does not work, images open as new page. The lightbox JavaScript library is not loaded. This is frequently caused by a missing TypoScript include or a conflict with another JavaScript library on the page. Solution: check in the browser dev tools whether the lightbox JS file is loaded and whether JavaScript errors appear in the console. With jQuery-based lightboxes (Fancybox), a jQuery version conflict may be the cause.

Loading time too high with large galleries. A gallery with 100+ images in high resolution can load slowly because thumbnails are not sufficiently compressed. Solution: configure TYPO3 Image Processing to generate thumbnails at fixed dimensions (e.g. 400x300px) and optimized quality (75-80%). Additionally, enable WebP format through the TYPO3 image processing configuration.

Migration and version compatibility

The last version of sf_filecollection_gallery is 1.5.0 from 27 March 2019 for TYPO3 9.5; it brought breaking changes itself, and no release has followed since. It is continued as filecollection_gallery by Sven Wappler for TYPO3 v12, v13 and v14, with an upgrade wizard for existing plugins.

For those migrating from an older gallery extension (e.g. ws_flexslider as a gallery substitute or custom gallery plugins), only the data source needs to change: organize images in file collections and place the sf_filecollection_gallery plugin on the pages. The images themselves remain in FAL and do not need to be moved.

During a TYPO3 upgrade from v10 to v12, the lightbox configuration should be reviewed. Fancybox 2 is no longer compatible with current jQuery versions. Gosign recommends switching to PhotoSwipe, which works without jQuery and delivers better performance on mobile devices. PhotoSwipe also supports touch gestures (pinch-to-zoom, swipe) that meet user expectations on smartphone screens. The migration from Fancybox to PhotoSwipe typically requires 4 to 8 hours: new JavaScript initialization, adapted lightbox template and CSS fine-tuning for transition animations.