Blocco Gutenberg per PDF: come gestire e mostrare documenti in WordPress
Gestire un PDF in WordPress è semplice. Gestirne venti, trenta o magari un archivio che cambia continuamente è un’altra storia.
Un regolamento, un catalogo, una scheda tecnica, un listino, della documentazione da scaricare: per un singolo file bastano gli strumenti già presenti in WordPress. Quando però i documenti aumentano, nasce un problema molto più concreto: come organizzarli e mostrarli senza costruire ogni volta la pagina a mano?
È proprio da questa esigenza che ho sviluppato DB Solution – PDF, un blocco Gutenberg per creare raccolte di documenti PDF in WordPress, gestendole manualmente oppure alimentandole dinamicamente tramite ACF.
Non volevo creare l’ennesimo pulsante “Scarica PDF”. Quello WordPress sa già farlo.
Volevo qualcosa di più utile.
Perché un blocco Gutenberg dedicato ai PDF?
WordPress dispone già del blocco File e, per esigenze semplici, va benissimo.
Il problema arriva quando una pagina deve contenere una vera raccolta di documenti.
Pensiamo, ad esempio, a:
- documentazione aziendale;
- cataloghi e listini;
- regolamenti;
- modulistica;
- manuali e schede tecniche;
- documenti associati dinamicamente a prodotti, servizi o contenuti;
- aree download che devono essere aggiornate nel tempo.
In questi casi non basta più inserire un PDF.
Serve un sistema per organizzare i documenti, presentarli in maniera coerente e soprattutto evitare di ricostruire tutto ogni volta che cambia un file.
DB Solution – PDF: un blocco Gutenberg pensato per le raccolte di documenti
DB Solution – PDF permette di creare direttamente nell’editor Gutenberg una raccolta di PDF.
Il principio è volutamente semplice: aggiungo il blocco, scelgo da dove devono arrivare i documenti e decido come presentarli.
Posso lavorare in due modi:
manualmente, scegliendo i PDF dalla Media Library di WordPress;
oppure dinamicamente, recuperandoli da un campo ACF Repeater.
Ed è soprattutto questa seconda possibilità che rende il blocco interessante nei progetti WordPress più strutturati.
Gestione manuale direttamente da Gutenberg
Se non ho bisogno di contenuti dinamici, posso utilizzare DB Solution – PDF come un normale blocco Gutenberg.
Aggiungo i documenti dalla Media Library di WordPress e posso gestire per ciascuno titolo e descrizione, decidere se mostrare anteprima e download, sostituire il documento, duplicarlo, eliminarlo oppure modificarne l’ordine.
La gestione dei documenti avviene direttamente nel blocco.
Ho preferito questa soluzione per una ragione abbastanza pratica: quando i PDF iniziano a essere numerosi, riempire la barra laterale di Gutenberg con decine di controlli diventa rapidamente scomodo.
La sidebar rimane quindi dedicata alle impostazioni generali, mentre i documenti si gestiscono dove effettivamente li sto vedendo.
PDF dinamici in WordPress con ACF Repeater
Questa è probabilmente la funzione che personalmente considero più interessante.
DB Solution – PDF può utilizzare un ACF Repeater come sorgente dei documenti.
Immaginiamo una struttura ACF composta da:
documenti_pdf
- titolo
- descrizione
Ogni volta che aggiungo un elemento al Repeater, il documento può comparire automaticamente nella raccolta PDF mostrata nella pagina.
Non devo tornare nel layout, duplicare blocchi o aggiornare manualmente i collegamenti.
Aggiorno il contenuto e cambia anche la raccolta.
Il plugin permette inoltre di configurare i nomi dei campi, quindi non obbliga a utilizzare una struttura ACF prestabilita.
Il campo File può restituire l’attachment ID, l’array del file oppure il relativo URL.
E c’è una piccola comodità in più: se non specifico il nome del Repeater, il plugin può provare a individuare automaticamente il primo Repeater popolato che contiene un campo PDF.
ACF è obbligatorio?
No.
Era importante per me mantenere separate le due cose.
DB Solution – PDF funziona anche senza Advanced Custom Fields.
ACF diventa semplicemente una sorgente aggiuntiva quando voglio realizzare raccolte documentali dinamiche.
Per un normale sito WordPress posso continuare a selezionare i documenti dalla Media Library e utilizzare il blocco senza installare ACF.
Lista o griglia: i PDF non devono per forza essere brutti
C’è poi l’aspetto visivo.
Gli archivi di documenti hanno spesso quell’inconfondibile aspetto da “pagina download del 2008”: una sequenza infinita di link blu, magari accompagnati da un’icona PDF.
Funziona, certo.
Ma possiamo fare qualcosa di meglio.
DB Solution – PDF permette di scegliere tra layout a lista e layout a griglia, adattando inoltre il numero di colonne per desktop, tablet e smartphone.
Ogni documento può mostrare:
- icona PDF;
- titolo;
- descrizione;
- dimensione del file;
- azione di anteprima;
- pulsante per il download.
Il risultato è una raccolta che rimane leggibile anche quando i documenti iniziano a diventare parecchi.
E soprattutto è responsive, quindi non devo creare una seconda soluzione solo per il mobile.
Non tutti i PDF devono essere trattati allo stesso modo.
Un utente potrebbe voler semplicemente consultare un documento senza scaricarlo, mentre in altri casi il download è esattamente l’azione che vogliamo mettere in evidenza.
Per questo ogni documento può avere anteprima e download, e le due azioni possono essere gestite separatamente.
Posso quindi costruire una raccolta più adatta al tipo di contenuto che sto pubblicando invece di imporre lo stesso comportamento a qualsiasi PDF.
Ho voluto mantenere il plugin utilizzabile anche fuori dal blocco Gutenberg.
DB Solution – PDF mette infatti a disposizione lo shortcode:
[dbsopd_pdf]
Questo permette di richiamare le raccolte anche all’interno di page builder, widget, template o altre aree di WordPress che supportano gli shortcode.
Per esempio, posso indicare direttamente gli allegati:
[dbsopd_pdf ids="123,456" heading="Documenti" layout="list"]
Oppure utilizzare ACF come sorgente:
[dbsopd_pdf source="acf"]
Posso anche specificare il Repeater e i relativi sottocampi:
[dbsopd_pdf source="acf" field="documenti_pdf" pdf_subfield="pdf" title_subfield="titolo" description_subfield="descrizione"]
C’è anche la possibilità di leggere i documenti da un’altra pagina o da un altro post, indicandone ID, slug o URL.
Questo apre scenari interessanti: una raccolta può essere gestita in un unico punto di WordPress e richiamata dove serve.
Questa parte è meno visibile, ma per me era importante.
Non volevo avere una versione del componente per Gutenberg e un’altra completamente diversa per gli shortcode.
Il rendering è condiviso.
Significa che l’obiettivo è mantenere lo stesso risultato sul frontend indipendentemente dal modo in cui la raccolta viene inserita.
In Gutenberg posso inoltre vedere lo shortcode equivalente alla configurazione del blocco, utile quando voglio riutilizzare la stessa impostazione altrove.
Anche tecnicamente ho cercato di mantenere DB Solution – PDF il più vicino possibile a WordPress.
Il plugin utilizza le API native, block.json, rendering server-side e la Media Library.
Non richiede framework frontend come Bootstrap o Tailwind e non introduce jQuery solo per far funzionare il componente.
L’idea è semplice: se sto sviluppando un blocco WordPress, preferisco utilizzare WordPress prima di aggiungere altre dipendenze.
Non credo serva installare un plugin per qualsiasi cosa.
Se devo pubblicare un solo PDF in una pagina, probabilmente utilizzerò semplicemente il blocco File di WordPress.
DB Solution – PDF nasce invece quando la richiesta diventa:
“Devo gestire una raccolta di documenti.”
E diventa ancora più interessante quando quella frase diventa:
“Questi documenti devono cambiare automaticamente in base al contenuto della pagina.”
È lì che l’integrazione tra Gutenberg, PDF e ACF Repeater comincia ad avere davvero senso.
Molti dei plugin che sviluppo partono nello stesso modo: non da una lista di funzionalità da aggiungere a WordPress, ma da qualcosa che durante un progetto reale mi fa pensare:
“Possibile che per fare questa cosa debba complicarmi così tanto la vita?”
DB Solution – PDF nasce con questa filosofia.
Un blocco Gutenberg per chi deve pubblicare PDF.
Una raccolta ordinata quando i documenti diventano tanti.
ACF quando devono diventare dinamici.
Uno shortcode quando Gutenberg non è il posto in cui devo utilizzarli.
Niente rivoluzioni. Semplicemente un modo più comodo per gestire e mostrare PDF in WordPress.
DB Solution – PDF
Blocco Gutenberg per creare raccolte PDF responsive, manuali o dinamiche tramite ACF Repeater.
Sviluppato da Davide Baraldi come parte della suite DB Solution.