{"id":167172,"date":"2025-06-30T09:00:00","date_gmt":"2025-06-30T09:00:00","guid":{"rendered":"https:\/\/gtechgroup.it\/blog\/acf-gutenberg-blocchi-custom-campi\/"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T22:00:00","slug":"acf-gutenberg-blocchi-custom-campi","status":"publish","type":"post","link":"https:\/\/gtechgroup.it\/blog\/acf-gutenberg-blocchi-custom-campi\/","title":{"rendered":"ACF e Gutenberg: Blocchi Custom con Campi Personalizzati"},"content":{"rendered":"

ACF e Gutenberg: L’Integrazione che Conta<\/h2>\n

L’editor a blocchi di WordPress, conosciuto come Gutenberg<\/strong>, ha trasformato radicalmente il modo in cui i contenuti vengono creati e gestiti in WordPress. Dalla sua introduzione con WordPress 5.0, Gutenberg è diventato l’editor predefinito e il futuro della piattaforma. Per gli sviluppatori che utilizzano ACF, la domanda chiave è stata: come integrare i campi personalizzati con il nuovo paradigma dei blocchi? La risposta di ACF è stata brillante: la creazione di ACF Blocks<\/strong>, una funzionalità che permette di registrare blocchi Gutenberg personalizzati utilizzando i familiari campi ACF e i template PHP, senza dover scrivere una singola riga di React o JavaScript.<\/p>\n

I blocchi ACF rappresentano il ponte perfetto tra il mondo dei campi personalizzati e il mondo dell’editor a blocchi. Permettono di creare blocchi con un’interfaccia di editing basata sui campi ACF (che gli utenti già conoscono) e un’anteprima in tempo reale nell’editor Gutenberg (che migliora enormemente l’esperienza utente rispetto al Flexible Content tradizionale). In questo articolo vedremo come registrare e configurare i blocchi ACF, come creare i template di rendering e come gestire gli aspetti avanzati di questa integrazione.<\/p>\n

Come Funzionano i Blocchi ACF<\/h2>\n

I blocchi ACF funzionano in modo fondamentalmente diverso dai blocchi Gutenberg nativi. I blocchi nativi sono costruiti con React e salvano il loro contenuto direttamente nel post_content come HTML commentato. I blocchi ACF, invece, sono costruiti con PHP<\/strong> e salvano i dati come metadati<\/strong> del post (nella tabella wp_postmeta), esattamente come qualsiasi altro campo ACF. Il rendering del blocco avviene lato server tramite un template PHP, sia nell’editor (come anteprima) sia nel frontend.<\/p>\n

Questa architettura ha vantaggi significativi. Non devi imparare React per creare blocchi personalizzati: se sai usare ACF e scrivere template PHP, sai già tutto il necessario. I dati dei blocchi sono accessibili tramite le funzioni standard di ACF (get_field()<\/code>, the_field()<\/code>), rendendoli compatibili con le query WP e i tool di migrazione esistenti. L’anteprima nell’editor è generata dallo stesso template PHP usato nel frontend, garantendo una corrispondenza perfetta tra ciò che l’utente vede nell’editor e ciò che appare sul sito.<\/p>\n

\"Gestione<\/p>\n

Registrare un Blocco ACF<\/h2>\n

La registrazione di un blocco ACF avviene tramite la funzione acf_register_block_type()<\/code> nel file functions.php<\/code> del tema. Ecco un esempio completo di registrazione di un blocco “Testimonial”:<\/p>\n

<?php\nadd_action(acf\/init, registra_blocchi_acf);\nfunction registra_blocchi_acf() {\n    if( function_exists(acf_register_block_type) ) {\n\n        acf_register_block_type(array(\n            name              => testimonial,\n            title             => Testimonial,\n            description       => Blocco per mostrare una testimonianza cliente.,\n            render_template   => template-parts\/blocks\/testimonial.php,\n            category          => formatting,\n            icon              => format-quote,\n            keywords          => array(testimonial, citazione, recensione),\n            mode              => preview,\n            supports          => array(\n                align => true,\n                mode  => true,\n            ),\n        ));\n    }\n}\n?><\/code><\/pre>\n
I parametri principali sono: name<\/strong> (identificativo univoco del blocco, senza spazi), title<\/strong> (nome visibile nell’inseritore di blocchi), description<\/strong> (descrizione mostrata nel pannello di dettaglio), render_template<\/strong> (percorso del file PHP per il rendering), category<\/strong> (categoria nell’inseritore di blocchi), icon<\/strong> (icona Dashicons o SVG personalizzata) e keywords<\/strong> (parole chiave per la ricerca nell’inseritore).<\/p>\n
Il parametro mode<\/strong> è particolarmente importante: preview<\/code> mostra l’anteprima del blocco nell’editor con i campi ACF nel pannello laterale; edit<\/code> mostra i campi ACF inline nel blocco; auto<\/code> alterna automaticamente tra preview e edit in base all’interazione dell’utente. Il modo preview<\/code> è generalmente il più apprezzato perché offre la migliore esperienza visuale.<\/p>\n
Creare il Template di Rendering<\/h2>\n
Il template di rendering è un file PHP standard che utilizza le funzioni ACF per recuperare e visualizzare i valori dei campi. Crea il file template-parts\/blocks\/testimonial.php<\/code> nel tuo tema:<\/p>\n
<?php\n$nome = get_field(nome_cliente);\n$ruolo = get_field(ruolo);\n$citazione = get_field(citazione);\n$foto = get_field(foto_cliente);\n\n\/\/ Supporto per classi CSS e allineamento\n$className = testimonial-block;\nif( !empty($block[className]) ) {\n    $className .=   . $block[className];\n}\nif( !empty($block[align]) ) {\n    $className .=  align . $block[align];\n}\n?>\n\n<div class=\"<?php echo esc_attr($className); ?>\">\n    <?php if($foto): ?>\n        <img class=\"testimonial-photo\"\n             src=\"<?php echo esc_url($foto[sizes][thumbnail]); ?>\"\n             alt=\"<?php echo esc_attr($foto[alt]); ?>\" \/>\n    <?php endif; ?>\n\n    <?php if($citazione): ?>\n        <blockquote><?php echo wp_kses_post($citazione); ?><\/blockquote>\n    <?php endif; ?>\n\n    <div class=\"testimonial-author\">\n        <?php if($nome): ?>\n            <strong><?php echo esc_html($nome); ?><\/strong>\n        <?php endif; ?>\n        <?php if($ruolo): ?>\n            <span><?php echo esc_html($ruolo); ?><\/span>\n        <?php endif; ?>\n    <\/div>\n<\/div><\/code><\/pre>\n
\"Configurazione<\/p>\n
Nota come il template accede alla variabile $block<\/code>, che è un array automaticamente disponibile nei template dei blocchi ACF contenente informazioni sul blocco corrente: nome, ID univoco, classi CSS personalizzate, allineamento e altre proprietà. Questa variabile ti permette di gestire le opzioni di blocco standard di Gutenberg (allineamento, classi aggiuntive) senza codice aggiuntivo.<\/p>\n
Associare i Campi al Blocco<\/h2>\n
Dopo aver registrato il blocco, devi creare un gruppo di campi ACF e associarlo al blocco tramite le Location Rules. Vai su ACF > Field Groups<\/strong>, crea un nuovo gruppo e nella sezione Location imposta la regola: Block è uguale a Testimonial<\/strong> (o il nome del tuo blocco). Aggiungi i campi che il blocco utilizzerà: nel nostro esempio, un campo Text “Nome Cliente”, un campo Text “Ruolo”, un campo Text Area “Citazione” e un campo Image “Foto Cliente”.<\/p>\n
Quando l’utente inserisce il blocco nell’editor Gutenberg, i campi ACF appaiono nel pannello laterale (in modalità preview) o direttamente nel blocco (in modalità edit). L’utente compila i campi e il blocco mostra immediatamente l’anteprima renderizzata dal template PHP. Questa esperienza è superiore sia al Classic Editor con ACF tradizionale (dove non c’è anteprima) sia ai blocchi Gutenberg nativi (dove serve React per lo sviluppo).<\/p>\n
Stili CSS per i Blocchi ACF<\/h2>\n
Per applicare stili CSS ai blocchi ACF, puoi utilizzare diversi approcci. Il più semplice è aggiungere gli stili nel foglio di stile principale del tema (style.css<\/code>), utilizzando la classe base del blocco come selettore. Un approccio più modulare è specificare un foglio di stile dedicato per ogni blocco tramite il parametro enqueue_style<\/code> nella registrazione:<\/p>\n
acf_register_block_type(array(\n    name          => testimonial,\n    title         => Testimonial,\n    render_template => template-parts\/blocks\/testimonial.php,\n    enqueue_style => get_template_directory_uri() . \/css\/blocks\/testimonial.css,\n    \/\/ ... altri parametri\n));<\/code><\/pre>\n
Il vantaggio di enqueue_style<\/code> è che il CSS viene caricato solo nelle pagine che effettivamente utilizzano il blocco, ottimizzando le performance. Lo stesso vale per enqueue_script<\/code> se il blocco necessita di JavaScript (ad esempio, per uno slider o un’animazione). Entrambi i file vengono automaticamente caricati sia nel frontend sia nell’editor Gutenberg, garantendo la coerenza visiva tra anteprima e risultato finale.<\/p>\n
Funzionalità Avanzate: InnerBlocks e JSX<\/h2>\n
I blocchi ACF supportano InnerBlocks<\/strong>, una funzionalità di Gutenberg che permette di annidare altri blocchi all’interno del tuo blocco personalizzato. Per abilitare InnerBlocks, aggiungi il supporto nella registrazione del blocco e inserisci il tag <InnerBlocks \/><\/code> nel template:<\/p>\n
\/\/ Nella registrazione:\nsupports => array(\n    jsx => true, \/\/ Abilita il rendering JSX per InnerBlocks\n),\n\n\/\/ Nel template PHP:\n<div class=\"my-block\">\n    <h2><?php the_field(titolo); ?><\/h2>\n    <InnerBlocks \/>\n<\/div><\/code><\/pre>\n
InnerBlocks è potente per creare blocchi “contenitore” come sezioni con sfondo personalizzato, colonne con stile specifico o card con header ACF e contenuto libero. L’utente può inserire qualsiasi blocco Gutenberg (paragrafi, immagini, liste, video) nell’area InnerBlocks, mentre i campi ACF gestiscono le proprietà del contenitore.<\/p>\n
\"Strumenti<\/p>\n
Gestire la Modalità Preview ed Edit<\/h2>\n
Il parametro mode<\/code> nella registrazione del blocco controlla il comportamento predefinito, ma l’utente può alternare tra le modalità in qualsiasi momento (se il supporto mode => true<\/code> è attivo). In modalità Preview<\/strong>, il blocco mostra l’anteprima renderizzata dal template PHP e i campi ACF appaiono nel pannello laterale dell’editor. In modalità Edit<\/strong>, i campi ACF vengono mostrati inline nel blocco, sostituendo l’anteprima.<\/p>\n
La modalità Preview è ideale per blocchi visivamente complessi dove l’anteprima è importante (hero banner, card, testimonial). La modalità Edit è preferibile per blocchi semplici con pochi campi dove l’editing inline è più veloce. Puoi anche gestire programmaticamente il comportamento del blocco quando non ha ancora dati: mostrando un placeholder o un messaggio di istruzione quando i campi sono vuoti.<\/p>\n
<?php if( empty(get_field(titolo)) && empty(get_field(contenuto)) ): ?>\n    <div class=\"block-placeholder\">\n        <p>Compila i campi nel pannello laterale per configurare questo blocco.<\/p>\n    <\/div>\n<?php else: ?>\n    <!-- Rendering normale del blocco -->\n<?php endif; ?><\/code><\/pre>\n
Blocchi ACF con block.json (WordPress 6.x)<\/h2>\n
A partire da ACF PRO 6.0 e WordPress 6.x, i blocchi ACF possono essere registrati anche tramite file block.json<\/code>, seguendo la convenzione moderna di WordPress per la registrazione dei blocchi. Questo approccio è più strutturato e allineato con le best practice dell’ecosistema Gutenberg:<\/p>\n
\/\/ acf-blocks\/testimonial\/block.json\n{\n    \"name\": \"acf\/testimonial\",\n    \"title\": \"Testimonial\",\n    \"description\": \"Blocco testimonianza cliente\",\n    \"category\": \"formatting\",\n    \"icon\": \"format-quote\",\n    \"keywords\": [\"testimonial\", \"citazione\"],\n    \"acf\": {\n        \"mode\": \"preview\",\n        \"renderTemplate\": \"acf-blocks\/testimonial\/render.php\"\n    },\n    \"supports\": {\n        \"align\": true\n    }\n}<\/code><\/pre>\n
I blocchi registrati con block.json beneficiano del caricamento automatico degli asset (CSS e JS) e di una migliore integrazione con gli strumenti di sviluppo di WordPress. Questo metodo è consigliato per i nuovi progetti, mentre l’approccio PHP tradizionale resta pienamente supportato per la retrocompatibilità.<\/p>\n
Best Practice per i Blocchi ACF<\/h2>\n
Per ottenere il massimo dai blocchi ACF, segui queste best practice consolidate. Organizza i file dei blocchi in una struttura coerente, ad esempio acf-blocks\/nome-blocco\/<\/code> con render.php, style.css e block.json nella stessa cartella. Usa nomi di blocco descrittivi e prefissati per evitare conflitti con altri plugin. Testa sempre i blocchi sia nell’editor che nel frontend, verificando che l’anteprima corrisponda al risultato finale.<\/p>\n
Gestisci i casi limite: cosa succede quando un campo è vuoto? Cosa succede quando un’immagine è stata cancellata dalla libreria media? Il template deve gestire questi scenari senza errori PHP o output HTML rotto. Usa sempre l’escaping appropriato per tutti i valori e fornisci stati di fallback per ogni campo critico. Infine, documenta i blocchi che crei, specialmente se lavori in team: una breve descrizione dei campi e del comportamento atteso facilita enormemente la manutenzione futura.<\/p>\n
\n
Leggi anche gli altri articoli della serie ACF<\/h3>\n