Catalogo PDF per PrestaShop — Guida completa

Presentazione

DFPDFCatalog pubblica i tuoi cataloghi PDF direttamente sul tuo negozio PrestaShop 8 o 9. Il modulo funziona in due modi complementari. Innanzitutto crea le proprie pagine di front office: una pagina vetrina che elenca tutti i cataloghi come banner cliccabili (/catalogues-pdf) e una pagina visualizzatore per catalogo (/catalogue-pdf/{id}-{slug}). Inoltre consente di integrare qualsiasi catalogo in qualsiasi pagina del tuo negozio, tramite uno shortcode, un widget Smarty o un iframe.

In entrambi i casi il PDF viene mostrato in un lettore integrato di livello professionale: modalità doppia pagina in stile rivista, miniature cliccabili, schermo intero, zoom, link cliccabili e testo selezionabile.

Installazione

1. Scarica il file ZIP del modulo dal tuo account DataFirefly.
2. Nel back office di PrestaShop vai su Moduli → Gestore moduli → Carica un modulo.
3. Seleziona il file dfpdfcatalog.zip e conferma.
4. Il modulo si installa automaticamente: tabelle del database, scheda di amministrazione e rotte di front vengono create senza alcuna configurazione manuale.

Dopo l’installazione compare una nuova scheda Cataloghi PDF nel menu Catalogo del back office.

Lo stesso archivio si installa su PrestaShop dalla 8.0 alla 8.2 e su PrestaShop 9.x. Non serve scaricare una versione diversa a seconda della generazione.

Aggiornamento da una versione precedente

1. Carica la nuova versione da Moduli → Gestore moduli → Carica un modulo (oppure sostituisci la cartella /modules/dfpdfcatalog/ via FTP).
2. Svuota la cache di PrestaShop: Parametri avanzati → Prestazioni → Svuota la cache.

L’aggiornamento preserva i cataloghi esistenti: le tabelle del database e i file caricati (banner e PDF) non vengono toccati. Passando alla 1.2.0, il modulo registra automaticamente gli hook necessari all’integrazione nelle pagine.

Aggiungere un catalogo

1. Vai su Catalogo → Cataloghi PDF e clicca su Aggiungi un catalogo.
2. Inserisci il titolo (traducibile per lingua). Serve anche a generare lo slug dell’URL e il meta title della pagina.
3. Inserisci la descrizione (traducibile). Viene mostrata nella pagina del visualizzatore e usata come meta description.
4. Carica l’immagine del banner. Compare nella griglia della pagina vetrina e funge da locandina di apertura quando il catalogo è integrato in una pagina.
5. Carica il file PDF.
6. Imposta la posizione (ordine di visualizzazione nella griglia) e lo stato attivo/inattivo.
7. In modalità multinegozio, seleziona i negozi in cui il catalogo deve comparire.
8. Salva: il catalogo è subito visibile su /catalogues-pdf.

Una volta salvato il catalogo, riaprilo: il modulo mostra un blocco Codici di integrazione con i quattro codici pronti da copiare per mostrarlo altrove nel tuo negozio. Clicca su un campo per selezionarlo.

Integrare un catalogo in una pagina

La pagina vetrina non va bene per ogni situazione. Per una landing page di settore, una pagina dedicata agli appalti pubblici o una categoria che deve presentare il proprio catalogo, puoi posizionare il visualizzatore esattamente dove vuoi.

Metodo consigliato: lo shortcode

Incolla questo marcatore nel contenuto della pagina, nel punto esatto in cui deve comparire il catalogo:

[dfpdfcatalog id="3"]

Sostituisci 3 con l’identificativo del catalogo, visibile nella colonna ID dell’elenco Catalogo → Cataloghi PDF. Lo shortcode funziona in:

• il contenuto delle pagine CMS;
• le descrizioni di categoria;
• le descrizioni di prodotto.

In questi tre contesti il modulo sostituisce il marcatore lato server, prima dell’invio della pagina. In tutti gli altri contesti (blocchi del tema, moduli di terze parti, page builder) un fallback JavaScript rileva il marcatore nella pagina e monta il visualizzatore nello stesso punto. Non c’è nulla da configurare: per il visitatore il risultato è identico.

Opzioni dello shortcode

• id — identificativo del catalogo. Obbligatorio.
• mode — click (predefinito) mostra prima una locandina costruita sul banner del catalogo e carica il visualizzatore solo al clic. inline mostra direttamente il visualizzatore, caricato all’avvicinarsi al viewport.
• height — altezza del visualizzatore in pixel. Per impostazione predefinita occupa l’80% dell’altezza dello schermo.
• title — testo mostrato sulla locandina di apertura. Per impostazione predefinita, il titolo del catalogo.

