Dokumentation · Technische Dokumentation

Frontend-Template-System

Dieses Dokument erklärt, wie das ADP Car Market Hub-Plugin Fahrzeugseiten im Frontend rendert, wie seine mitgelieferten Templates mit dem aktiven WordPress-Theme zusammenhängen und welche Erweiterungspunkte für Themes und Shortcodes bereitgestellt werden.

Wann Sie dieses Dokument verwenden sollten

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

Verstehen, welche Datei die einzelne Fahrzeugseite oder das Fahrzeugarchiv rendert.
Entscheiden, ob Sie eine auf Shortcodes basierende Auflistung innerhalb einer regulären Seite verwenden oder sich auf das CPT-Archiv verlassen möchten.
Das Layout über ein Child-Theme erweitern oder überschreiben. Die Mechanismen zum Überschreiben finden Sie unter Template Overrides.

Übersicht

Das Plugin registriert seinen Custom Post Type as24ci_car mit Archiv-Unterstützung und liefert einen kleinen Satz an mitgelieferten Templates im Verzeichnis templates/ des Plugins aus. Zwei WordPress-Filter leiten Anfragen an diese Templates weiter, wenn das aktive Theme keine eigene Version bereitstellt:

single_template — verwendet für is_singular( 'as24ci_car' ).
archive_template — verwendet für is_post_type_archive( 'as24ci_car' ).

Jeder Filter bittet zuerst WordPress, ein Override auf Theme-Ebene (locate_template()) zu finden, und greift nur dann auf die im Plugin mitgelieferte Datei zurück, wenn kein Override existiert.

Mitgelieferte Templates

Die folgenden Dateien befinden sich im Ordner templates/ des Plugins und werden durch die oben genannten Filter (oder durch Shortcodes) geladen:

single-as24ci_car.php — schlanker Wrapper, der das passende Layout für die einzelne Fahrzeugseite basierend auf der Option as24ci_design_single_layout auswählt und die gewählte Layout-Datei einbindet.
single-as24ci_car-classic.php — das aktuelle Layout für die einzelne Fahrzeugseite. Der Wrapper lädt derzeit immer diese Datei; zukünftige Versionen können zusätzliche Layouts hinzufügen. Überprüfen Sie das Verhalten anhand der aktuellen Plugin-Version, bevor Sie kundenorientierte Texte veröffentlichen.
archive-as24ci_car.php — das Fahrzeugarchiv-Layout, das für das CPT-Archiv und für den Shortcode [as24ci_archive] verwendet wird.
parts/search-filter.php — Partial, das von [as24ci_search_filter] gerendert wird, um das eigenständige Suchformular anzuzeigen.
page-as24ci_compare.php — Vergleichsseite, die von [as24ci_compare] gerendert wird.
icons/ — gemeinsam genutzte Inline-SVG-Icon-Helper, die in allen Templates verwendet werden.
css/ und js/ — Assets, von denen die Templates abhängen.

Wie eine Anfrage ein Template erreicht

WordPress analysiert die Anfrage und löst sie auf ein einzelnes Fahrzeug oder das Fahrzeugarchiv auf.
Unmittelbar vor der Ausgabe wendet WordPress den Filter single_template oder archive_template an.
Der Filter-Callback des Plugins: - gibt das ursprüngliche $template zurück, wenn die Anfrage nicht für as24ci_car bestimmt ist; - ruft locate_template( '<template>.php' ) auf, um dem aktiven (Child-)Theme die erste Möglichkeit zum Überschreiben zu geben; - wenn keine Theme-Datei existiert, wird die mitgelieferte Datei aus dem Verzeichnis templates/ des Plugins zurückgegeben; - wenn keines von beiden existiert, wird das ursprüngliche $template zurückgegeben, sodass WordPress auf seine Standardhierarchie zurückgreifen kann.

Die Shortcodes folgen im Prinzip derselben Priorität, rufen jedoch nicht locate_template() auf — sie binden immer die mitgelieferten Archiv- / Vergleichs- / Suchfilter-Dateien des Plugins ein. Siehe Shortcodes und Template Overrides für die Auswirkungen.

