Documentazione · Guida all'integrazione

Guida al CSS personalizzato

Questo documento spiega come personalizzare l'aspetto visivo del plugin ADP Car Market Hub in modo sicuro utilizzando il CSS, quali approcci sono stabili tra gli aggiornamenti del plugin e come evitare sovrascritture che potrebbero interrompersi in caso di modifiche al plugin.

Quando utilizzare questo documento

Utilizza questo documento se stai:

Regolando colori, font, spaziatura o altri dettagli visivi sulle pagine dei veicoli oltre a quanto offerto dalle impostazioni in Car Market Hub → Design.
Aggiungendo correzioni responsive per dimensioni dello schermo specifiche.
Scrivendo regole CSS nel foglio di stile del tuo tema child destinate agli elementi del plugin.
Esaminando le sovrascritture CSS esistenti dopo un aggiornamento del plugin.

Inizia con Car Market Hub → Design prima di scrivere qualsiasi CSS personalizzato. Le impostazioni di Design coprono già i colori primari, i colori dei pulsanti, la tipografia (H1 / H2 / H3 / corpo), le dimensioni dei caratteri, il raggio del bordo e altro ancora. Il CSS personalizzato è necessario solo per le regolazioni che le impostazioni di Design non espongono.

Panoramica

Il plugin genera il suo CSS front-end in due punti:

Fogli di stile in coda. File CSS caricati tramite WordPress di wp_enqueue_style() nelle pagine dell'archivio veicoli, del singolo veicolo e di confronto. Questi file sono contrassegnati con il numero di versione del plugin e memorizzati nella cache dei browser.
Stili inline dinamici. Un blocco <style id="as24ci-dynamic-styles"> inserito in <head> con priorità wp_head 99. Questo blocco contiene dichiarazioni di proprietà personalizzate CSS (variabili) in :root e regole con ambito derivate dalle impostazioni di Design. Viene generato su ogni pagina del front-end.

Il modo consigliato per aggiungere CSS personalizzato è il campo CSS personalizzato in Car Market Hub → Design. Il contenuto di quel campo viene aggiunto al blocco di stili inline dinamici al termine del processo di compilazione, dopo tutte le altre regole generate dal plugin. Questo lo rende il posto più affidabile per le sovrascritture perché viene caricato sulla stessa pagina e nello stesso blocco <style>, dopo le regole che sta sovrascrivendo.

Un'opzione secondaria è il file style.css del tema child o il campo integrato CSS aggiuntivo di WordPress (Aspetto → Personalizza → CSS aggiuntivo). Questi vengono caricati come fogli di stile separati e la loro interazione con le dichiarazioni !important del plugin richiede attenzione (vedi sotto).

Prerequisiti

Accesso amministratore WordPress a Car Market Hub → Design.
Comprensione di base della specificità dei selettori CSS.
Un browser con strumenti di sviluppo per ispezionare le classi degli elementi e gli stili calcolati.

Comprendere la struttura CSS del plugin

Classi wrapper

Tutto l'output front-end del plugin è racchiuso in elementi che portano classi prevedibili. Queste classi sono i punti di aggancio stabili per il CSS personalizzato.

Classe	Applicata a	Presente su
`.as24ci-page`	Wrapper più esterno	Tutte le pagine del plugin e l'output degli shortcode
`.as24ci-page-classic`	Wrapper più esterno	Pagine del singolo veicolo
`.as24ci-archive-page`	Wrapper più esterno	Pagine dell'archivio veicoli e shortcode `[as24ci_archive]`
`.as24ci-page-inner`	Contenitore della larghezza del contenuto	Tutte le pagine del plugin
`.as24ci-archive-inner`	Contenitore del contenuto dell'archivio	Archivio veicoli
`.as24ci-archive-list`	Griglia o elenco dei veicoli	Archivio
`.as24ci-archive-row`	Singola scheda veicolo	Archivio
`.as24ci-card`	Pannello della scheda	Singolo veicolo

Definire l'ambito dei selettori sotto .as24ci-page garantisce che le regole non influiscano su altre parti della pagina.

Proprietà personalizzate CSS

Il plugin dichiara proprietà personalizzate CSS (variabili CSS) in :root per tutti i valori controllabili dal design. Queste sono impostate dalle impostazioni di Design e sono i punti di personalizzazione previsti. Puoi sovrascriverle nel campo CSS personalizzato:

:root {
  --as24ci-color-primary: #b22222;
  --as24ci-color-button: #b22222;
  --as24ci-border-radius: 4px;
}