[dfpdfcatalog id="3" mode="inline" height="800"]

Widget Smarty in un template del tema

Per integrare un catalogo direttamente in un file .tpl del tuo tema:

{widget name='dfpdfcatalog' id_catalog=3 mode='inline'}

Questa sintassi funziona solo nei template. Il contenuto delle pagine CMS non viene interpretato da Smarty, quindi in quel caso usa lo shortcode.

Iframe, anche fuori da PrestaShop

Il modulo espone una pagina di integrazione priva di intestazione e piè di pagina del negozio, pronta da inserire in un iframe:

<iframe src="/catalogue-pdf-embed/3" width="100%" height="800" style="border:0;" loading="lazy"></iframe>

È il metodo da adottare per mostrare un catalogo su un sito esterno. Queste pagine di integrazione sono in noindex e non entrano quindi mai in concorrenza con le tue pagine reali nei risultati di ricerca. Tieni presente che l’altezza di un iframe è fissa: sul tuo negozio è preferibile lo shortcode, che si adatta al contenuto.

Più cataloghi nella stessa pagina

Puoi inserire tutti i cataloghi che vuoi nella stessa pagina. Ogni integrazione crea un visualizzatore indipendente, con i propri comandi di navigazione, il proprio zoom e la propria modalità di visualizzazione. Le scorciatoie da tastiera agiscono solo sul visualizzatore in uso, non su tutti contemporaneamente.

Il caricamento è ottimizzato proprio per questo scenario:

• in modalità click nessun PDF viene scaricato finché il visitatore non apre un catalogo;
• in modalità inline il caricamento parte all’avvicinarsi al viewport;
• la libreria di rendering e il foglio di stile vengono scaricati una sola volta per tutta la pagina, e solo se un catalogo è realmente presente.

Una pagina con otto cataloghi in modalità click carica quindi inizialmente solo otto immagini di banner.

Pagine di front office

Pagina vetrina

La pagina /catalogues-pdf mostra tutti i cataloghi attivi del negozio corrente come griglia di banner, ordinati per posizione. Ogni banner rimanda al visualizzatore del catalogo. La pagina genera il proprio meta title e la propria meta description e si integra nel breadcrumb nativo di PrestaShop.

Pagina del visualizzatore

Ogni catalogo ha la propria pagina /catalogue-pdf/{id}-{slug}. Il PDF viene mostrato nel visualizzatore integrato, con un pulsante per tornare alla vetrina e un pulsante di download diretto. Il PDF è servito da un controller PHP in visualizzazione inline, il che forza la visualizzazione nel browser. Le richieste HTTP Range sono supportate, quindi i cataloghi voluminosi si caricano progressivamente anziché in un’unica volta.

Usare il visualizzatore

Il visualizzatore si basa su PDF.js (Mozilla) e offre i seguenti comandi nella barra degli strumenti:

• Miniature — mostra o nasconde la barra laterale delle miniature delle pagine. Le miniature sono cliccabili e vengono generate man mano che si scorre (rendering differito), anche per cataloghi molto lunghi. La pagina o le pagine attive sono evidenziate.
• Doppia pagina — alterna tra visualizzazione pagina per pagina e modalità doppia pagina in stile rivista: copertina da sola, poi coppie 2-3, 4-5 e così via. Questa modalità è attiva per impostazione predefinita su schermi larghi almeno 1024 px.
• Navigazione — pulsanti precedente e successivo, indicatore di pagina (per esempio «Pagina 4-5 / 24» in modalità doppia pagina). Funzionano anche le frecce sinistra e destra della tastiera.
• Zoom — ingrandimento e riduzione a passi del 25% e pulsante di adattamento automatico alla larghezza.
• Schermo intero — porta il visualizzatore a schermo intero tramite l’API nativa del browser. Su iOS Safari viene usata automaticamente una modalità a schermo intero simulata. Il tasto Esc consente di uscire.

Gli hyperlink contenuti nel PDF restano cliccabili: i link esterni si aprono in una nuova scheda e i link interni (sommario, rimandi) navigano direttamente nel visualizzatore. Se il PDF contiene un livello di testo, il testo è selezionabile, copiabile e la ricerca Ctrl+F del browser funziona sul contenuto.

Il rendering usa la densità di pixel dello schermo (HiDPI): le pagine sono nitide su schermi Retina e 4K.

SEO e URL

