Anleitung für Template-Overrides

Dieses Dokument erklärt, wie Sie die vom ADP Car Market Hub-Plugin verwendeten PHP-Templates sicher anpassen können, indem Sie Override-Dateien in Ihrem Theme erstellen, und wie Sie diese Overrides bei Plugin-Updates wartbar halten.

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie dieses Dokument, wenn Sie:

• Ein Entwickler sind, der die HTML-Struktur des Fahrzeug-Archivs, der einzelnen Fahrzeug-Detailseite oder der Vergleichsseite über das hinaus anpassen muss, was die Design-Einstellungen und Custom CSS erlauben.
• Ein benutzerdefiniertes Theme pflegen und Fahrzeugseiten nahtlos in die eigene HTML-Struktur des Themes integrieren möchten.
• Eine Website nach einem Plugin-Update überprüfen, um festzustellen, ob bestehende Overrides noch kompatibel sind.

Diese Anleitung richtet sich an PHP-Entwickler, die mit der WordPress-Theme-Entwicklung vertraut sind. Wenn Sie nur Farben, Schriftarten oder Abstände ändern müssen, verwenden Sie stattdessen Car Market Hub → Design oder das Feld für Custom CSS – ein Template-Override ist dafür nicht erforderlich. Siehe Anleitung für Custom CSS.

Übersicht

Das Plugin stellt Fallback-PHP-Templates für Fahrzeugseiten in seinem Verzeichnis templates/ bereit. WordPress sucht Templates in einer bestimmten Reihenfolge: Aktive Theme-Dateien werden vor den Plugin-Dateien geprüft. Das Plugin nutzt diesen Mechanismus gezielt über locate_template():

1. WordPress prüft das aktive Theme-Verzeichnis auf eine Datei mit demselben Namen.
2. Falls vorhanden, wird diese Theme-Datei verwendet.
3. Falls nicht vorhanden, wird das eigene Template des Plugins als Fallback verwendet.

Das bedeutet, dass Sie jedes der Front-End-Templates des Plugins überschreiben können, indem Sie eine Datei mit demselben Namen im Stammverzeichnis Ihres Themes ablegen. Die Plugin-Datei wird dabei niemals verändert und bleibt bei Updates vor Ihren Anpassungen geschützt. Ihre Override-Datei verbleibt im Theme, das unter Ihrer eigenen Versionskontrolle steht.

Für Overrides verfügbare Templates

Die folgenden Template-Dateien werden über locate_template() aufgelöst und können überschrieben werden:

Die Vergleichsseite (page-as24ci_compare.php) und das Suchfilter-Partial (parts/search-filter.php) werden direkt vom Plugin geladen und nicht über locate_template() aufgelöst. Sie können mit dieser Methode nicht überschrieben werden. Überprüfen Sie dieses Verhalten in der aktuellen Plugin-Version, bevor Sie sich darauf verlassen.

Voraussetzungen

• Zugriff auf die Dateien des aktiven Themes (über FTP, SSH oder den WordPress-Datei-Editor).
• Ein Child-Theme wird dringend empfohlen, wenn Sie ein kommerzielles oder Parent-Theme verwenden. Wenn Sie Override-Dateien in einem Parent-Theme ablegen, gehen diese bei einer Aktualisierung des Parent-Themes verloren.
• Vertrautheit mit PHP und WordPress-Template-Tags (get_header(), get_footer(), the_title() und ähnlichen).

Schritt-für-Schritt-Anleitung

Erstellen eines Template-Overrides

1. Suchen Sie die Quelldatei. Finden Sie das Template, das Sie anpassen möchten, im Plugin-Verzeichnis unter wp-content/plugins/adp-car-market-hub/templates/. Zum Beispiel archive-as24ci_car.php.
2. Kopieren Sie die Datei — nicht verschieben. Kopieren Sie die Datei in das Stammverzeichnis Ihres (Child-)Themes. Der Dateiname muss identisch sein: - Für das Archiv: wp-content/themes/your-theme/archive-as24ci_car.php - Für die Einzelansicht: wp-content/themes/your-theme/single-as24ci_car.php
3. Nehmen Sie Ihre Änderungen in der Theme-Kopie vor. Bearbeiten Sie die Kopie in Ihrem Theme. Die Originaldatei des Plugins bleibt unberührt.
4. Testen Sie im Frontend. Rufen Sie ein Fahrzeug-Archiv oder eine Fahrzeug-Detailseite auf und überprüfen Sie, ob Ihre Änderungen angewendet werden.

Überprüfen, welches Template aktiv ist

