Documentazione · Guida all'integrazione

Guida alla sovrascrittura dei template

Questo documento spiega come personalizzare in sicurezza i template PHP utilizzati dal plugin ADP Car Market Hub creando file di override nel tuo tema e come mantenere tali sovrascritture gestibili nel tempo durante gli aggiornamenti del plugin.

Quando utilizzare questo documento

Utilizza questo documento se sei:

Un sviluppatore che ha la necessità di modificare la struttura HTML dell'archivio veicoli, della pagina di dettaglio del singolo veicolo o della pagina di confronto oltre a quanto consentito dalle impostazioni di Design e dal CSS personalizzato.
Responsabile della manutenzione di un tema personalizzato e desideri integrare perfettamente le pagine dei veicoli nella struttura HTML del tema stesso.
Impegnato nella revisione di un sito dopo un aggiornamento del plugin per verificare se le sovrascritture esistenti sono ancora compatibili.

Questa guida è rivolta agli sviluppatori PHP che hanno familiarità con lo sviluppo di temi WordPress. Se hai solo bisogno di modificare colori, font o spaziature, utilizza invece Car Market Hub → Design o il campo CSS personalizzato — non è necessario alcun override dei template. Consulta la Guida al CSS personalizzato.

Panoramica

Il plugin fornisce template PHP di fallback per le pagine dei veicoli nella sua directory templates/. WordPress individua i template in un ordine specifico: i file del tema attivo vengono controllati prima di quelli del plugin. Il plugin utilizza intenzionalmente questo meccanismo tramite locate_template():

WordPress controlla la directory del tema attivo alla ricerca di un file con lo stesso nome.
Se trovato, viene utilizzato quel file del tema.
Se non viene trovato, il template del plugin viene utilizzato come fallback.

Ciò significa che puoi sovrascrivere qualsiasi template front-end del plugin inserendo un file con lo stesso nome nella directory principale del tuo tema. Il file del plugin non viene mai modificato e rimane al sicuro dalle tue personalizzazioni durante gli aggiornamenti. Il tuo file di override rimane nel tema, che si trova sotto il tuo controllo di versione.

Template disponibili per la sovrascrittura

I seguenti file di template vengono risolti tramite locate_template() e possono essere sovrascritti:

Nome file del template	Scopo	Posizione nel plugin
`single-as24ci_car.php`	Pagina di dettaglio del singolo veicolo. Carica il layout attivo (attualmente sempre `single-as24ci_car-classic.php`).	`templates/single-as24ci_car.php`
`archive-as24ci_car.php`	Pagina dell'archivio veicoli e degli annunci. Utilizzato anche quando lo shortcode `[as24ci_archive]` viene renderizzato in modalità template.	`templates/archive-as24ci_car.php`

La pagina di confronto (page-as24ci_compare.php) e il partial del filtro di ricerca (parts/search-filter.php) sono caricati direttamente dal plugin e non vengono risolti tramite locate_template(). Non possono essere sovrascritti utilizzando questo metodo. Verifica questo comportamento nella versione corrente del plugin prima di fare affidamento su di esso.

Requisiti preliminari

