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ässige WordPress-Template-Hierarchie vom Theme überschrieben werden können und welche direkt durch 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.

Für die Post-Types und Taxonomien, die diese Templates rendern, siehe Custom Post Types und Taxonomien. Für die Shortcodes, die Template-Teile direkt laden, siehe Shortcodes für Entwickler.

Übersicht

Das Plugin liefert seine Templates im Ordner templates/ des Plugins aus. Zwei Mechanismen stellen diese 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, damit ein aktives Theme oder Child-Theme seine 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-Teilelement 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-Archivliste.
• 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].

Teilelemente (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 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 umgibt.
2. Verwenden Sie die vom Plugin bereitgestellten Action- und Filter-Hooks (siehe Hooks und Filter, Aktionen-Referenz, Filter-Referenz), 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 synchron 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 nun Ihre Datei ü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ässig /cars/) neu, um Ihre Version zu sehen.

Vergleichsseite oder Suchfilter-Formular anpassen

1. Betten Sie entweder den entsprechenden Shortcode in ein benutzerdefiniertes Seitentemplate oder Block-Layout in Ihrem Theme ein, oder forken Sie das zugrunde liegende Template in Ihr Theme und laden Sie es aus Ihrem eigenen Template.
2. Stellen Sie sicher, dass alle benötigten Plugin-Assets (CSS/JS, siehe Frontend Assets) weiterhin auf Ihrer benutzerdefinierten Seite geladen werden.

Betriebliche Hinweise

• Verwenden Sie ein Child-Theme. Legen Sie Overrides in einem Child-Theme ab, 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 Einzelansichts- und Archivseiten anordnet und über die Admin-UI des Plugins konfiguriert wird. Wenn Sie das Einzelansichts- oder Archiv-Template vollständig ersetzen, umgehen Sie auch den Layout-Manager. Verwenden Sie gezielte Hook-basierte Anpassungen, 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 durch das Plugin-Template und nicht durch single_template / archive_template gerendert wird.
• 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.
• Asset-Einreihung. Die mit dem Plugin ausgelieferten Front-End-CSS- und JavaScript-Dateien werden bedingt basierend auf der aktuellen Seite (Einzelansicht, Archiv, Shortcode-Nutzung) geladen. Wenn Sie ein benutzerdefiniertes Wrapper-Template erstellen, das nicht den Standardbedingungen entspricht, werden die relevanten Plugin-Assets möglicherweise nicht automatisch geladen.
• Ü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 allfällige Objekt- oder Seitencaches.
• Die Einzelansicht rendert das klassische Layout (oder umgekehrt). Das Layout der Einzelansicht wird in den Design-Einstellungen des Plugins in der Admin-UI ausgewählt. Ändern Sie es dort und nicht über das Theme.
• Die Vergleichsseite zeigt nichts an oder liefert einen 404-Fehler. Stellen Sie sicher, dass die Vergleichsseite noch existiert, den Shortcode [as24ci_compare] enthält und veröffentlicht ist. Überprüfen Sie, ob die Vergleichsfunktion in der Admin-UI 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 geladen 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 und Taxonomien
• Shortcodes für Entwickler
• Frontend Assets
• Hooks und Filter
• Filter-Referenz