Dokumentation · Technische Dokumentation

Template-Overrides

Dieses Dokument erklärt, wie Sie die im ADP Car Market Hub-Plugin mitgelieferten Front-End-Templates über ein (Child-)Theme überschreiben, damit Aktualisierungen Ihre Anpassungen nicht überschreiben.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie:

Das Markup, das Layout oder die Reihenfolge der Felder auf der Fahrzeug-Detailseite oder dem Fahrzeug-Archiv anpassen möchten, ohne die Quelldateien des Plugins zu verändern.
Theme-spezifische Wrapper, Sidebars oder Hooks auf den Seiten des Plugins anwenden möchten.
Bestehende Anpassungen in ein Child-Theme migrieren möchten, um sie updatesicher zu machen.

Für den zugrunde liegenden Template-Ladevorgang siehe Frontend Template System. Für template-basierte Shortcodes siehe Shortcodes.

Übersicht

Das Plugin rendert die Fahrzeug-Detailseiten und das Fahrzeug-Archiv über zwei WordPress-Filter:

single_template — ersetzt durch single-as24ci_car.php (Theme-Override) oder die im Plugin mitgelieferte Datei.
archive_template — ersetzt durch archive-as24ci_car.php (Theme-Override) oder die im Plugin mitgelieferte Datei.

Für jeden Filter ruft das Plugin zuerst locate_template() auf. Wenn das aktive Theme (oder sein Child-Theme) eine Datei mit dem erwarteten Namen bereitstellt, gewinnt diese Datei. Andernfalls greift das Plugin auf die Datei zurück, die in seinem eigenen Verzeichnis templates/ ausgeliefert wird.

Dies macht Overrides einfach: Legen Sie eine korrekt benannte Datei in Ihrem Theme ab, und WordPress lädt diese anstelle der mitgelieferten Version.

Anforderungen oder Voraussetzungen

Ein Child-Theme wird dringend empfohlen, damit Theme-Updates Ihre Overrides nicht überschreiben.
Vertrautheit mit den mitgelieferten Template-Dateien. Diese befinden sich im Namespace AS24CI und basieren auf Plugin-Klassen wie Archive_Filters, Field_Mapping, Schema, Options und Locations.
Lesezugriff auf das Verzeichnis templates/ des Plugins, um das aktuelle mitgelieferte Markup als Ausgangspunkt zu kopieren.

Schritt-für-Schritt-Anleitung

Identifizieren Sie das Template, das Sie überschreiben möchten: - Fahrzeug-Detailseite → single-as24ci_car.php. - Fahrzeug-Archivseite → archive-as24ci_car.php.
Kopieren Sie die mitgelieferte Datei aus dem Verzeichnis templates/ des Plugins unter demselben Dateinamen in das Stammverzeichnis Ihres (Child-)Themes.
Bearbeiten Sie die Kopie in Ihrem Theme. Behalten Sie die vorhandenen Klassenreferenzen und Datenabfragen bei, es sei denn, Sie sind sich des Ersatzes sicher.
Leeren Sie alle Full-Page- oder Template-Caches.
Laden Sie die entsprechende Seite im Front-End neu und überprüfen Sie, ob das Override geladen wird (z. B. indem Sie den Quelltext der Seite nach einem von Ihnen hinzugefügten Kommentar durchsuchen).

Speicherorte für Overrides

Das Plugin verwendet locate_template() mit dem reinen Dateinamen. Das bedeutet, dass WordPress an folgenden Orten sucht:

Im Stammverzeichnis des aktiven Child-Themes.
Im Stammverzeichnis des aktiven Parent-Themes.

Unterverzeichnis-Layouts innerhalb eines Themes (z. B. <theme>/templates/single-as24ci_car.php) werden vom Filter des Plugins nicht durchsucht. Platzieren Sie Override-Dateien mit dem exakten Dateinamen im Stammverzeichnis des Themes.

Was Sie überschreiben können

