Sistema di template e override

Questo documento descrive come il plugin ADP Car Market Hub carica i suoi template front-end e come un tema può sovrascriverli (override). Elenca i file forniti nella cartella templates/ del plugin e spiega quali sono sovrascrivibili dal tema tramite la gerarchia standard dei template di WordPress e quali vengono caricati direttamente dagli shortcode.

Quando utilizzare questo documento

Leggi questo documento quando hai bisogno di:

• Personalizzare il markup della pagina singola del veicolo, dell'archivio veicoli o della pagina di confronto da un tema o tema child.
• Sostituire una piccola porzione (ad esempio il modulo del filtro di ricerca) senza dover duplicare l'intero template.
• Capire quali file di template sono sicuri da sovrascrivere e quali cambiano tra le varie versioni.

Per i tipi di post e le tassonomie renderizzati da questi template, consulta Custom Post Types And Taxonomies. Per gli shortcode che caricano direttamente le parti di template, consulta Shortcodes For Developers.

Panoramica

Il plugin distribuisce i suoi template nella cartella templates/ del plugin stesso. Due meccanismi li espongono:

1. Filtri della gerarchia dei template di WordPress. Il plugin si aggancia a single_template e archive_template. Per entrambi i filtri chiama prima locate_template() in modo che un tema attivo o un tema child possa fornire la propria copia del file. Se non viene trovato alcun override nel tema, viene utilizzato il template integrato del plugin.
2. Rendering diretto tramite shortcode. Gli shortcode per la pagina di confronto ([as24ci_compare]) e il filtro di ricerca autonomo ([as24ci_search_filter]) caricano i loro template direttamente dalla cartella templates/ del plugin. Non consultano il tema per un eventuale override.

Il risultato è che la pagina del singolo veicolo e l'archivio dei veicoli possono essere sovrascritti in modo pulito inserendo un file nel tema attivo, mentre la pagina di confronto e la porzione del filtro di ricerca cambiano solo quando si modifica o si filtra il loro output attraverso un meccanismo diverso.

File inclusi in templates/

Template di primo livello:

• archive-as24ci_car.php — elenco dell'archivio veicoli.
• single-as24ci_car.php — pagina singola del veicolo (layout predefinito).
• single-as24ci_car-classic.php — layout singolo alternativo "classic".
• page-as24ci_compare.php — pagina di confronto renderizzata da [as24ci_compare].

Porzioni (partials) e asset:

• parts/search-filter.php — il modulo del filtro di ricerca renderizzato da [as24ci_search_filter].
• icons/ — definizioni delle icone SVG utilizzate dai template.
• css/ e js/ — fogli di stile e script front-end distribuiti insieme ai template e accodati dal caricatore di asset (vedi Frontend Assets).

Template sovrascrivibili dal tema

Questi file vengono caricati tramite i filtri single_template / archive_template e pertanto rispettano il tema:

Il plugin chiama locate_template( '<file-name>.php' ) senza alcun prefisso di sottocartella, quindi il file di override va inserito direttamente nella root del tema attivo (o nella root del tema child). Se locate_template() restituisce un percorso, il plugin lo utilizza; in caso contrario, ricorre al template integrato.

Template non caricati tramite la gerarchia del tema

Questi file sono caricati direttamente dal plugin e non vengono rilevati da locate_template():

Per personalizzare questi elementi, hai tre opzioni affidabili:

1. Crea una pagina o un template contenitore nel tuo tema che chiami lo shortcode pertinente e circondi il suo output con il tuo markup.
2. Utilizza gli hook di azione e filtro esposti dal plugin (vedi Hooks And Filters, Actions Reference, Filters Reference) per modificare il comportamento anziché il markup.
3. Come ultima risorsa, duplica (fork) il file nel tuo tema e caricalo dal tuo template; in questo caso ti assumerai la responsabilità di mantenerlo allineato con le future versioni del plugin.

Istruzioni passo dopo passo

Sovrascrivere la pagina singola del veicolo