Accesso ai file del tema attivo (tramite FTP, SSH o l'editor di file di WordPress).
Si raccomanda caldamente l'uso di un tema child se stai utilizzando un tema commerciale o un tema parent. L'inserimento dei file di override in un tema parent comporta la loro perdita al momento dell'aggiornamento del tema parent stesso.
Familiarità con PHP e con i tag dei template di WordPress (get_header(), get_footer(), the_title() e simili).

Istruzioni passo dopo passo

Creazione di un override del template

Individua il file sorgente. Trova il template che desideri personalizzare nella directory del plugin, in wp-content/plugins/adp-car-market-hub/templates/. Ad esempio, archive-as24ci_car.php.
Copia — non spostare — il file. Copia il file nella directory principale del tuo tema (child). Il nome del file deve essere identico: - Per l'archivio: wp-content/themes/your-theme/archive-as24ci_car.php - Per il singolo: wp-content/themes/your-theme/single-as24ci_car.php
Apporta le modifiche nella copia del tema. Modifica la copia nel tuo tema. Il file originale del plugin rimane intatto.
Testa sul front-end. Visita un archivio veicoli o la pagina di un singolo veicolo e conferma che le modifiche siano applicate.

Verificare quale template è attivo

La pagina Stato di salute del sito di WordPress e i plugin di monitoraggio delle query (ad esempio Query Monitor) possono mostrare quale file di template viene utilizzato per una determinata richiesta. In alternativa, aggiungi un commento temporaneo all'inizio del tuo file di override e controlla il codice sorgente della pagina per confermare che il file venga caricato.

Mantenere la compatibilità dopo gli aggiornamenti del plugin

Quando il plugin viene aggiornato, i template inclusi in templates/ potrebbero subire modifiche. Il tuo file di override rimane nel tema e continua a essere utilizzato — ma se la logica dei template del plugin è cambiata, il tuo override potrebbe non essere aggiornato.

Dopo ogni aggiornamento del plugin:

Confronta il tuo file di override con il file corrispondente nella directory del plugin aggiornato. Uno strumento di diff o un editor di codice con confronto file può essere d'aiuto.
Integra eventuali modifiche rilevanti dalla nuova versione del plugin nel tuo override.
Testa le pagine dei veicoli sul front-end dopo l'integrazione.

Mantenere gli override al minimo — contenenti solo le sezioni che hai effettivamente bisogno di modificare — riduce il lavoro richiesto durante l'integrazione degli aggiornamenti.

Riferimento di configurazione

Non esiste un campo di impostazione del plugin che controlli direttamente le sovrascritture dei template. La logica di risoluzione fa parte del sistema di hook di WordPress e non può essere modificata dall'amministrazione del plugin.

Le impostazioni di Design in Car Market Hub → Design si applicano comunque anche quando è in uso un override del template, poiché il CSS dinamico viene generato tramite wp_head indipendentemente da quale file di template venga servito.

Note operative

Requisito del tema child. Se utilizzi un tema commerciale o parent, crea sempre un tema child prima di aggiungere file di override. I file aggiunti direttamente a un tema parent vengono eliminati quando il tema si aggiorna.
L'override deve chiamare get_header() e get_footer(). I template del plugin li chiamano entrambi. Se il tuo override li omette, la pagina verrà servita senza la navigazione e il piè di pagina del tema. Questo non è quasi mai desiderabile.
Mantieni il namespace del plugin. I file di template del plugin dichiarano namespace AS24CI; e fanno riferimento a costanti interne come CPT::POST_TYPE e Options::DESIGN_SINGLE_LAYOUT. Se il tuo override utilizza una di queste, mantieni la dichiarazione del namespace o qualifica completamente i nomi delle classi.
Modalità di rendering dello shortcode. Il template dell'archivio supporta due modalità di rendering controllate dalla variabile globale $as24ci_render_mode: 'template' (quando servito come pagina di archivio CPT) e 'shortcode' (quando incluso dallo shortcode [as24ci_archive]). Il template omette get_header() e get_footer() in modalità shortcode. Il tuo override dovrebbe replicare questo comportamento se desideri che lo shortcode funzioni correttamente insieme al template dell'archivio.
Stabilità delle classi CSS. Il CSS del plugin dipende dai nomi delle classi nell'HTML del template (ad esempio .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). Se rimuovi o rinomini queste classi nel tuo override, il foglio di stile del plugin e le impostazioni di Design smetteranno di funzionare per quegli elementi. Modifica i nomi delle classi solo se aggiorni anche il CSS corrispondente nel campo CSS personalizzato o nel foglio di stile del tuo tema.
Classe alignfull. Il plugin aggiunge la classe alignfull al wrapper .as24ci-page in modo che i temi a blocchi lo estendano a larghezza intera. Se rimuovi questa classe nel tuo override, il comportamento a larghezza intera del tema a blocchi non verrà applicato.
Requisiti di versione PHP e WordPress. I template del plugin utilizzano funzionalità PHP coerenti con i requisiti dichiarati del plugin. Vedi Requisiti di PHP e database.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa verificare
Il file di override non viene utilizzato.	Il file si trova nella directory errata, presenta un errore di battitura nel nome del file o si trova nella root del tema parent anziché nella root del tema child.	Conferma il nome esatto del file e la sua posizione. Utilizza Query Monitor o controlla il codice sorgente della pagina alla ricerca di un commento temporaneo nel file di override.
Le pagine dei veicoli restituiscono una pagina vuota o un errore PHP dopo la creazione dell'override.	Il file di override presenta un errore di sintassi PHP o manca di un'inclusione richiesta.	Controlla il log degli errori PHP del server. Conferma che il file di override apra e chiuda correttamente i tag PHP.
Il CSS del plugin non viene applicato sul template sovrascritto.	La classe wrapper `.as24ci-page` o `.as24ci-page-classic` manca dall'output dell'override.	Assicurati che il wrapper esterno `<div class="as24ci-page as24ci-page-classic …">` sia presente nell'override.
Le impostazioni di Design (colori, tipografia) non hanno effetto.	L'output CSS dinamico si basa sulle classi wrapper del plugin. Se sono assenti, le regole con ambito non corrispondono.	Ripristina le classi wrapper come descritto sopra.
Lo shortcode `[as24ci_archive]` non mostra l'intestazione o il piè di pagina del tema quando è attivo anche l'override dell'archivio.	L'override chiama sempre `get_header()` e `get_footer()` indipendentemente da `$as24ci_render_mode`.	Aggiungi un controllo per `$as24ci_render_mode === 'template'` prima di chiamare `get_header()` e `get_footer()`, rispecchiando la logica del template del plugin stesso.