Documentazione · Documentazione tecnica

Note tecniche sulla generazione di PDF

Questo documento descrive come il plugin ADP Car Market Hub produce schede tecniche dei veicoli ottimizzate per la stampa ("exposés") che i visitatori possono salvare come PDF utilizzando la finestra di dialogo di stampa del proprio browser.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

Personalizzare quali campi appaiono sulla scheda tecnica stampabile.
Sostituire la sorgente predefinita dell'immagine del codice QR con un generatore ospitato autonomamente (self-hosted).
Incorporare un link alla scheda tecnica stampabile di un veicolo da un'altra pagina o sistema.
Diagnosticare dati mancanti o errati sulla pagina stampabile.

Panoramica

La scheda tecnica in PDF è implementata in AS24CI\Pdf_Datasheet. Essa non genera un PDF binario sul server. Al contrario, effettua il rendering di una pagina HTML autonoma (senza l'intestazione/piè di pagina del tema WordPress) ottimizzata per la funzione Stampa → Salva come PDF del browser.

Questo approccio ha due implicazioni pratiche:

L'output appare identico indipendentemente dal tema attivo, poiché il tema viene bypassato.
Il browser gestisce l'effettivo rendering del PDF. Il visitatore (o il team della concessionaria) crea il PDF localmente; il server si limita a fornire l'HTML.

Trigger e routing

La classe registra la variabile di query pubblica as24ci_pdf.
Un'azione template_redirect rimane in ascolto della variabile. Quando è presente e si risolve in un articolo as24ci_car pubblicato, il plugin esegue il rendering della scheda tecnica e chiama exit.
L'helper URL Pdf_Datasheet::get_datasheet_url( $post_id ) restituisce home_url( '/?as24ci_pdf=<post_id>' ). Utilizza questo helper anziché costruire l'URL manualmente.

Regole di convalida:

Gli ID non numerici o pari a zero restituiscono HTTP 400 con un messaggio tradotto "ID veicolo non valido".
Articolo mancante, tipo di articolo errato o stato non pubblicato restituiscono HTTP 404 con un messaggio tradotto "Veicolo non trovato o non pubblicato".

Selezione dei campi

Pdf_Datasheet::get_allowed_fields() è la whitelist autorevole dei campi che possono apparire sulla scheda tecnica. Qualsiasi campo non presente nell'elenco viene ignorato, in modo che gli amministratori non possano mostrare dati non supportati manipolando le impostazioni salvate.

Campi attualmente consentiti:

title, price, mileage, first_reg, fuel_type, transmission, power, body_type, exterior_color, doors, seats, emission_class, co2, consumption, equipment, description, location, contact.

I valori predefiniti sono esposti da get_default_settings() e sovrapposti alle impostazioni persistenti del PDF Manager dell'utente, in modo che i campi aggiunti di recente ricevano un valore predefinito sensato.

Codice QR

Pdf_Datasheet::get_qr_image_url( $target_url ) restituisce un URL dell'immagine QR per l'incorporamento nella scheda tecnica. L'implementazione predefinita richiede un PNG 180×180 dal servizio pubblico goqr.me (https://api.qrserver.com/v1/create-qr-code/).

Dettagli operativi:

Una guardia difensiva restituisce una stringa vuota se l'URL di destinazione contiene autoscout24. in modo che il codice QR non rimandi mai accidentalmente alla pagina di dettaglio dell'annuncio di origine.
L'URL predefinito è filtrabile tramite as24ci_pdf_qr_image_url. Restituisci una stringa vuota per sopprimere interamente l'immagine QR, oppure restituisci il tuo URL personalizzato (self-hosted).

Istruzioni passo dopo passo

Per visualizzare l'anteprima di una scheda tecnica stampabile per un veicolo:

Individua il veicolo nell'amministrazione di WordPress o sul frontend.
Apri l'URL https://example.com/?as24ci_pdf=<post_id> in un browser.
Utilizza la finestra di dialogo di stampa del browser (Ctrl/Cmd + P) per salvare la pagina come PDF o inviarla a una stampante.

Per personalizzare i campi visibili:

Apri la scheda di amministrazione PDF Manager.
Attiva o disattiva i campi e le opzioni di branding (logo, azienda, indirizzo, telefono, ecc.).
Salva. Le impostazioni vengono salvate nelle opzioni di WordPress e unite ai valori predefiniti al momento del rendering.

Per sostituire il fornitore del QR con un generatore self-hosted:

Aggiungi un piccolo mu-plugin o uno snippet del tema che si agganci a as24ci_pdf_qr_image_url, ignori il valore predefinito e restituisca il tuo URL.
Verifica il risultato in un browser prima di distribuirlo in produzione.

Riferimento di configurazione

Whitelist dei campi: vedi get_allowed_fields() sopra. Valori predefiniti: vedi get_default_settings(). L'elenco esatto delle opzioni di branding e di layout esposte nella scheda di amministrazione PDF Manager è gestito lato server. Verifica le opzioni correnti rispetto alla schermata del PDF Manager prima di pubblicare la documentazione rivolta ai clienti.

Note operative

Il renderer restituisce HTML completo (inclusi <!DOCTYPE>, <head>, stili inline) e chiama exit per impedire a WordPress di inviare il suo tema. Qualsiasi plugin che si agganci tardi in template_redirect e scriva nella risposta dopo questo punto non verrà eseguito.
Poiché il PDF viene generato lato client dal browser, la numerazione delle pagine, le intestazioni/piè di pagina e le dimensioni della carta dipendono dalle impostazioni di stampa del visitatore, non dal plugin.
L'immagine QR viene recuperata dal browser del visitatore (o dal motore di stampa), non dal server WordPress. Se la tua politica sulla privacy vieta le richieste di terze parti nei documenti stampabili, sovrascrivi l'URL del QR o sopprimilo interamente tramite il filtro.
L'endpoint restituisce una pagina HTML pubblica; non incorporare dati riservati nei campi configurabili.

Risoluzione dei problemi

Pagina 404 invece della scheda tecnica — l'articolo non esiste, non è del tipo di articolo as24ci_car o non è publish. Verifica l'ID e lo stato dell'articolo.
400 "ID veicolo non valido" — il valore passato in ?as24ci_pdf= non era un numero intero positivo.
Gli stili del tema si riversano nella pagina stampabile — il renderer bypassato il tema; se vedi il markup del tema, un altro plugin sta intercettando template_redirect prima di questo o l'URL non è stato rilevato. Ricontrolla il parametro URL e svuota le cache della pagina.
Il codice QR è mancante o non funzionante — l'URL di destinazione conteneva autoscout24. (soppresso per sicurezza) o un filtro personalizzato ha restituito una stringa vuota. Verifica l'URL di destinazione e l'implementazione del filtro.
Il PDF differisce tra i browser — il rendering di stampa varia tra i diversi browser e sistemi operativi. Standardizza su un unico browser/sistema operativo per le esportazioni rivolte ai clienti se il layout preciso è importante.