Anleitung für Template-Overrides

Dieses Dokument erklärt, wie Sie die vom ADP Car Market Hub-Plugin verwendeten PHP-Templates sicher anpassen, indem Sie Override-Dateien in Ihrem Theme erstellen, und wie Sie diese Overrides über Plugin-Updates hinweg 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 ändern muss, was die Design-Einstellungen und das benutzerdefinierte CSS zulassen.
• 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 benutzerdefiniertes CSS – es ist kein Template-Override erforderlich. Siehe Anleitung für benutzerdefiniertes 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 Plugin-Dateien geprüft. Das Plugin nutzt diesen Mechanismus bewusst über locate_template():

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

Das bedeutet, dass Sie jedes der Frontend-Templates des Plugins überschreiben können, indem Sie eine Datei mit demselben Namen im Stammverzeichnis Ihres Themes ablegen. Die Plugin-Datei wird niemals verändert und bleibt bei Updates von Ihren Anpassungen unberührt. 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

Einen Template-Override erstellen

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. Im Frontend testen. Rufen Sie ein Fahrzeug-Archiv oder eine einzelne Fahrzeugseite 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 (zum Beispiel 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.

Kompatibel bleiben nach Plugin-Updates

Wenn das Plugin aktualisiert wird, können sich die mitgelieferten Templates in templates/ ändern. Ihre Override-Datei verbleibt im Theme und wird weiterhin verwendet – aber wenn sich 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 helfen.
2. Führen Sie alle relevanten Änderungen aus der neuen Version des Plugins in Ihren Override zusammen.
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 Plugin-Einstellungsfeld, das Template-Overrides direkt steuert. Die Auflösungslogik ist Teil des WordPress-Hook-Systems und kann nicht über den Plugin-Adminbereich 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, welche Template-Datei 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.
• Der 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. Das 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 geben Sie die Klassennamen vollständig qualifiziert an.
• Shortcode-Render-Modus. Das Archiv-Template unterstützt zwei Render-Modi, die durch die globale Variable $as24ci_render_mode gesteuert werden: 'template' (wenn als CPT-Archivseite bereitgestellt) und 'shortcode' (wenn durch den Shortcode [as24ci_archive] eingebunden). Das Template lässt get_header() und get_footer() im Shortcode-Modus weg. Ihr Override sollte dieses Verhalten replizieren, wenn Sie möchten, dass der Shortcode korrekt neben dem Archiv-Template funktioniert.
• Stabilität der CSS-Klassen. Das CSS des Plugins hängt von Klassennamen im Template-HTML ab (zum Beispiel .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 benutzerdefiniertes CSS oder im Stylesheet Ihres Themes aktualisieren.
• alignfull-Klasse. Das Plugin fügt dem Wrapper .as24ci-page die Klasse alignfull hinzu, damit Block-Themes ihn auf die volle Breite ausdehnen. Wenn Sie diese Klasse in Ihrem Override entfernen, wird das Verhalten für die volle Breite bei 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 benutzerdefiniertes CSS
• Page-Builder-Integration
• Referenz für Design & Styles
• PHP- und Datenbank-Anforderungen