Sistema di template frontend

Questo documento spiega come il plugin ADP Car Market Hub gestisce il rendering delle pagine dei veicoli sul front-end, come i suoi template inclusi si relazionano con il tema WordPress attivo e quali punti di estensione sono esposti a temi e shortcode.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Capire quale file esegue il rendering della pagina del singolo veicolo o dell'archivio veicoli.
• Decidere se utilizzare un elenco basato su shortcode all'interno di una pagina normale o affidarsi all'archivio del CPT.
• Estendere o sovrascrivere il layout da un tema child. Per i meccanismi di sovrascrittura, consulta Template Overrides.

Panoramica

Il plugin registra il suo custom post type as24ci_car con supporto per l'archivio e include un piccolo set di template predefiniti all'interno della directory templates/ del plugin. Due filtri di WordPress indirizzano le richieste a questi template quando il tema attivo non fornisce una propria versione:

• single_template — utilizzato per is_singular( 'as24ci_car' ).
• archive_template — utilizzato per is_post_type_archive( 'as24ci_car' ).

Ciascun filtro chiede innanzitutto a WordPress di individuare un override a livello di tema (locate_template()), e ricorre al file incluso nel plugin solo quando non esiste alcun override.

Template inclusi

I seguenti file si trovano nella cartella templates/ del plugin e vengono caricati dai filtri sopra indicati (o dagli shortcode):

• single-as24ci_car.php — un sottile wrapper che seleziona il layout corretto per il singolo veicolo in base all'opzione as24ci_design_single_layout e include il file di layout scelto.
• single-as24ci_car-classic.php — l'attuale layout per il singolo veicolo. Al momento il wrapper carica sempre questo file; le versioni future potrebbero aggiungere ulteriori layout. Verifica il comportamento rispetto alla versione corrente del plugin prima di pubblicare testi destinati ai clienti.
• archive-as24ci_car.php — il layout dell'archivio veicoli utilizzato per l'archivio del CPT e per lo shortcode [as24ci_archive].
• parts/search-filter.php — file parziale renderizzato da [as24ci_search_filter] per mostrare il modulo di ricerca autonomo.
• page-as24ci_compare.php — pagina di confronto renderizzata da [as24ci_compare].
• icons/ — helper condivisi per icone SVG inline utilizzati in tutti i template.
• css/ e js/ — asset da cui dipendono i template.

Come una richiesta raggiunge un template

1. WordPress analizza la richiesta e la risolve in un singolo veicolo o nell'archivio dei veicoli.
2. Subito prima dell'output, WordPress applica single_template o archive_template.
3. La callback del filtro del plugin: - restituisce il file $template originale quando la richiesta non riguarda as24ci_car; - chiama locate_template( '<template>.php' ) per dare al tema attivo (child) la prima possibilità di effettuare l'override; - se non esiste alcun file del tema, restituisce il file incluso nella directory templates/ del plugin; - se non esiste nessuno dei due, restituisce il file $template originale in modo che WordPress possa ricorrere alla sua gerarchia standard.

Gli shortcode seguono lo stesso principio di precedenza, ma non chiamano locate_template() — includono sempre i file di archivio / confronto / filtri di ricerca forniti dal plugin. Vedi Shortcodes e Template Overrides per le relative implicazioni.

Integrazione tra shortcode e modalità di rendering

Il plugin espone un flag globale, $as24ci_render_mode, che i gestori degli shortcode impostano su 'shortcode' durante l'esecuzione del loro template incluso. Il codice condizionale nei template e nelle classi di supporto (ad esempio per il caricamento degli asset) utilizza questo flag per applicare alle pagine basate su shortcode la stessa logica applicata all'archivio nativo del CPT.

Lo shortcode [as24ci_archive] sostituisce la query globale $wp_query con una query personalizzata durante il rendering del template di archivio, e ripristina la query precedente e wp_reset_postdata() successivamente, in modo da poter essere incorporato in sicurezza all'interno di una pagina normale.

Riferimento di configurazione

Le opzioni relative a layout, design e funzionalità che influenzano ciò che viene renderizzato all'interno dei template (zone dei filtri, set di campi dei preferiti, interruttore dell'agente di ricerca, ecc.) sono documentate in Options And Settings Storage.

Note operative

• Le callback dei filtri del plugin restituiscono il percorso del file incluso come stringa. WordPress include il file con il suo caricatore di template standard, quindi le variabili globali come $post, $wp_query e le classi del body si comportano come in qualsiasi template del tema.
• I template inclusi dichiarano namespace AS24CI; e exit quando ABSPATH non è definito, rispecchiando la protezione standard di WordPress.
• I file dei template fanno riferimento a classi del plugin come Archive_Filters, Field_Mapping, Schema, Options e Locations per assemblare i propri dati. I temi che sovrascrivono il file devono mantenere intatti questi riferimenti (o replicare il recupero dei dati equivalente) per evitare avvisi di variabili non definite.
• L'archivio basato su shortcode forza un nuovo WP_Query dai parametri di $_GET tramite Archive_Filters::build_query_args_from_request(), in modo che i filtri URL funzionino in modo identico sull'archivio del CPT e sulle pagine degli shortcode.

Risoluzione dei problemi

• Il layout del plugin non appare mai — verifica che il tema attivo non definisca i propri file single-as24ci_car.php o archive-as24ci_car.php; i file del tema hanno sempre la precedenza. Vedi Template Overrides.
• Una pagina che utilizza [as24ci_archive] mostra l'articolo errato — lo shortcode sostituisce la query globale durante la sua esecuzione e la ripristina successivamente. Se un componente personalizzato del tema legge la query globale prima che lo shortcode venga elaborato, l'ordine in cui la pagina renderizza le parti del layout diventa importante; inserisci lo shortcode nell'area del contenuto principale anziché nell'header o nella barra laterale.
• La paginazione si azzera alla pagina 1 all'interno di [as24ci_archive] — lo shortcode legge ?paged= e ?page= dall'URL. Assicurati che la struttura dei permalink consenta le query string o utilizza un permalink compatibile con lo shortcode.
• Asset (CSS/JS) non caricati su una pagina con shortcode — il plugin rileva gli shortcode e il flag $as24ci_render_mode per caricare gli asset. Se un builder memorizza in cache l'output della pagina, svuota forzatamente tale cache dopo aver modificato la pagina in modo che lo shortcode venga rilevato durante l'accodamento.

Documenti correlati

• Template Overrides
• Shortcodes
• Custom Post Types And Taxonomies
• Options And Settings Storage
• Architecture Overview