Il modulo dichiara le sue rotte tramite l’hook moduleRoutes di PrestaShop:

• /catalogues-pdf — pagina vetrina, con meta title e meta description dedicati.
• /catalogue-pdf/{id}-{slug} — un URL pulito per catalogo, dove lo slug è generato automaticamente dal titolo. Il meta title riprende il titolo del catalogo e la meta description la sua descrizione.
• /catalogue-pdf-embed/{id} — pagina di integrazione destinata agli iframe, in noindex.

Non serve creare alcuna pagina CMS: le rotte sono registrate automaticamente all’installazione.

Multilingua e multinegozio

Titoli e descrizioni si traducono campo per campo nel modulo di modifica (selettore di lingua standard di PrestaShop). Ogni lingua genera il proprio slug e i propri meta. In modalità multinegozio l’associazione catalogo/negozio si gestisce con caselle di spunta: ogni negozio mostra solo i cataloghi che gli sono assegnati. Questo filtro si applica anche all’accesso diretto tramite URL e alle integrazioni nelle pagine: un catalogo non assegnato al negozio corrente non viene mai servito lì.

Risoluzione dei problemi

Lo shortcode compare come testo semplice nella pagina

• Verifica che l’identificativo corrisponda a un catalogo esistente, attivo e assegnato al negozio corrente. Un identificativo sconosciuto lascia il marcatore intatto invece di mostrare un visualizzatore vuoto.
• Verifica che il catalogo contenga effettivamente un file PDF.
• Svuota la cache di PrestaShop, poi ricarica la pagina in una finestra privata.
• Se hai appena aggiornato il modulo, disinstallalo e reinstallalo per forzare la registrazione degli hook di integrazione.

Il PDF non viene visualizzato

• Verifica che il file PDF sia stato caricato correttamente (riapri il catalogo nel back office).
• Svuota la cache di PrestaShop e ricarica la pagina in una finestra privata.
• Se nel visualizzatore compare un messaggio di errore, viene proposto in alternativa un link di download diretto del PDF.

Il testo non è selezionabile o Ctrl+F non trova nulla

La selezione del testo richiede che il PDF contenga un livello di testo. I PDF scansionati o esportati come puro bitmap non lo contengono: in quel caso è possibile solo la visualizzazione grafica. Passa il documento attraverso uno strumento di OCR se ti serve il testo.

I link del PDF non sono cliccabili

I link devono essere vere annotazioni di collegamento all’interno del PDF (create dallo strumento di esportazione: InDesign, Word, LibreOffice e simili). Un testo che assomiglia a un URL ma privo di annotazione non sarà cliccabile.

Le pagine appaiono allungate o sfocate

Questo problema della versione 1.0.0 è risolto dalla versione 1.0.1 (rendering HiDPI e neutralizzazione dei reset CSS dei temi). Aggiorna il modulo e svuota la cache di PrestaShop.

Cronologia delle versioni

• 1.2.0 (2026-08-10) — Integrazione di un catalogo in qualsiasi pagina tramite shortcode, widget Smarty o iframe; sostituzione lato server nelle pagine CMS, nelle categorie e nelle schede prodotto, con fallback JavaScript; visualizzatore riscritto in istanze indipendenti (più cataloghi per pagina); caricamento differito; codici di integrazione pronti da copiare nel back office; supporto delle richieste HTTP Range.
• 1.1.0 (2026-08-10) — Compatibilità con PrestaShop 9; correzione dell’associazione al negozio nel modulo di modifica; filtro per negozio applicato all’accesso diretto tramite URL; verifica del contenuto reale dei file caricati.
• 1.0.4 (2026-05-11) — Modalità schermo intero (API nativa più fallback per iOS Safari); correzione dell’adattamento alla larghezza della copertina in modalità doppia pagina; evidenziazione dei pulsanti attivi.
• 1.0.3 (2026-05-11) — Modalità doppia pagina in stile rivista (copertina da sola, poi 2-3, 4-5…); attivazione automatica su schermi larghi; annullamento pulito dei rendering durante le navigazioni rapide.
• 1.0.2 (2026-05-11) — Barra laterale di miniature cliccabili con rendering differito; livello testo (selezione e Ctrl+F); pulsante di visualizzazione delle miniature.
• 1.0.1 (2026-05-11) — Rendering HiDPI nitido su Retina e 4K; link del PDF cliccabili (livello annotazioni); correzione dell’allungamento verticale delle pagine.
• 1.0.0 (2026-05-08) — Versione iniziale: pagina vetrina, visualizzatore integrato, URL SEO, multilingua, multinegozio.