Dokumentation · Integrationshandbuch

Page Builder Integration

Dieses Dokument erklärt, wie Sie das ADP Car Market Hub-Plugin in Page-Builder-Workflows verwenden, wie Sie Shortcodes auf Seiten platzieren, die mit einem beliebigen Seiteneditor erstellt wurden, und was nach der Platzierung im Frontend zu überprüfen ist.

Wann dieses Dokument zu verwenden ist

Verwenden Sie dieses Dokument, wenn Sie:

Fahrzeuglisten, Suchfilter oder das Vergleichstool auf Seiten einbetten, die mit einem Page Builder wie Elementor, WPBakery, Divi, Beaver Builder oder dem WordPress Block-Editor (Gutenberg) erstellt wurden.
Eine benutzerdefinierte Startseite oder Landingpage erstellen, die eine gefilterte Teilmenge des Fahrzeugbestands anzeigen soll.
Einen eigenständigen Suchfilter auf einer Seite platzieren, damit Besucher mit dem Filtern beginnen können, bevor sie zur Ergebnisseite navigieren.
Probleme diagnostizieren, bei denen Plugin-Assets auf einer Page-Builder-Seite nicht korrekt geladen werden.

Die Zielgruppe ist ein WordPress-Administrator oder Website-Ersteller. Für die grundlegende Platzierung von Shortcodes sind keine PHP- oder CSS-Kenntnisse erforderlich.

Übersicht

Das Plugin stellt drei Frontend-Shortcodes zur Verfügung, die Sie auf jeder WordPress-Seite platzieren können, auch auf Seiten, die mit Page Buildern von Drittanbietern erstellt wurden:

Shortcode	Was gerendert wird
`[as24ci_archive]`	Vollständige Fahrzeugliste mit Suchfiltern, Sortiersteuerungen, Status-Tabs und Paginierung. Entspricht der Fahrzeug-Archivseite.
`[as24ci_search_filter]`	Eigenständiges Suchfilter-Formular ohne Ergebnisse. Leitet an das Fahrzeug-Archiv oder an eine von Ihnen angegebene Ergebnisseite weiter.
`[as24ci_compare]`	Fahrzeug-Vergleichstabelle. Setzt voraus, dass Fahrzeuge vom Besucher zur Vergleichsliste hinzugefügt wurden.

Zusätzliche Shortcodes sind für sekundäre Funktionen verfügbar:

Shortcode	Was gerendert wird
`[as24ci_favorites]`	Liste der Fahrzeuge, die der Besucher als Favoriten markiert hat.
`[as24ci_location_box post_id=""]`	Händler-Standortkarte für den angegebenen Location-Post.
`[as24ci_hours_box post_id=""]`	Öffnungszeiten-Karte für den angegebenen Location-Post.

Diese Shortcodes funktionieren in jedem Page Builder, der Standard-WordPress-Shortcodes unterstützt. Die Ausgabe ist dieselbe wie auf den entsprechenden vom Plugin verwalteten Seiten.

Voraussetzungen

Vor dem Platzieren von Shortcodes:

Das Plugin ist installiert und aktiviert.
Mindestens ein Fahrzeug wurde importiert (für [as24ci_archive] und [as24ci_search_filter]).
Sprechende Permalinks sind aktiviert (Einstellungen → Permalinks). Ohne sprechende Permalinks wird die URL des Fahrzeug-Archivs möglicherweise nicht korrekt aufgelöst, wenn [as24ci_search_filter] einen Besucher auf die Ergebnisseite weiterleitet.
Wenn Sie den Block-Editor (Gutenberg) verwenden, ist keine zusätzliche Einrichtung erforderlich. Wenn Sie einen Page Builder eines Drittanbieters verwenden, stellen Sie sicher, dass dieser WordPress-Shortcodes beibehält, ohne die eckigen Klammern zu kodieren oder zu maskieren.

Schritt-für-Schritt-Anleitung

Einbetten des Fahrzeug-Archivs auf einer Seite

Erstellen Sie eine neue Seite oder öffnen Sie eine vorhandene Seite in Ihrem Page Builder.
Fügen Sie einen Shortcode-Block hinzu (oder das entsprechende Element in Ihrem Page Builder – Elementor hat ein Shortcode-Widget, WPBakery hat ein Einzelnes Bild → Shortcode-Element, Divi hat ein Code-Modul usw.).
Fügen Sie den Shortcode ein:

   [as24ci_archive]