1. Copia single-as24ci_car.php dalla cartella templates/ del plugin.
2. Incollalo nella root del tuo tema attivo (o tema child).
3. Modifica la copia per apportare le tue modifiche.
4. Ricarica la pagina di un singolo veicolo. WordPress caricherà il tuo file tramite locate_template() invece del file integrato del plugin.

Sovrascrivere l'archivio veicoli

1. Copia archive-as24ci_car.php dalla cartella templates/ del plugin.
2. Incollalo nella root del tuo tema attivo (o tema child).
3. Modifica la copia. Ricarica la pagina dell'archivio (di default /cars/) per vedere la tua versione.

Personalizzare la pagina di confronto o il modulo del filtro di ricerca

1. Avvolgi lo shortcode pertinente in un template di pagina personalizzato o in un layout a blocchi nel tuo tema, oppure duplica il template sottostante nel tuo tema e caricalo dal tuo template.
2. Verifica che tutti gli asset del plugin da cui dipendi (CSS/JS, vedi Frontend Assets) siano ancora accodati nella tua pagina personalizzata.

Note operative

• Usa un tema child. Inserisci gli override in un tema child per evitare di perderli quando il tema genitore si aggiorna.
• Interazione con il Layout Manager. Il plugin include un Layout Manager che organizza i blocchi all'interno delle pagine del singolo veicolo e dell'archivio, configurabile dall'interfaccia di amministrazione del plugin. Se sostituisci completamente il template singolo o dell'archivio, escluderai anche il Layout Manager. Utilizza modifiche mirate basate su hook quando hai bisogno di mantenere tale comportamento.
• Attivazione della pagina di confronto. La pagina di confronto viene creata all'attivazione. La pagina stessa contiene semplicemente lo shortcode [as24ci_compare], quindi il suo contenuto viene renderizzato dal template del plugin, non da single_template / archive_template.
• Shortcode in qualsiasi pagina. Poiché [as24ci_archive] riutilizza il renderer dell'archivio, puoi incorporare l'elenco in qualsiasi pagina o layout a blocchi di WordPress senza dover sovrascrivere affatto il template dell'archivio.
• Accodamento degli asset. I CSS e JavaScript front-end distribuiti con il plugin vengono accodati in modo condizionale in base alla pagina corrente (singola, archivio, utilizzo di shortcode). Se crei un template contenitore personalizzato che non corrisponde alle condizioni standard, i relativi asset del plugin potrebbero non essere accodati automaticamente.
• Verifica il comportamento nella versione corrente del plugin prima di pubblicare un tema personalizzato. La struttura dei template e il markup dei blocchi possono cambiare tra una release e l'altra.

Risoluzione dei problemi

• Il mio override del tema viene ignorato. Verifica che il nome del file corrisponda esattamente (single-as24ci_car.php, archive-as24ci_car.php) e che si trovi nella root del tema attivo. Svuota la cache degli oggetti o della pagina.
• La pagina singola mostra il layout classico (o viceversa). Il layout singolo viene selezionato dalle impostazioni di design del plugin nell'interfaccia di amministrazione. Modificalo lì anziché dal tema.
• La pagina di confronto non mostra nulla o restituisce un errore 404. Verifica che la pagina di confronto esista ancora, contenga lo shortcode [as24ci_compare] e sia pubblicata. Verifica che la funzionalità di confronto sia abilitata nell'interfaccia di amministrazione del plugin.
• Script o stile front-end mancante su una pagina contenitore personalizzata. Il caricatore di asset del plugin si basa sul rilevamento del tipo di post, dell'archivio e degli shortcode. Utilizza gli shortcode ufficiali all'interno del tuo contenitore in modo che gli asset corrispondenti vengano accodati automaticamente.
• Verifica il comportamento nella versione corrente del plugin prima di pubblicare un'integrazione personalizzata. I percorsi dei template e il markup possono evolversi tra una release e l'altra.

Documenti correlati

• Custom Post Types And Taxonomies
• Shortcodes For Developers
• Frontend Assets
• Hooks And Filters
• Filters Reference