Template-System und Overrides

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin seine Front-End-Templates lädt und wie ein Theme diese überschreiben kann. Es listet die im Ordner templates/ des Plugins bereitgestellten Dateien auf und erklärt, welche davon über die standardmäßige WordPress-Template-Hierarchie vom Theme überschrieben werden können und welche direkt von Shortcodes geladen werden.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie:

• Das Markup der Fahrzeug-Einzelansicht, des Fahrzeug-Archivs oder der Vergleichsseite über ein Theme oder Child-Theme anpassen möchten.
• Einen kleinen Teilbereich (z. B. das Suchfilter-Formular) ersetzen möchten, ohne das gesamte Template zu forken.
• Verstehen möchten, welche Template-Dateien sicher überschrieben werden können und welche sich zwischen den Versionen ändern.

Informationen zu den Post-Types und Taxonomien, die diese Templates rendern, finden Sie unter Custom Post Types And Taxonomies. Die Shortcodes, die Template-Teile direkt laden, finden Sie unter Shortcodes For Developers.

Übersicht

Das Plugin liefert seine Templates im Ordner templates/ des Plugins aus. Zwei Mechanismen stellen sie bereit:

1. WordPress-Template-Hierarchie-Filter. Das Plugin klinkt sich in single_template und archive_template ein. Für beide Filter ruft es zuerst locate_template() auf, sodass ein aktives Theme oder Child-Theme eine eigene Kopie der Datei bereitstellen kann. Wenn kein Theme-Override gefunden wird, wird das im Plugin enthaltene Template verwendet.
2. Direktes Shortcode-Rendering. Die Shortcodes für die Vergleichsseite ([as24ci_compare]) und den eigenständigen Suchfilter ([as24ci_search_filter]) laden ihre Templates direkt aus dem Ordner templates/ des Plugins. Sie fragen das Theme nicht nach einem Override ab.

Das führt dazu, dass die Fahrzeug-Einzelansicht und das Fahrzeug-Archiv sauber überschrieben werden können, indem eine Datei im aktiven Theme abgelegt wird, während sich die Vergleichsseite und das Suchfilter-Partial nur ändern, wenn Sie deren Ausgabe über einen anderen Mechanismus modifizieren oder filtern.

Im Ordner templates/ enthaltene Dateien

Top-Level-Templates:

• archive-as24ci_car.php — Fahrzeug-Archiv-Auflistung.
• single-as24ci_car.php — Fahrzeug-Einzelansicht (Standard-Layout).
• single-as24ci_car-classic.php — Alternatives "klassisches" Einzelansicht-Layout.
• page-as24ci_compare.php — Vergleichsseite, gerendert durch [as24ci_compare].

Partials und Assets:

• parts/search-filter.php — Das Suchfilter-Formular, gerendert durch [as24ci_search_filter].
• icons/ — SVG-Icon-Definitionen, die von den Templates verwendet werden.
• css/ und js/ — Front-End-Stylesheets und -Skripte, die zusammen mit den Templates ausgeliefert und vom Asset-Loader eingereiht werden (siehe Frontend Assets).

Vom Theme überschreibbare Templates

Diese Dateien werden über die Filter single_template / archive_template geladen und berücksichtigen daher das Theme:

Das Plugin ruft locate_template( '<file-name>.php' ) ohne Unterverzeichnis-Präfix auf, sodass die Override-Datei direkt im Stammverzeichnis des aktiven Themes (oder des Child-Themes) abgelegt werden muss. Wenn locate_template() einen Pfad zurückgibt, verwendet das Plugin diesen; andernfalls greift es auf das mitgelieferte Template zurück.

Nicht über die Theme-Hierarchie geladene Templates

Diese Dateien werden direkt vom Plugin geladen und nicht von locate_template() erfasst:

Um diese anzupassen, haben Sie drei zuverlässige Optionen:

1. Erstellen Sie eine Wrapper-Seite oder ein Template in Ihrem Theme, das den entsprechenden Shortcode aufruft und dessen Ausgabe mit Ihrem eigenen Markup umschließt.
2. Verwenden Sie die vom Plugin bereitgestellten Action- und Filter-Hooks (siehe Hooks And Filters, Actions Reference, Filters Reference), um das Verhalten anstelle des Markups zu ändern.
3. Als letzte Option können Sie die Datei in Ihr Theme forken und aus Ihrem eigenen Template laden; Sie übernehmen dann die Verantwortung dafür, sie mit zukünftigen Plugin-Releases kompatibel zu halten.

Schritt-für-Schritt-Anleitung

Fahrzeug-Einzelansicht überschreiben

1. Kopieren Sie single-as24ci_car.php aus dem Ordner templates/ des Plugins.
2. Fügen Sie die Datei im Stammverzeichnis Ihres aktiven Themes (oder Child-Themes) ein.
3. Bearbeiten Sie die Kopie, um Ihre Änderungen vorzunehmen.
4. Laden Sie eine Fahrzeug-Einzelansicht neu. WordPress lädt Ihre Datei nun über locate_template() anstelle der im Plugin enthaltenen Datei.

