Documentatie · Technische documentatie

Frontend-templatesysteem

Dit document legt uit hoe de ADP Car Market Hub-plugin voertuigpagina's rendert op de frontend, hoe de meegeleverde templates zich verhouden tot het actieve WordPress-thema en welke uitbreidingspunten beschikbaar zijn voor thema's en shortcodes.

Wanneer u dit document moet gebruiken

Lees dit document als u het volgende wilt doen:

Begrijpen welk bestand de individuele voertuigpagina of het voertuigarchief rendert.
Beslissen of u een op shortcodes gebaseerd overzicht binnen een normale pagina wilt gebruiken of wilt vertrouwen op het CPT-archief.
De lay-out uitbreiden of overschrijven vanuit een child-thema. Zie Template Overrides voor de werking van overschrijvingen.

Overzicht

De plugin registreert zijn as24ci_car-posttype met archiefondersteuning en levert een kleine set meegeleverde templates in de map templates/ van de plugin. Twee WordPress-filters routeren verzoeken naar deze templates wanneer het actieve thema geen eigen versie heeft:

single_template — gebruikt voor is_singular( 'as24ci_car' ).
archive_template — gebruikt voor is_post_type_archive( 'as24ci_car' ).

Elk filter vraagt eerst aan WordPress om een overschrijving op themaniveau te zoeken (locate_template()), en valt pas terug op het meegeleverde bestand van de plugin als er geen overschrijving bestaat.

Meegeleverde templates

De volgende bestanden bevinden zich in de map templates/ van de plugin en worden geladen door de bovenstaande filters (of door shortcodes):

single-as24ci_car.php — dunne wrapper die de juiste lay-out voor een individueel voertuig selecteert op basis van de optie as24ci_design_single_layout en het gekozen lay-outbestand invoegt.
single-as24ci_car-classic.php — de huidige lay-out voor een individueel voertuig. De wrapper laadt momenteel altijd dit bestand; toekomstige versies kunnen extra lay-outs toevoegen. Controleer de werking met de huidige plugin-versie voordat u teksten voor klanten publiceert.
archive-as24ci_car.php — de lay-out voor het voertuigarchief die wordt gebruikt voor het CPT-archief en voor de shortcode [as24ci_archive].
parts/search-filter.php — gedeeltelijke template (partial) gerenderd door [as24ci_search_filter] om het losstaande zoekformulier weer te geven.
page-as24ci_compare.php — vergelijkingspagina gerenderd door [as24ci_compare].
icons/ — gedeelde inline-SVG-pictogramhelpers die in alle templates worden gebruikt.
css/ en js/ — assets waarvan de templates afhankelijk zijn.

Hoe een verzoek een template bereikt

WordPress analyseert het verzoek en herleidt dit naar een individueel voertuig of naar het voertuigarchief.
Vlak voor de uitvoer past WordPress single_template of archive_template toe.
De filter-callback van de plugin: - retourneert de originele $template wanneer het verzoek niet voor as24ci_car is; - roept locate_template( '<template>.php' ) aan om het actieve (child-)thema de eerste kans te geven om te overschrijven; - als er geen themabestand bestaat, retourneert deze het meegeleverde bestand uit de map templates/ van de plugin; - als geen van beide bestaat, retourneert deze de originele $template zodat WordPress kan terugvallen op zijn standaardhiërarchie.

De shortcodes volgen in essentie dezelfde prioriteit, maar ze roepen locate_template() niet aan — ze voegen altijd de meegeleverde archief- / vergelijkings- / zoekfilterbestanden van de plugin in. Zie Shortcodes en Template Overrides voor de gevolgen hiervan.

Integratie van shortcodes en rendermodus

De plugin stelt een globale vlag beschikbaar, $as24ci_render_mode, die de shortcode-handlers instellen op 'shortcode' terwijl hun meegeleverde template wordt uitgevoerd. Voorwaardelijke code in de templates en in ondersteunende klassen (bijvoorbeeld voor het laden van assets) gebruikt deze vlag om dezelfde logica toe te passen op pagina's met shortcodes als op het systeemeigen CPT-archief.

De shortcode [as24ci_archive] vervangt de globale $wp_query door een aangepaste query terwijl de archieftemplate wordt gerenderd, en herstelt daarna de vorige query en wp_reset_postdata(), zodat deze veilig binnen een normale pagina kan worden ingesloten.

Configuratiereferentie

Optiesleutel	Effect op rendering
`as24ci_design_single_layout`	Selecteert de lay-out voor een individueel voertuig. De huidige wrapper laadt altijd het klassieke lay-outbestand; deze optie voedt ook lay-outbewuste body-classes en CSS. Standaard `'minimal'`.

Lay-out-, ontwerp- en functie-instellingen die invloed hebben op wat er in de templates wordt gerenderd (filterzones, favorieten-veldset, zoekagent-schakelaar, enz.) zijn gedocumenteerd in Options And Settings Storage.

Operationele opmerkingen

De filter-callbacks van de plugin retourneren het meegeleverde bestandspad als een string. WordPress voegt het bestand toe met zijn standaard template-loader, zodat globale variabelen zoals $post, $wp_query en body-classes zich gedragen zoals in elk ander thematemplate.
Meegeleverde templates declareren namespace AS24CI; en exit wanneer ABSPATH niet is gedefinieerd, wat de standaardbeveiliging van WordPress weerspiegelt.
Templatebestanden verwijzen naar pluginklassen zoals Archive_Filters, Field_Mapping, Schema, Options en Locations om hun gegevens te verzamelen. Thema's die het bestand overschrijven, moeten deze verwijzingen intact houden (of het ophalen van gelijkwaardige gegevens repliceren) om waarschuwingen over ongedefinieerde variabelen te voorkomen.
Het op shortcodes gebaseerde archief dwingt een nieuwe WP_Query af van $_GET-parameters via Archive_Filters::build_query_args_from_request(), zodat URL-filters identiek werken op het CPT-archief en op shortcode-pagina's.

Problemen oplossen

De lay-out van de plugin verschijnt nooit — controleer of het actieve thema geen eigen single-as24ci_car.php of archive-as24ci_car.php definieert; themabestanden winnen altijd. Zie Template Overrides.
Een pagina die [as24ci_archive] gebruikt, toont het verkeerde bericht — de shortcode vervangt de globale query tijdens de uitvoering en herstelt deze daarna. Als een aangepast themacomponent de globale query leest voordat de shortcode is verwerkt, is de volgorde waarin de pagina delen van de lay-out rendert van belang; sluit de shortcode in het hoofdinhoudsgebied in in plaats van in de header of zijbalk.
Paginering wordt gereset naar pagina 1 binnen [as24ci_archive] — de shortcode leest ?paged= en ?page= uit de URL. Zorg ervoor dat uw permalink-structuur query-strings toestaat of gebruik een permalink die compatibel is met de shortcode.
Asset (CSS/JS) niet geladen op een shortcode-pagina — de plugin detecteert shortcodes en de vlag $as24ci_render_mode om assets te laden. Als een builder de pagina-uitvoer cachet, wis die cache dan geforceerd na het bewerken van de pagina, zodat de shortcode wordt gedetecteerd tijdens het enqueuen.