Documentazione · Guida all'integrazione

Integrazione con i Page Builder

Questo documento spiega come utilizzare il plugin ADP Car Market Hub all'interno dei flussi di lavoro dei page builder, come inserire gli shortcode nelle pagine create con qualsiasi editor di pagina e cosa verificare sul front-end dopo l'inserimento.

Quando utilizzare questo documento

Utilizza questo documento se stai:

Inserendo elenchi di veicoli, filtri di ricerca o lo strumento di confronto su pagine create con un page builder come Elementor, WPBakery, Divi, Beaver Builder o l'editor a blocchi di WordPress (Gutenberg).
Creando una homepage personalizzata o una landing page che deve mostrare un sottoinsieme filtrato dell'inventario dei veicoli.
Posizionando un filtro di ricerca autonomo su una pagina in modo che i visitatori possano iniziare a filtrare prima di navigare alla pagina dei risultati.
Diagnosticando problemi in cui gli asset del plugin non si caricano correttamente su una pagina creata con un page builder.

Il pubblico di riferimento è un amministratore o un site builder di WordPress. Non è richiesta alcuna conoscenza di PHP o CSS per l'inserimento di base degli shortcode.

Panoramica

Il plugin fornisce tre shortcode per il front-end che puoi inserire in qualsiasi pagina WordPress, comprese le pagine create con page builder di terze parti:

Shortcode	Cosa genera
`[as24ci_archive]`	Elenco completo dei veicoli con filtri di ricerca, controlli di ordinamento, schede di stato e paginazione. Equivalente alla pagina dell'archivio veicoli.
`[as24ci_search_filter]`	Modulo di filtro di ricerca autonomo senza risultati. Invia i dati all'archivio veicoli o a qualsiasi pagina dei risultati specificata.
`[as24ci_compare]`	Tabella di confronto dei veicoli. Dipende dai veicoli che sono stati aggiunti alla lista di confronto dal visitatore.

Sono disponibili shortcode aggiuntivi per funzionalità secondarie:

Shortcode	Cosa genera
`[as24ci_favorites]`	Elenco dei veicoli che il visitatore ha contrassegnato come preferiti.
`[as24ci_location_box post_id=""]`	Scheda della sede del concessionario per l'articolo Location specificato.
`[as24ci_hours_box post_id=""]`	Scheda degli orari di apertura per l'articolo Location specificato.

Questi shortcode funzionano in qualsiasi page builder che supporti gli shortcode standard di WordPress. L'output è lo stesso delle corrispondenti pagine gestite dal plugin.

Requisiti preliminari

Prima di inserire gli shortcode:

Il plugin deve essere installato e attivato.
Almeno un veicolo deve essere stato importato (per [as24ci_archive] e [as24ci_search_filter]).
I permalink leggibili devono essere abilitati (Impostazioni → Permalink). Senza permalink leggibili, l'URL dell'archivio veicoli potrebbe non risolversi correttamente quando [as24ci_search_filter] reindirizza un visitatore alla pagina dei risultati.
Se utilizzi l'Editor a blocchi (Gutenberg), non è necessaria alcuna configurazione aggiuntiva. Se utilizzi un page builder di terze parti, verifica che mantenga gli shortcode di WordPress senza codificare o convertire le parentesi quadre.

Istruzioni passo dopo passo

Inserire l'archivio veicoli in una pagina

Crea una nuova pagina o aprine una esistente nel tuo page builder.
Aggiungi un blocco shortcode (o il suo equivalente nel tuo page builder: Elementor ha un widget Shortcode, WPBakery ha un elemento Singola immagine → Shortcode, Divi ha un modulo Codice, e così via).
Incolla lo shortcode:

   [as24ci_archive]

Per pre-filtrare l'elenco — ad esempio per mostrare solo i veicoli elettrici — utilizza gli attributi opzionali dello shortcode:

   [as24ci_archive fuel="electric" per_page="24"]