Shortcode- und Render-Modus-Integration

Das Plugin stellt ein globales Flag, $as24ci_render_mode, zur Verfügung, das von den Shortcode-Handlern auf 'shortcode' gesetzt wird, während ihr mitgeliefertes Template ausgeführt wird. Bedingter Code in den Templates und in unterstützenden Klassen (z. B. beim Laden von Assets) verwendet dieses Flag, um dieselbe Logik auf Shortcode-basierten Seiten anzuwenden wie auf dem nativen CPT-Archiv.

Der Shortcode [as24ci_archive] ersetzt die globale Abfrage $wp_query während des Renderns des Archiv-Templates durch eine benutzerdefinierte Abfrage und stellt die vorherige Abfrage sowie wp_reset_postdata() anschliessend wieder her, sodass er sicher in eine normale Seite eingebettet werden kann.

Konfigurationsreferenz

Optionsschlüssel	Auswirkung auf das Rendern
`as24ci_design_single_layout`	Wählt das Layout für die einzelne Fahrzeugseite aus. Der aktuelle Wrapper lädt immer die klassische Layout-Datei; diese Option steuert auch layoutabhängige Body-Classes und CSS. Standard ist `'minimal'`.

Layout-, Design- und Funktions-Toggles, die beeinflussen, was innerhalb der Templates gerendert wird (Filterzonen, Favoriten-Feldset, Suchauftrag-Toggle usw.), sind in Options And Settings Storage dokumentiert.

Betriebliche Hinweise

Die Filter-Callbacks des Plugins geben den Pfad der mitgelieferten Datei als String zurück. WordPress bindet die Datei mit seinem Standard-Template-Loader ein, sodass sich globale Variablen wie $post, $wp_query und Body-Classes wie in jedem Theme-Template verhalten.
Mitgelieferte Templates deklarieren namespace AS24CI; und exit, wenn ABSPATH nicht definiert ist, was den Standardschutz von WordPress widerspiegelt.
Template-Dateien verweisen auf Plugin-Klassen wie Archive_Filters, Field_Mapping, Schema, Options und Locations, um ihre Daten zusammenzustellen. Themes, die die Datei überschreiben, müssen diese Referenzen intakt halten (oder den entsprechenden Datenabruf replizieren), um Warnungen wegen nicht definierter Variablen zu vermeiden.
Das Shortcode-basierte Archiv erzwingt ein neues WP_Query aus den Parametern von $_GET via Archive_Filters::build_query_args_from_request(), sodass URL-Filter auf dem CPT-Archiv und auf Shortcode-Seiten identisch funktionieren.

Fehlerbehebung

Das Layout des Plugins erscheint nie — stellen Sie sicher, dass das aktive Theme kein eigenes single-as24ci_car.php oder archive-as24ci_car.php definiert; Theme-Dateien gewinnen immer. Siehe Template Overrides.
Eine Seite mit [as24ci_archive] zeigt den falschen Beitrag an — der Shortcode ersetzt die globale Abfrage während der Ausführung und stellt sie anschliessend wieder her. Wenn eine benutzerdefinierte Theme-Komponente die globale Abfrage liest, bevor der Shortcode verarbeitet wird, spielt die Reihenfolge, in der die Seite Teile des Layouts rendert, eine Rolle; betten Sie den Shortcode im Hauptinhaltsbereich und nicht im Header oder in der Sidebar ein.
Die Seitennummerierung wird innerhalb von [as24ci_archive] auf Seite 1 zurückgesetzt — der Shortcode liest ?paged= und ?page= aus der URL. Stellen Sie sicher, dass Ihre Permalink-Struktur Query-Strings zulässt, oder verwenden Sie einen Permalink, der mit dem Shortcode kompatibel ist.
Asset (CSS/JS) wird auf einer Shortcode-Seite nicht geladen — das Plugin erkennt Shortcodes und das Flag $as24ci_render_mode, um Assets zu laden. Wenn ein Page-Builder die Seitenausgabe zwischenspeichert, leeren Sie diesen Cache nach dem Bearbeiten der Seite manuell, damit der Shortcode beim Einreihen in die Warteschlange erkannt wird.