srhinow/contao-page-images-bundle

Set one or more images central per page in Contao CMS. This is a Fork from 'Ruudt/contao-page_images' and updated for >=Contao 5.3 and >=PHP 8.3

3.0.5 2026-05-13 21:57 UTC

Requires

• php: ^8.3
• contao/core-bundle: ^5.3

GPL-3.0-or-later

• Ruud Walraven
• Sven Rhinow

• image
• contao
• pageimage
• backend modul

README

Zentrale Verwaltung von Seitenbildern für Contao CMS. Bilder werden einmalig im Backend konfiguriert und automatisch an Unterseiten vererbt — bis eine Seite eine eigene Zuweisung besitzt oder die Vererbung explizit gesperrt wird.

Fork von Ruudt/contao-page_images, neu geschrieben für Contao 5.3+ und PHP 8.3+.

Anforderungen

Abhängigkeit	Version
PHP	^8.3
Contao Core Bundle	^5.3

Installation

composer require srhinow/contao-page-images-bundle

Nach der Installation die Datenbank-Migration ausführen:

php bin/console contao:migrate

Datenhierarchie

tl_pageimages              Bild-Kategorien (z. B. „Header", „Teaser-Bild")
└── tl_pageimages_items    Konkrete Bildzuweisungen mit Seitenliste
    └── tl_pageimages_pages  Verknüpfungstabelle: Item ↔ Seiten-ID

Backend

Das Bundle fügt unter Inhalte → Seitenbilder (do=page_images) ein Backend-Modul hinzu.

Bild-Kategorien (tl_pageimages)

Jede Kategorie definiert einen „Slot" im Layout, in dem Seitenbilder angezeigt werden.

Feld	Beschreibung
Name	Eindeutiger interner Name der Kategorie (Pflichtfeld)
Bildquellen (multiSRC)	Standard-Bilder für diesen Slot (Fallback, wenn keine Seiten-Zuweisung greift)
Alt-Text (alt)	Standard-Alt-Text für alle Bilder dieser Kategorie
Bildgröße (size)	Contao Image-Size für die Ausgabe

Bildeinträge (tl_pageimages_items)

Kindeinträge einer Kategorie. Jedem Eintrag werden konkrete Seiten zugeordnet.

Feld	Beschreibung
Bildquellen (multiSRC)	Bilder für diesen Eintrag (Pflichtfeld)
Seiten (pages)	Seiten, auf denen dieser Eintrag angezeigt wird (Pflichtfeld, Seitenbaum-Auswahl)
Beschriftung anzeigen (showText)	Checkbox: Klappt das Textfeld auf
Text (text)	Optionaler HTML-Text (TinyMCE-Editor), der zusammen mit dem Bild ausgegeben wird
Vererbung sperren (noInheritance)	Checkbox: Verhindert, dass dieser Eintrag an Unterseiten weitergegeben wird

Vererbungslogik

Beim Rendern des Frontend-Moduls sucht PageImagesService ein Bild für die aktuelle Seite:

1. Prüfe ob ein Eintrag direkt der aktuellen Seite zugeordnet ist.
2. Falls nicht: Gehe zur Elternseite — außer ein Eintrag auf dem Weg hat „Vererbung sperren" aktiviert.
3. Falls kein Eintrag im Seitenbaum gefunden: Nutze das Standard-Bild der Kategorie (tl_pageimages.multiSRC).

Frontend-Modul

Modultyp: page_images — „Seitenbilder" (Gruppe: Seitenbilder)

Feld	Beschreibung
Seitenbilder-Kategorie (pageimages)	Welche Kategorie dargestellt wird (Pflichtfeld, Radio-Auswahl)
Seitenbilder-Template (pageimages_layout)	Template für die Ausgabe (alle Templates mit Präfix pageimages_)
Anzahl der Bilder (image_count)	1 = erstes Bild, 0 = alle, N = die ersten N Bilder
useCaption	Bildunterschrift anzeigen
fullsize	Lightbox-Link aktivieren

Templates

mod_page_images.html.twig

Modul-Wrapper. Rendert das Bild-Template, wenn ein Seitenbild vorhanden ist.

Variable	Typ	Beschreibung
has_pageimage	bool	true wenn ein Bild für die aktuelle Seite gefunden wurde
pageimage	string	Gerendertes HTML des Bild-Templates

pageimages_default.html.twig

Rendert die Bilder mit optionalem Textoverlay. Nutzt die Twig-Funktion contao_figure().

Variable	Typ	Beschreibung
images	array	Array von Bild-Datensätzen (UUID + Größe aus der Kategorie)
text	string	Optionaler Text-Overlay (HTML)
showText	bool	Text-Overlay aktiv?

Eigene Templates müssen mit dem Präfix pageimages_ beginnen, damit sie im Backend-Dropdown erscheinen.

Hook

Der compilePageImages-Hook feuert nach der Bildauflösung und erlaubt projektspezifische Nachbearbeitung:

$GLOBALS['TL_HOOKS']['compilePageImages'][] = [MyClass::class, 'myMethod'];

Signatur: myMethod(Template $template, array $pageImages, ModuleModel $model): void

Benutzerrechte

Zwei Berechtigungsschlüssel werden für Backend-Benutzer und -Gruppen registriert:

Schlüssel	Beschreibung
pageimages_categories	Auf welche Kategorien der Benutzer zugreifen darf
pageimages_categoriesp	Erlaubte Operationen: create, delete

Datenbankstruktur

tl_pageimages

Spalte	Typ	Beschreibung
id	int(10) unsigned PK AI	Primärschlüssel
sorting	int(10) unsigned	Sortierung
tstamp	int(10) unsigned	Zeitstempel letzte Änderung
name	varchar(200)	Kategoriename
alt	varchar(200)	Standard-Alt-Text
size	varchar(64)	Bildgröße-Konfiguration
multiSRC	blob NULL	Standard-Bildquellen (serialisierte UUIDs)

tl_pageimages_items

Spalte	Typ	Beschreibung
id	int(10) unsigned PK AI	Primärschlüssel
pid	int(10) unsigned	Elternkategorie (tl_pageimages.id)
sorting	int(10) unsigned	Sortierung
tstamp	int(10) unsigned	Zeitstempel
multiSRC	blob NULL	Bildquellen (serialisierte UUIDs)
showText	boolean	Text anzeigen
text	blob NULL	Optionaler HTML-Text
noInheritance	char(1)	Vererbung sperren

tl_pageimages_pages

Verknüpfungstabelle: Welche Seiten ein tl_pageimages_items-Eintrag abdeckt.

Spalte	Typ	Beschreibung
id	int(10) unsigned PK AI	Primärschlüssel
pid	int(10) unsigned	Elterneintrag (tl_pageimages_items.id)
sorting	int(10) unsigned	Sortierung
tstamp	int(10) unsigned	Zeitstempel
pageId	int(10) unsigned	Seiten-ID (tl_page.id)

Tests ausführen

vendor/bin/phpunit -c vendor/srhinow/contao-page-images-bundle/phpunit.xml.dist

Changelog

Siehe CHANGELOG.md für die vollständige Versionshistorie.

Lizenz

GPL-3.0-or-later

Autoren

Ruud Walraven (Ursprungsautor)
Sven Rhinow — sr-tag.de
Support: [e-mail]
Quellcode: gitlab.com/srhinow/contao-page-images-bundle