Attributi supportati:

Attributo	Valori	Descrizione
`make`	Qualsiasi slug di marca (es. `bmw`)	Pre-seleziona una marca.
`model`	Qualsiasi slug di modello (es. `3-series`)	Pre-seleziona un modello (da usare con `make`).
`price_min`	Intero	Filtro prezzo minimo.
`price_max`	Intero	Filtro prezzo massimo.
`fuel`	Qualsiasi slug di tipo di carburante	Pre-seleziona un tipo di carburante.
`body`	Qualsiasi slug di carrozzeria	Pre-seleziona un tipo di carrozzeria.
`order_by`	`price`, `mileage`, `date`	Campo di ordinamento predefinito.
`order`	`asc`, `desc`	Direzione di ordinamento. Predefinito `asc`.
`per_page`	`12`, `24`, `48`, `72`, `all`	Risultati per pagina. Predefinito `24`.

Gli attributi dello shortcode impostano i valori predefiniti. I visitatori possono comunque sovrascriverli interagendo con i filtri sulla pagina. I parametri di query dell'URL hanno sempre la precedenza sugli attributi dello shortcode.

Pubblica o visualizza in anteprima la pagina e conferma che l'elenco dei veicoli appaia.

Inserire un filtro di ricerca autonomo

Posiziona [as24ci_search_filter] in qualsiasi punto di una pagina — ad esempio nella homepage — per consentire ai visitatori di impostare i propri criteri prima di essere indirizzati alla pagina dei risultati.

[as24ci_search_filter results_url="/cars/"]

L'attributo results_url specifica dove inviare il modulo. Per impostazione predefinita, corrisponde all'URL dell'archivio veicoli. Impostalo sull'URL di qualsiasi pagina che contenga [as24ci_archive].
Se il plugin non riesce a determinare automaticamente l'URL dell'archivio e results_url non è impostato, il modulo reindirizza per impostazione predefinita a /cars/.

Utilizzare la pagina di confronto come modello

La pagina di confronto è uno speciale modello di pagina di WordPress (page-as24ci_compare.php). Il plugin può creare automaticamente una pagina Confronta durante l'installazione. Puoi anche inserire [as24ci_compare] in un blocco shortcode su qualsiasi pagina normale per incorporare la tabella di confronto in linea.

Riferimento di configurazione

Tutti gli shortcode utilizzano le impostazioni già definite nell'amministrazione del plugin. Non ci sono campi di configurazione separati per la modalità page builder.

Attributo dello shortcode	Da dove provengono le opzioni sottostanti
Quali filtri appaiono in `[as24ci_archive]` e `[as24ci_search_filter]`	Il layout dei filtri attivo configurato nella scheda Filtri dell'amministrazione del plugin.
Design visivo di tutti gli shortcode	Car Market Hub → Design — colori, tipografia, raggio del bordo, ecc.
Flag delle funzionalità (preferiti, confronto, agente di ricerca)	Car Market Hub → Impostazioni (e la Configurazione guidata). Se una funzionalità è disabilitata, lo shortcode corrispondente non genera nulla o mostra un messaggio.

Caricamento degli asset

Il plugin rileva se uno shortcode è presente nella pagina corrente utilizzando la funzione has_shortcode() di WordPress e accoda automaticamente i file CSS e JavaScript appropriati. Non è necessario configurare manualmente il caricamento degli asset.

Sulle pagine che utilizzano [as24ci_archive] o [as24ci_compare], vengono accodati i seguenti fogli di stile:

as24ci-archive.css — per [as24ci_archive]
as24ci-compare.css — per [as24ci_compare] e per l'interruttore di confronto nelle pagine dell'archivio e dei singoli veicoli
as24ci-search-agent.css — quando la funzionalità Agente di ricerca è abilitata

Il blocco CSS del design dinamico (<style id="as24ci-dynamic-styles">) viene generato in <head> su ogni pagina del front-end, non solo sulle pagine specifiche del plugin.