Le sovrascritture delle proprietà personalizzate rappresentano l'approccio più stabile agli aggiornamenti perché funzionano indipendentemente dalla struttura HTML interna del plugin.

Specificità e `!important`

Alcune regole nel blocco CSS inline dinamico del plugin utilizzano !important per sovrascrivere in modo affidabile gli stili del tema attivo che si rivolgono agli stessi elementi (ad esempio, le regole per le intestazioni a livello di tema). Se hai bisogno di sovrascrivere una di queste regole dall'esterno del blocco dinamico (ad esempio da un foglio di stile del tema), potresti aver bisogno anche di !important. Il campo CSS personalizzato viene caricato all'interno dello stesso blocco dinamico e pertanto ha lo stesso contesto di specificità; nella maggior parte dei casi puoi sovrascrivere le regole del plugin da lì senza !important.

Istruzioni passo dopo passo

Utilizzo del campo CSS personalizzato (consigliato)

Vai su Car Market Hub → Design.
Scorri fino al campo CSS personalizzato (verifica l'etichetta esatta nella versione corrente del plugin).
Inserisci le tue regole CSS. Il campo accetta CSS standard; i tag HTML vengono rimossi prima dell'output.
Salva le impostazioni.
Svuota la cache della pagina e ricarica una pagina del veicolo per verificare.

Esempio: modifica del colore di sfondo della scheda del veicolo:

.as24ci-archive-row {
  background: #f9f9f9;
}

Esempio: regolazione della dimensione del carattere del prezzo in evidenza sulle pagine del singolo veicolo:

.as24ci-page-classic .as24ci-hero-price-value {
  font-size: 2rem;
}

Esempio: riduzione della larghezza del contenuto interno:

.as24ci-page-inner {
  width: min(1200px, calc(100% - 32px));
}

Utilizzo del foglio di stile del tema child

Se preferisci mantenere il CSS personalizzato nel controllo di versione insieme al tuo tema:

Apri il file style.css del tuo tema child (o un file custom.css dedicato incluso da functions.php).
Definisci l'ambito di tutti i selettori sotto .as24ci-page o una classe wrapper più specifica per evitare conflitti con il resto del sito.
Se una regola non ha effetto perché una regola del plugin con !important ha una specificità effettiva maggiore, prova ad aggiungere !important alla tua dichiarazione o utilizza invece il campo CSS personalizzato.

Convalida del comportamento responsive

Il CSS del plugin è progettato per essere responsive. Dopo aver aggiunto regole personalizzate, esegui un test ai seguenti breakpoint utilizzando gli strumenti di sviluppo del browser:

Desktop (≥ 1280 px): conferma il layout a griglia, l'allineamento della barra laterale dei filtri e la sezione hero.
Tablet (768 – 1279 px): conferma che l'archivio passi a una griglia più stretta e che il pannello dei filtri sia accessibile.
Mobile (< 768 px): conferma che le schede si impilino verticalmente, che le immagini si ridimensionino correttamente e che il modulo di contatto sia utilizzabile.

Presta particolare attenzione alle regole width, max-width, padding, margin e font-size che aggiungi: i valori in pixel assoluti che appaiono corretti su desktop possono compromettere il layout mobile.

Riferimento di configurazione

Impostazione di Design	Cosa controlla	Proprietà personalizzata impostata
Colore primario	Colore principale del brand utilizzato per le intestazioni e variabile CSS primaria	`--as24ci-color-primary`, `--as24ci-color-heading`
Colore di accento	Evidenziazione secondaria e colore del prezzo	`--as24ci-color-accent`, `--as24ci-color-price`
Colore del pulsante	Sfondo predefinito del pulsante	`--as24ci-color-button`
Colore del pulsante al passaggio del mouse	Sfondo del pulsante al passaggio del mouse	`--as24ci-color-button-hover`
Sfondo della scheda	Sfondo degli elementi scheda/pannello	`--as24ci-color-bg`
Raggio del bordo	Angoli arrotondati su schede e pulsanti	`--as24ci-border-radius`
Tipografia (H1 / H2 / H3 / Corpo)	Dimensione del carattere, spessore, altezza della riga e trasformazione del testo con ambito limitato a `.as24ci-page-classic`	Regole inline su `.as24ci-page-classic h1`, `.as24ci-page-classic h2`, ecc.
CSS personalizzato	CSS a forma libera aggiunto alla fine del blocco dinamico	N/D — aggiunto testualmente

Note operative

Stabilità degli aggiornamenti. I nomi delle classi e la struttura HTML nei template del plugin possono cambiare tra le versioni del plugin. I selettori CSS che si rivolgono a elementi profondamente annidati o a combinazioni di classi molto specifiche hanno maggiori probabilità di interrompersi dopo un aggiornamento. Utilizza le classi wrapper stabili più esterne (.as24ci-page, .as24ci-page-classic, .as24ci-archive-page) e le proprietà personalizzate CSS ove possibile.
Versioni dei fogli di stile in coda. I file CSS del plugin sono contrassegnati con il numero di versione del plugin (?ver=x.y.z). Dopo un aggiornamento del plugin, i browser richiedono automaticamente la nuova versione. I plugin di cache che ignorano le stringhe di query potrebbero servire un vecchio file CSS: svuota sia la cache della pagina che la cache della CDN dopo gli aggiornamenti.
Campo CSS personalizzato e tag HTML. Il campo CSS personalizzato passa il suo contenuto attraverso wp_strip_all_tags() prima dell'output. I tag HTML (inclusi <style>, <script> e </style>) vengono rimossi. Scrivi solo CSS semplice: non sono necessari wrapper HTML.
Evita di indirizzare selettori interni senza un ambito wrapper. Non scrivere mai una regola come .as24ci-title-main { color: red; } senza definirne l'ambito su .as24ci-page o .as24ci-page-classic. Una classe utilizzata all'interno del template del plugin potrebbe teoricamente corrispondere a elementi in altre parti della pagina se un altro plugin o tema utilizza lo stesso nome di classe.
Non modificare direttamente i file CSS del plugin. I file CSS all'interno di wp-content/plugins/adp-car-market-hub/templates/css/ vengono sovrascritti quando il plugin si aggiorna. Qualsiasi modifica apportata a tali file andrà persa. Utilizza invece il campo CSS personalizzato o il foglio di stile del tuo tema child.
Utilizzo di !important. Il plugin utilizza !important nelle sovrascritture tipografiche per garantire che abbiano effetto sugli stili di intestazione a livello di tema. Evita di utilizzare !important indiscriminatamente nel tuo CSS personalizzato: rende più difficile la manutenzione futura. Se hai bisogno di sovrascrivere una regola !important del plugin, prova prima ad aumentare la specificità del selettore.
Impostazioni tipografiche per pagina. La scheda Design include gruppi tipografici separati per le pagine del singolo veicolo, le pagine di archivio, i preferiti e le pagine di confronto. Queste impostazioni rappresentano il modo previsto per applicare una tipografia che differisce tra i tipi di pagina. Utilizzale prima di scrivere CSS personalizzato per lo stesso scopo.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa controllare
Il CSS personalizzato dal campo Design non ha alcun effetto visibile.	La cache della pagina sta servendo una vecchia versione della pagina.	Svuota la cache della pagina e la cache della CDN, quindi esegui un ricaricamento forzato della pagina.
Una regola nel foglio di stile del tema child non sovrascrive una regola del plugin.	La regola del plugin ha una dichiarazione `!important` o un selettore con specificità maggiore.	Aumenta la specificità della tua regola o spostala nel campo CSS personalizzato nel plugin (dove viene aggiunta dopo le regole del plugin stesso).
Il CSS personalizzato compromette il layout mobile.	Un valore fisso di `width` o `font-size` nel CSS personalizzato non si ridimensiona a larghezze di schermo ridotte.	Avvolgi la regola in una query `@media` o utilizza unità relative (`%`, `em`, `rem`, `vw`) invece di pixel assoluti.
Il blocco `as24ci-dynamic-styles` manca dal codice sorgente della pagina.	Un plugin di cache o di ottimizzazione HTML sta rimuovendo i blocchi `<style>` inline.	Inserisci `as24ci-dynamic-styles` nella whitelist nelle impostazioni del plugin di ottimizzazione o escludi le pagine del plugin dall'ottimizzazione.
Gli stili del campo CSS personalizzato appaiono nell'ordine errato.	Il CSS personalizzato viene aggiunto dopo tutte le altre regole del plugin nel blocco dinamico, quindi dovrebbe sempre prevalere a meno che un altro foglio di stile (caricato dopo `wp_head`) non lo sovrascriva.	Ispeziona la pagina con gli strumenti di sviluppo del browser per verificare l'ordine a cascata.