single-as24ci_car.php — die gesamte Fahrzeug-Detailseite. Der mitgelieferte Wrapper ist absichtlich schlank gehalten; das eigentliche Layout befindet sich in single-as24ci_car-classic.php. Wenn Sie den Wrapper überschreiben, übernehmen Sie die volle Verantwortung für die Auswahl und Einbindung eines Layouts.
archive-as24ci_car.php — die gesamte Fahrzeug-Archivseite. Dies ist auch die Datei, die der Shortcode [as24ci_archive] einbindet (siehe Einschränkungen unten).

Was nicht direkt überschreibbar ist

Template-Teile (z. B. templates/parts/search-filter.php) werden mit include aus absoluten Plugin-Pfaden geladen und durchlaufen nicht locate_template(). Um diese anzupassen, überschreiben Sie das übergeordnete Template, das sie einbindet, und replizieren Sie die erforderliche Ausgabe, oder nutzen Sie die verfügbaren Hooks und Filter des Plugins.
Shortcode-Templates — [as24ci_archive], [as24ci_compare] und [as24ci_search_filter] binden immer die mitgelieferten Dateien des Plugins ein (archive-as24ci_car.php, page-as24ci_compare.php, parts/search-filter.php). Ein Theme-Override von archive-as24ci_car.php wirkt sich daher auch auf den Shortcode [as24ci_archive] aus, aber die Templates für den Vergleich und den Suchfilter können nicht über locate_template() überschrieben werden.
Plugin-CSS/JS, von dem die Templates abhängen. Überschreiben Sie das Styling über das Stylesheet Ihres Themes, anstatt die eingereihten Assets des Plugins zu entfernen.

Betriebliche Hinweise

Überprüfen Sie bei einem Upgrade des Plugins das Changelog auf Änderungen an den mitgelieferten Templates. Wenn das Plugin Daten hinzufügt oder entfernt, die das Template rendert, muss Ihr Override möglicherweise entsprechend aktualisiert werden.
Vermeiden Sie es, partielle Overrides mit Code zu mischen, der die Struktur der mitgelieferten Datei voraussetzt. Halten Sie das Override entweder nah am Original oder dokumentieren Sie die Abweichung innerhalb der Datei.
Theme-Overrides sind von automatischen Plugin-Updates nicht betroffen, da WordPress nur Dateien innerhalb des Plugin-Verzeichnisses aktualisiert.
Overrides gelten sowohl für angemeldete Administratoren als auch für Besucher. Es gibt im Plugin keinen Override-Mechanismus pro Benutzerrolle.
Overrides können die Post-Type- oder Berechtigungsprüfungen, die die Filter anwenden, nicht umgehen: Das Override wird nur bei echten Single- oder Archiv-Anfragen für as24ci_car geladen.

Fehlerbehebung

Override-Datei wird ignoriert — Stellen Sie sicher, dass sich die Datei im Stammverzeichnis des aktiven Themes befindet und exakt den Dateinamen verwendet (single-as24ci_car.php oder archive-as24ci_car.php). Suchen Sie nach Tippfehlern oder prüfen Sie, ob ein Parent-Theme die Datei bereits bereitstellt.
Fatal Error nach Override — Die mitgelieferten Templates verwenden den Namespace AS24CI und verweisen auf Plugin-Klassen. Wenn Sie nur einen Teil der Datei kopiert haben, stellen Sie die Namespace-Deklaration und den Schutz durch defined( 'ABSPATH' ) wieder her und lassen Sie die Abfragen für Field_Mapping / Archive_Filters intakt.
Override erscheint im CPT-Archiv, aber nicht im Shortcode — Beide Wege laden archive-as24ci_car.php aus dem Verzeichnis templates/ des Plugins; der Shortcode verwendet locate_template() nicht. Überprüfen Sie Ihren Override-Pfad und stellen Sie sicher, dass kein Caching-Plugin eine ältere Version der Seite ausliefert.
Layout sieht nach dem Override ungestylt aus — Das mitgelieferte CSS erwartet bestimmte Klassennamen. Behalten Sie diese Klassennamen entweder in Ihrem Override bei oder erweitern Sie das Theme-Stylesheet, um das neue Markup abzudecken.