Um die Liste vorzufiltern – zum Beispiel um nur Elektrofahrzeuge anzuzeigen – verwenden Sie die optionalen Shortcode-Attribute:

   [as24ci_archive fuel="electric" per_page="24"]

Unterstützte Attribute:

Attribut	Werte	Beschreibung
`make`	Beliebiger Marken-Slug (z. B. `bmw`)	Wählt eine Marke vor.
`model`	Beliebiger Modell-Slug (z. B. `3-series`)	Wählt ein Modell vor (zusammen mit `make` verwenden).
`price_min`	Ganzzahl	Minimaler Preisfilter.
`price_max`	Ganzzahl	Maximaler Preisfilter.
`fuel`	Beliebiger Kraftstoffart-Slug	Wählt eine Kraftstoffart vor.
`body`	Beliebiger Karosserieform-Slug	Wählt eine Karosserieform vor.
`order_by`	`price`, `mileage`, `date`	Standard-Sortierfeld.
`order`	`asc`, `desc`	Sortierrichtung. Standard ist `asc`.
`per_page`	`12`, `24`, `48`, `72`, `all`	Ergebnisse pro Seite. Standard ist `24`.

Shortcode-Attribute legen die Standardwerte fest. Besucher können diese weiterhin überschreiben, indem sie mit den Filtern auf der Seite interagieren. URL-Query-Parameter haben immer Vorrang vor Shortcode-Attributen.

Veröffentlichen Sie die Seite oder rufen Sie die Vorschau auf und bestätigen Sie, dass die Fahrzeugliste angezeigt wird.

Einbetten eines eigenständigen Suchfilters

Platzieren Sie [as24ci_search_filter] an einer beliebigen Stelle auf einer Seite – zum Beispiel auf der Startseite –, damit Besucher ihre Kriterien festlegen können, bevor sie zur Ergebnisseite weitergeleitet werden.

[as24ci_search_filter results_url="/cars/"]

Das Attribut results_url gibt an, wohin das Formular gesendet wird. Standardmäßig ist dies die URL des Fahrzeug-Archivs. Setzen Sie es auf die URL einer beliebigen Seite, die [as24ci_archive] enthält.
Wenn das Plugin die Archiv-URL nicht automatisch ermitteln kann und results_url nicht gesetzt ist, fällt das Formular auf /cars/ zurück.

Verwendung der Vergleichsseite als Template

Die Vergleichsseite ist ein spezielles WordPress-Seitentemplate (page-as24ci_compare.php). Das Plugin kann während der Installation automatisch eine Vergleichsseite erstellen. Sie können auch [as24ci_compare] in einem Shortcode-Block auf einer beliebigen regulären Seite platzieren, um die Vergleichstabelle inline einzubetten.

Konfigurationsreferenz

Alle Shortcodes verwenden Einstellungen, die bereits in der Plugin-Administration definiert sind. Es gibt keine separaten Konfigurationsfelder für den Page-Builder-Modus.

Shortcode-Attribut	Woher die zugrunde liegenden Optionen stammen
Welche Filter in `[as24ci_archive]` und `[as24ci_search_filter]` erscheinen	Das aktive Filter-Layout, das im Reiter Filter der Plugin-Administration konfiguriert ist.
Visuelles Design aller Shortcodes	Car Market Hub → Design – Farben, Typografie, Eckenradius usw.
Feature-Flags (Favoriten, Vergleich, Suchauftrag)	Car Market Hub → Einstellungen (und der Setup-Assistent). Wenn eine Funktion deaktiviert ist, rendert der entsprechende Shortcode nichts oder zeigt eine Nachricht an.

Laden von Assets

Das Plugin erkennt mithilfe der WordPress-Funktion has_shortcode(), ob ein Shortcode auf der aktuellen Seite vorhanden ist, und reiht die entsprechenden CSS- und JavaScript-Dateien automatisch in die Warteschlange ein. Sie müssen das Laden von Assets nicht manuell konfigurieren.

Auf Seiten, die [as24ci_archive] oder [as24ci_compare] verwenden, werden die folgenden Stylesheets geladen:

as24ci-archive.css – für [as24ci_archive]
as24ci-compare.css – für [as24ci_compare] und für den Vergleichs-Umschalter auf Archiv- und Einzelseiten
as24ci-search-agent.css – wenn die Suchauftrags-Funktion aktiviert ist

Der dynamische Design-CSS-Block (<style id="as24ci-dynamic-styles">) wird in <head> auf jeder Frontend-Seite ausgegeben, nicht nur auf Plugin-spezifischen Seiten.