Fahrzeug-Archiv überschreiben

1. Kopieren Sie archive-as24ci_car.php aus dem Ordner templates/ des Plugins.
2. Fügen Sie die Datei im Stammverzeichnis Ihres aktiven Themes (oder Child-Themes) ein.
3. Bearbeiten Sie die Kopie. Laden Sie die Archivseite (standardmäßig /cars/) neu, um Ihre Version zu sehen.

Vergleichsseite oder Suchfilter-Formular anpassen

1. Umschließen Sie entweder den entsprechenden Shortcode in einem benutzerdefinierten Seitentemplate oder Block-Layout in Ihrem Theme, oder forken Sie das zugrunde liegende Template in Ihr Theme und laden Sie es aus Ihrem eigenen Template.
2. Stellen Sie sicher, dass alle Plugin-Assets, von denen Sie abhängen (CSS/JS, siehe Frontend Assets), weiterhin auf Ihrer benutzerdefinierten Seite eingereiht werden.

Betriebshinweise

• Nutzen Sie ein Child-Theme. Platzieren Sie Overrides in einem Child-Theme, um zu verhindern, dass sie bei Aktualisierungen des Parent-Themes verloren gehen.
• Zusammenspiel mit dem Layout-Manager. Das Plugin enthält einen Layout-Manager, der Blöcke innerhalb der Fahrzeug-Einzelansicht und der Archivseiten anordnet und über die Admin-Oberfläche des Plugins konfiguriert wird. Wenn Sie das Einzelansichts- oder Archiv-Template vollständig ersetzen, umgehen Sie auch den Layout-Manager. Verwenden Sie selektive, Hook-basierte Modifikationen, wenn Sie dieses Verhalten beibehalten möchten.
• Aktivierung der Vergleichsseite. Die Vergleichsseite wird bei der Aktivierung erstellt. Die Seite selbst enthält lediglich den Shortcode [as24ci_compare], sodass ihr Inhalt vom Plugin-Template gerendert wird und nicht von single_template / archive_template.
• Shortcode auf beliebigen Seiten. Da [as24ci_archive] den Archiv-Renderer wiederverwendet, können Sie die Auflistung in jede beliebige WordPress-Seite oder jedes Block-Layout einbetten, ohne das Archiv-Template überhaupt überschreiben zu müssen.
• Einreihen von Assets. Mit dem Plugin ausgelieferte Front-End-CSS- und JavaScript-Dateien werden bedingt basierend auf der aktuellen Seite (Einzelansicht, Archiv, Shortcode-Nutzung) eingereiht. Wenn Sie ein benutzerdefiniertes Wrapper-Template erstellen, das nicht den Standardbedingungen entspricht, werden die relevanten Plugin-Assets möglicherweise nicht automatisch eingereiht.
• Überprüfen Sie das Verhalten in der aktuellen Plugin-Version, bevor Sie ein benutzerdefiniertes Theme veröffentlichen. Die Template-Struktur und das Block-Markup können sich zwischen den Versionen ändern.

Fehlerbehebung

• Mein Theme-Override wird ignoriert. Stellen Sie sicher, dass der Dateiname exakt übereinstimmt (single-as24ci_car.php, archive-as24ci_car.php) und dass sich die Datei im Stammverzeichnis des aktiven Themes befindet. Leeren Sie jeglichen Objekt- oder Seitencache.
• Die Einzelansicht rendert das klassische Layout (oder umgekehrt). Das Layout der Einzelansicht wird in den Design-Einstellungen des Plugins in der Admin-Oberfläche ausgewählt. Ändern Sie es dort und nicht über das Theme.
• Die Vergleichsseite zeigt nichts an oder führt zu einem 404-Fehler. Stellen Sie sicher, dass die Vergleichsseite noch existiert, den Shortcode [as24ci_compare] enthält und veröffentlicht ist. Vergewissern Sie sich, dass die Vergleichsfunktion in der Admin-Oberfläche des Plugins aktiviert ist.
• Front-End-Skript oder -Style fehlt auf einer benutzerdefinierten Wrapper-Seite. Der Asset-Loader des Plugins orientiert sich an Post-Type-, Archiv- und Shortcode-Erkennung. Verwenden Sie die offiziellen Shortcodes innerhalb Ihres Wrappers, damit die passenden Assets automatisch eingereiht werden.
• Überprüfen Sie das Verhalten in der aktuellen Plugin-Version, bevor Sie eine benutzerdefinierte Integration veröffentlichen. Template-Pfade und Markup können sich zwischen den Versionen weiterentwickeln.

Verwandte Dokumente

• Custom Post Types And Taxonomies
• Shortcodes For Developers
• Frontend Assets
• Hooks And Filters
• Filters Reference