Documentazione · Documentazione tecnica

Sovrascrittura dei template

Questo documento spiega come sovrascrivere i template front-end inclusi nel plugin ADP Car Market Hub da un tema (child) in modo che gli aggiornamenti non sovrascrivano le tue personalizzazioni.

Quando utilizzare questo documento

Leggi questo documento se hai la necessità di:

Modificare il markup, il layout o l'ordine dei campi nella pagina del singolo veicolo o nell'archivio dei veicoli senza modificare i file sorgente del plugin.
Applicare wrapper, barre laterali o hook specifici del tema alle pagine del plugin.
Migrare le personalizzazioni esistenti in un tema child per renderle sicure a seguito degli aggiornamenti.

Per il flusso di caricamento dei template sottostante, consulta il documento Frontend Template System. Per i shortcode basati su template, consulta Shortcodes.

Panoramica

Il plugin esegue il rendering delle singole pagine dei veicoli e dell'archivio dei veicoli tramite due filtri di WordPress:

single_template — sostituito da single-as24ci_car.php (sovrascrittura del tema) o dal file incluso nel plugin.
archive_template — sostituito da archive-as24ci_car.php (sovrascrittura del tema) o dal file incluso nel plugin.

Per ciascun filtro, il plugin chiama prima locate_template(). Se il tema attivo (o il suo tema child) fornisce un file con il nome previsto, quel file ha la priorità. In caso contrario, il plugin ripiega sul file fornito all'interno della propria directory templates/.

Questo rende le sovrascritture semplici: inserisci un file con il nome corretto nel tuo tema e WordPress lo caricherà al posto della versione inclusa nel plugin.

Requisiti o prerequisiti

Si raccomanda caldamente l'uso di un tema child, in modo che gli aggiornamenti del tema non sovrascrivano le tue modifiche.
Familiarità con i file di template inclusi. Utilizzano il namespace AS24CI e si basano su classi del plugin come Archive_Filters, Field_Mapping, Schema, Options e Locations.
Accesso in lettura alla directory templates/ del plugin per copiare il markup originale come punto di partenza.

Istruzioni passo dopo passo

Identifica il template che desideri sovrascrivere: - Pagina del singolo veicolo → single-as24ci_car.php. - Pagina dell'archivio dei veicoli → archive-as24ci_car.php.
Copia il file originale dalla directory templates/ del plugin nella root del tuo tema (child) utilizzando lo stesso nome file.
Modifica la copia nel tuo tema. Mantieni i riferimenti alle classi esistenti e i recuperi dei dati, a meno che tu non sia sicuro della loro sostituzione.
Svuota qualsiasi cache di pagina intera o di template.
Ricarica la pagina pertinente sul front-end e conferma che la sovrascrittura venga caricata (ad esempio visualizzando il codice sorgente della pagina per cercare un commento di controllo che hai aggiunto).

Posizioni di sovrascrittura

Il plugin utilizza locate_template() con il nome del file nudo. Ciò significa che WordPress effettua la ricerca in:

La directory root del tema child attivo.
La directory root del tema parent attivo.

Le strutture di sottodirectory all'interno di un tema (ad esempio <theme>/templates/single-as24ci_car.php) non vengono scansionate dal filtro del plugin. Posiziona i file di sovrascrittura nella root del tema utilizzando l'esatto nome del file.

Cosa è possibile sovrascrivere

single-as24ci_car.php — l'intera pagina del singolo veicolo. Il wrapper incluso è intenzionalmente minimale; il layout effettivo risiede in single-as24ci_car-classic.php. Sovrascrivere il wrapper significa assumersi la piena responsabilità della scelta e dell'inclusione di un layout.
archive-as24ci_car.php — l'intera pagina dell'archivio dei veicoli. Questo è anche il file che il shortcode [as24ci_archive] include (vedi Limitazioni di seguito).

Cosa non è direttamente sovrascrivibile

Parti di template (es. templates/parts/search-filter.php) vengono caricate con include da percorsi assoluti del plugin e non passano attraverso locate_template(). Per personalizzarle, sovrascrivi il template genitore che le include e replica l'output richiesto, oppure utilizza gli hook e i filtri disponibili nel plugin.
Template dei shortcode — [as24ci_archive], [as24ci_compare] e [as24ci_search_filter] includono sempre i file originali del plugin (archive-as24ci_car.php, page-as24ci_compare.php, parts/search-filter.php). Una sovrascrittura da tema di archive-as24ci_car.php influisce quindi anche sul shortcode [as24ci_archive], ma i template di confronto e di filtro di ricerca non possono essere sovrascritti tramite locate_template().
CSS/JS del plugin da cui dipendono i template. Sovrascrivi gli stili tramite il foglio di stile del tuo tema anziché rimuovere gli asset messi in coda dal plugin.

Note operative

Quando aggiorni il plugin, controlla il changelog per eventuali modifiche ai template inclusi. Se il plugin aggiunge o rimuove dati visualizzati dal template, potrebbe essere necessario aggiornare la tua sovrascrittura per adeguarla.
Evita di mescolare sovrascritture parziali con codice che presuppone la struttura del file originale. Mantieni la sovrascrittura fedele all'originale oppure documenta le divergenze all'interno del file.
Le sovrascritture del tema non sono influenzate dagli aggiornamenti automatici del plugin perché WordPress aggiorna solo i file all'interno della directory del plugin.
Le sovrascritture si applicano sia agli amministratori loggati che ai visitatori. Non esiste un meccanismo di sovrascrittura basato sul ruolo nel plugin.
Le sovrascritture non possono bypassare i controlli sul post-type o sulle capacità applicati dai filtri: la sovrascrittura viene caricata solo per richieste autentiche di singoli o archivi as24ci_car.

Risoluzione dei problemi

Il file di sovrascrittura viene ignorato — verifica che il file si trovi nella root del tema attivo e utilizzi l'esatto nome file (single-as24ci_car.php o archive-as24ci_car.php). Controlla la presenza di refusi o se un tema parent fornisce già lo stesso file.
Errore fatale dopo la sovrascrittura — i template inclusi utilizzano il namespace AS24CI e fanno riferimento alle classi del plugin. Se hai copiato solo una parte del file, ripristina la dichiarazione del namespace e la protezione defined( 'ABSPATH' ), mantenendo intatti i recuperi Field_Mapping / Archive_Filters.
La sovrascrittura appare nell'archivio CPT ma non nel shortcode — entrambi i percorsi caricano archive-as24ci_car.php dalla directory templates/ del plugin; il shortcode non utilizza locate_template(). Verifica il percorso della tua sovrascrittura e che nessun plugin di cache stia servendo una versione precedente della pagina.
Il layout appare privo di stile dopo la sovrascrittura — il CSS incluso si aspetta nomi di classe specifici. Mantieni tali nomi di classe nella tua sovrascrittura o estendi il foglio di stile del tema per coprire il nuovo markup.