Betriebshinweise

Paginierung auf Shortcode-Seiten. Der Shortcode [as24ci_archive] liest die Query-Parameter ?paged= und ?page= für die Paginierung aus. Wenn ein Page Builder oder Theme diese Parameter für eigene Zwecke verwendet, kann es zu einem Konflikt kommen. Testen Sie die Paginierung auf der Seite in ihrem endgültigen Kontext.
Einfache Permalinks. Wenn einfache Permalinks (Query-Strings) aktiviert sind, gibt is_post_type_archive() für das Archiv des Plugins „false“ zurück. Das Plugin fällt auf die Erkennung von has_shortcode() zurück, sodass CSS und JavaScript weiterhin geladen werden. Die results_url für [as24ci_search_filter] wird jedoch möglicherweise nicht korrekt aufgelöst – bevorzugen Sie in der Produktionsumgebung sprechende Permalinks.
Rendern von Page-Builder-Inhalten. Einige Page Builder rendern Shortcodes auf dem Server (Standard-do_shortcode) und andere rendern sie über Ajax oder auf dem Client. Die Shortcodes des Plugins basieren auf dem standardmäßigen serverseitigen Rendern. Wenn ein Page Builder das Rendern auf die Client-Seite verschiebt, erscheint die Ausgabe in der Builder-Vorschau möglicherweise leer, sollte aber im veröffentlichten Frontend korrekt angezeigt werden.
Verschachtelte Shortcodes. Verschachteln Sie Plugin-Shortcodes nicht ineinander. Jeder Shortcode verwaltet sein eigenes WP_Query und seinen globalen Zustand.
Layout in voller Breite. Wie die plugin-eigenen Archiv- und Einzel-Templates umschließt die Shortcode-Ausgabe alles innerhalb von .as24ci-page.alignfull. Bei Block-Themes führt dies dazu, dass sich die Auflistung über die gesamte Breite erstreckt. Wenn der Page Builder die Seite auf einen schmaleren Container beschränkt, wird der Shortcode-Inhalt durch diesen Container begrenzt. Details finden Sie unter Theme-Integration.
Position des Suchfilters. Der Shortcode [as24ci_search_filter] rendert das Filterformular, aber keine Ergebnisliste. Wenn er auf der Startseite platziert wird, sollte die Formularaktion auf eine separate Seite verweisen, die [as24ci_archive] enthält.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Was zu prüfen ist
Shortcode wird als reiner Text gerendert (`[as24ci_archive]`).	Der Page Builder maskiert oder kodiert den Shortcode, anstatt ihn auszuführen.	Verwenden Sie das dedizierte Shortcode-Widget oder den Code-Block des Page Builders anstelle eines einfachen Textblocks.
Archiv-Shortcode zeigt keine Fahrzeuge.	Es wurden noch keine Fahrzeuge importiert oder die Vorfilter-Attribute im Shortcode passen zu keinem Fahrzeug.	Importieren Sie zuerst Fahrzeuge. Überprüfen Sie die Attributwerte mit den tatsächlichen Daten unter Car Market Hub → Fahrzeuge.
CSS wird auf der Shortcode-Seite nicht angewendet.	Der Page Builder entfernt die Plugin-Stylesheets oder verzögert deren Laden.	Überprüfen Sie die Entwicklertools des Browsers → Reiter „Netzwerk“ auf das Stylesheet `as24ci-archive` oder `as24ci-single`. Wenn es fehlt, prüfen Sie, ob der Page Builder eine Option zum Beibehalten von Drittanbieter-Assets hat.
Dynamisches CSS (`as24ci-dynamic-styles`) fehlt.	Ein Caching- oder Optimierungs-Plugin entfernt Inline-`<style>`-Blöcke aus `<head>`.	Schließen Sie `as24ci-dynamic-styles` von der Optimierungsregel aus oder setzen Sie die `as24ci-*`-Handles auf die Whitelist.
Paginierung funktioniert auf der Archiv-Shortcode-Seite nicht.	Der Parameter `?paged=` wird vom Theme oder Page Builder konsumiert oder umgeschrieben.	Testen Sie mit der normalen URL-Navigation. Prüfen Sie, ob das Theme oder der Page Builder Query-Parameter abfängt.
`[as24ci_search_filter]` sendet an die falsche URL.	Das Attribut `results_url` fehlt oder verweist auf eine Seite ohne `[as24ci_archive]`.	Fügen Sie `results_url="/cars/"` (oder den korrekten Pfad) zum Shortcode hinzu.