Die WordPress-Seite Website-Zustand und Query-Monitor-Plugins (z. B. Query Monitor) können anzeigen, welche Template-Datei für eine bestimmte Anfrage verwendet wird. Alternativ können Sie einen temporären Kommentar am Anfang Ihrer Override-Datei einfügen und den Quelltext der Seite überprüfen, um sicherzustellen, dass die Datei geladen wird.

Kompatibilität nach Plugin-Updates wahren

Wenn das Plugin aktualisiert wird, können sich die mitgelieferten Templates in templates/ ändern. Ihre Override-Datei verbleibt im Theme und wird weiterhin verwendet – wenn sich jedoch die Template-Logik des Plugins geändert hat, ist Ihr Override möglicherweise veraltet.

Nach jedem Plugin-Update:

1. Vergleichen Sie Ihre Override-Datei mit der entsprechenden Datei im aktualisierten Plugin-Verzeichnis. Ein Diff-Tool oder ein Code-Editor mit Dateivergleich kann hierbei hilfreich sein.
2. Führen Sie alle relevanten Änderungen aus der neuen Version des Plugins in Ihr Override zusammen (Merge).
3. Testen Sie die Fahrzeugseiten nach dem Zusammenführen im Frontend.

Wenn Sie Overrides minimal halten – also nur die Abschnitte enthalten, die Sie tatsächlich ändern müssen –, verringert sich der Aufwand beim Zusammenführen von Updates.

Konfigurationsreferenz

Es gibt kein Einstellungsfeld im Plugin, das Template-Overrides direkt steuert. Die Auflösungslogik ist Teil des WordPress-Hook-Systems und kann im Plugin-Admin-Bereich nicht geändert werden.

Die Design-Einstellungen unter Car Market Hub → Design gelten auch dann, wenn ein Template-Override verwendet wird, da das dynamische CSS unabhängig davon, welches Template ausgeliefert wird, über wp_head ausgegeben wird.

Betriebliche Hinweise

• Child-Theme-Anforderung. Wenn Sie ein kommerzielles oder Parent-Theme verwenden, erstellen Sie immer ein Child-Theme, bevor Sie Override-Dateien hinzufügen. Dateien, die direkt zu einem Parent-Theme hinzugefügt werden, werden bei Theme-Updates gelöscht.
• Das Override muss get_header() und get_footer() aufrufen. Die eigenen Templates des Plugins rufen beide auf. Wenn Ihr Override diese weglässt, wird die Seite ohne die Navigation und den Footer des Themes gerendert. Dies ist fast nie erwünscht.
• Plugin-Namespace beibehalten. Die Template-Dateien des Plugins deklarieren namespace AS24CI; und verweisen auf interne Konstanten wie CPT::POST_TYPE und Options::DESIGN_SINGLE_LAYOUT. Wenn Ihr Override eine dieser Konstanten verwendet, behalten Sie die Namespace-Deklaration bei oder verwenden Sie vollqualifizierte Klassennamen.
• Shortcode-Rendermodus. Das Archiv-Template unterstützt zwei Rendermodi, die durch die globale Variable $as24ci_render_mode gesteuert werden: 'template' (wenn es als CPT-Archivseite bereitgestellt wird) und 'shortcode' (wenn es durch den Shortcode [as24ci_archive] eingebunden wird). Das Template lässt get_header() und get_footer() im Shortcode-Modus weg. Ihr Override sollte dieses Verhalten replizieren, wenn der Shortcode neben dem Archiv-Template korrekt funktionieren soll.
• Stabilität der CSS-Klassen. Das CSS des Plugins hängt von Klassennamen im Template-HTML ab (z. B. .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). Wenn Sie diese Klassen in Ihrem Override entfernen oder umbenennen, funktionieren das Stylesheet des Plugins und die Design-Einstellungen für diese Elemente nicht mehr. Ändern Sie Klassennamen nur, wenn Sie auch das entsprechende CSS im Feld für Custom CSS oder im Stylesheet Ihres Themes aktualisieren.
• alignfull-Klasse. Das Plugin fügt die Klasse alignfull zum Wrapper .as24ci-page hinzu, damit Block-Themes diesen auf die volle Breite ausdehnen. Wenn Sie diese Klasse in Ihrem Override entfernen, wird das Full-Width-Verhalten von Block-Themes nicht angewendet.
• PHP-Version und WordPress-Versionsanforderungen. Die Templates des Plugins verwenden PHP-Funktionen, die mit den angegebenen Anforderungen des Plugins übereinstimmen. Siehe PHP- und Datenbank-Anforderungen.

Fehlerbehebung

Verwandte Dokumente

• Theme-Integration
• Anleitung für Custom CSS
• Page-Builder-Integration
• Referenz für Design & Styles
• PHP- und Datenbank-Anforderungen