Dokumentation · Technische Dokumentation

Template-Overrides

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

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

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

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

Übersicht

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

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

Für jeden Filter ruft das Plugin zuerst locate_template() auf. Wenn das aktive Theme (oder dessen 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 verwenden den 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-Einzelansicht → 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-Strukturen 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 Theme-Stammverzeichnis.

Was Sie überschreiben können

single-as24ci_car.php – die gesamte Fahrzeug-Einzelansicht. Der mitgelieferte Wrapper ist bewusst 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 sie 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 im Plugin enthaltenen Dateien 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 in die Warteschlange eingereihten Assets des Plugins zu entfernen.

Betriebshinweise

Überprüfen Sie bei einer Aktualisierung 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 rollenspezifischen Override-Mechanismus.
Overrides können die Post-Type- oder Berechtigungsprüfungen, die die Filter anwenden, nicht umgehen: Das Override wird nur bei echten as24ci_car-Einzelansichts- oder Archiv-Anfragen geladen.

Fehlerbehebung

Override-Datei wird ignoriert – Stellen Sie sicher, dass sich die Datei im Stammverzeichnis des aktiven Themes befindet und exakt so benannt ist (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 Schutzmechanismus defined( 'ABSPATH' ) wieder her und lassen Sie die Abfragen 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 jedoch nicht locate_template(). Ü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.