Note operative

Paginazione sulle pagine con shortcode. Lo shortcode [as24ci_archive] legge i parametri di query ?paged= e ?page= per la paginazione. Quando un page builder o un tema utilizza tali parametri per i propri scopi, potrebbe verificarsi un conflitto. Verifica la paginazione sulla pagina nel suo contesto finale.
Permalink semplici. Con i permalink semplici (query-string) abilitati, is_post_type_archive() restituisce false per l'archivio del plugin. Il plugin ricorre al rilevamento di has_shortcode(), quindi CSS e JavaScript vengono comunque caricati. Tuttavia, il results_url per [as24ci_search_filter] potrebbe non risolversi correttamente — preferisci i permalink leggibili in produzione.
Rendering dei contenuti del page builder. Alcuni page builder eseguono il rendering degli shortcode sul server (standard do_shortcode) e altri li visualizzano tramite Ajax o sul client. Gli shortcode del plugin si affidano al rendering standard lato server. Se un page builder rimanda il rendering al lato client, l'output potrebbe apparire vuoto nell'anteprima del builder, ma dovrebbe essere visualizzato correttamente sul front-end pubblicato.
Shortcode nidificati. Non nidificare gli shortcode del plugin l'uno dentro l'altro. Ogni shortcode gestisce la propria WP_Query e lo stato globale.
Layout a larghezza intera. Come i modelli di archivio e dei singoli veicoli del plugin, l'output dello shortcode racchiude tutto all'interno di .as24ci-page.alignfull. Sui temi a blocchi, questo fa sì che l'elenco si estenda a tutta larghezza. Se il page builder limita la pagina a un contenitore più stretto, il contenuto dello shortcode sarà limitato da quel contenitore. Vedi Integrazione con il tema per i dettagli.
Posizione del filtro di ricerca. Lo shortcode [as24ci_search_filter] genera il modulo di filtro ma non un elenco di risultati. Quando viene posizionato sulla homepage, l'azione del modulo dovrebbe puntare a una pagina separata che contiene [as24ci_archive].

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa verificare
Lo shortcode viene visualizzato come testo letterale (`[as24ci_archive]`).	Il page builder sta convertendo o codificando lo shortcode invece di eseguirlo.	Utilizza il widget Shortcode dedicato del page builder o il blocco Codice anziché un blocco di testo normale.
Lo shortcode dell'archivio non mostra veicoli.	Non è ancora stato importato alcun veicolo, oppure gli attributi di pre-filtro nello shortcode non corrispondono a nessun veicolo.	Importa prima i veicoli. Verifica i valori degli attributi rispetto ai dati reali in Car Market Hub → Auto.
Il CSS non viene applicato sulla pagina dello shortcode.	Il page builder rimuove o rimanda i fogli di stile del plugin.	Controlla gli strumenti per sviluppatori del browser → scheda Rete per il foglio di stile `as24ci-archive` o `as24ci-single`. Se manca, verifica se il page builder ha un'opzione per preservare gli asset di terze parti.
Il CSS dinamico (`as24ci-dynamic-styles`) è mancante.	Un plugin di caching o ottimizzazione sta rimuovendo i blocchi `<style>` in linea da `<head>`.	Escludi `as24ci-dynamic-styles` dalla regola di ottimizzazione o inserisci gli handle `as24ci-*` nella whitelist.
La paginazione non funziona sulla pagina dello shortcode dell'archivio.	Il parametro `?paged=` viene consumato o riscritto dal tema o dal page builder.	Esegui un test con la navigazione URL semplice. Verifica se il tema o il page builder intercetta i parametri di query.
`[as24ci_search_filter]` invia i dati all'URL errato.	L'attributo `results_url` è mancante o punta a una pagina senza `[as24ci_archive]`.	Aggiungi `results_url="/cars/"` (o il percorso corretto) allo shortcode.