Chi Siamo Area Clienti Promo del Mese Dicono di Noi Portfolio FAQ Blog
Contattaci
Senza categoria

ACF e Gutenberg: Blocchi Custom con Campi Personalizzati

· 10 min di lettura

ACF e Gutenberg: L’Integrazione che Conta

L’editor a blocchi di WordPress, conosciuto come Gutenberg, 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, 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.

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.

Come Funzionano i Blocchi ACF

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 e salvano i dati come metadati 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.

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(), the_field()), 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.

Gestione dei blocchi ACF e dei gruppi di campi in WordPress Gutenberg

Registrare un Blocco ACF

La registrazione di un blocco ACF avviene tramite la funzione acf_register_block_type() nel file functions.php del tema. Ecco un esempio completo di registrazione di un blocco “Testimonial”:

<?php
add_action(acf/init, registra_blocchi_acf);
function registra_blocchi_acf() {
    if( function_exists(acf_register_block_type) ) {

        acf_register_block_type(array(
            name              => testimonial,
            title             => Testimonial,
            description       => Blocco per mostrare una testimonianza cliente.,
            render_template   => template-parts/blocks/testimonial.php,
            category          => formatting,
            icon              => format-quote,
            keywords          => array(testimonial, citazione, recensione),
            mode              => preview,
            supports          => array(
                align => true,
                mode  => true,
            ),
        ));
    }
}
?>

I parametri principali sono: name (identificativo univoco del blocco, senza spazi), title (nome visibile nell’inseritore di blocchi), description (descrizione mostrata nel pannello di dettaglio), render_template (percorso del file PHP per il rendering), category (categoria nell’inseritore di blocchi), icon (icona Dashicons o SVG personalizzata) e keywords (parole chiave per la ricerca nell’inseritore).

Il parametro mode è particolarmente importante: preview mostra l’anteprima del blocco nell’editor con i campi ACF nel pannello laterale; edit mostra i campi ACF inline nel blocco; auto alterna automaticamente tra preview e edit in base all’interazione dell’utente. Il modo preview è generalmente il più apprezzato perché offre la migliore esperienza visuale.

Creare il Template di Rendering

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 nel tuo tema:

<?php
$nome = get_field(nome_cliente);
$ruolo = get_field(ruolo);
$citazione = get_field(citazione);
$foto = get_field(foto_cliente);

// Supporto per classi CSS e allineamento
$className = testimonial-block;
if( !empty($block[className]) ) {
    $className .=   . $block[className];
}
if( !empty($block[align]) ) {
    $className .=  align . $block[align];
}
?>

<div class="<?php echo esc_attr($className); ?>">
    <?php if($foto): ?>
        <img class="testimonial-photo"
             src="<?php echo esc_url($foto[sizes][thumbnail]); ?>"
             alt="<?php echo esc_attr($foto[alt]); ?>" />
    <?php endif; ?>

    <?php if($citazione): ?>
        <blockquote><?php echo wp_kses_post($citazione); ?></blockquote>
    <?php endif; ?>

    <div class="testimonial-author">
        <?php if($nome): ?>
            <strong><?php echo esc_html($nome); ?></strong>
        <?php endif; ?>
        <?php if($ruolo): ?>
            <span><?php echo esc_html($ruolo); ?></span>
        <?php endif; ?>
    </div>
</div>

Configurazione dei campi ACF per un blocco Gutenberg personalizzato

Nota come il template accede alla variabile $block, 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.

Associare i Campi al Blocco

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, crea un nuovo gruppo e nella sezione Location imposta la regola: Block è uguale a Testimonial (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”.

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).

Stili CSS per i Blocchi ACF

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), 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 nella registrazione:

acf_register_block_type(array(
    name          => testimonial,
    title         => Testimonial,
    render_template => template-parts/blocks/testimonial.php,
    enqueue_style => get_template_directory_uri() . /css/blocks/testimonial.css,
    // ... altri parametri
));

Il vantaggio di enqueue_style è che il CSS viene caricato solo nelle pagine che effettivamente utilizzano il blocco, ottimizzando le performance. Lo stesso vale per enqueue_script 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.

Funzionalità Avanzate: InnerBlocks e JSX

I blocchi ACF supportano InnerBlocks, 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 /> nel template:

// Nella registrazione:
supports => array(
    jsx => true, // Abilita il rendering JSX per InnerBlocks
),

// Nel template PHP:
<div class="my-block">
    <h2><?php the_field(titolo); ?></h2>
    <InnerBlocks />
</div>

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.

Strumenti avanzati ACF per la creazione di blocchi Gutenberg personalizzati

Gestire la Modalità Preview ed Edit

Il parametro mode nella registrazione del blocco controlla il comportamento predefinito, ma l’utente può alternare tra le modalità in qualsiasi momento (se il supporto mode => true è attivo). In modalità Preview, il blocco mostra l’anteprima renderizzata dal template PHP e i campi ACF appaiono nel pannello laterale dell’editor. In modalità Edit, i campi ACF vengono mostrati inline nel blocco, sostituendo l’anteprima.

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.

<?php if( empty(get_field(titolo)) && empty(get_field(contenuto)) ): ?>
    <div class="block-placeholder">
        <p>Compila i campi nel pannello laterale per configurare questo blocco.</p>
    </div>
<?php else: ?>
    <!-- Rendering normale del blocco -->
<?php endif; ?>

Blocchi ACF con block.json (WordPress 6.x)

A partire da ACF PRO 6.0 e WordPress 6.x, i blocchi ACF possono essere registrati anche tramite file block.json, seguendo la convenzione moderna di WordPress per la registrazione dei blocchi. Questo approccio è più strutturato e allineato con le best practice dell’ecosistema Gutenberg:

// acf-blocks/testimonial/block.json
{
    "name": "acf/testimonial",
    "title": "Testimonial",
    "description": "Blocco testimonianza cliente",
    "category": "formatting",
    "icon": "format-quote",
    "keywords": ["testimonial", "citazione"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "acf-blocks/testimonial/render.php"
    },
    "supports": {
        "align": true
    }
}

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à.

Best Practice per i Blocchi ACF

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/ 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.

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.

Leggi anche gli altri articoli della serie ACF

Per creare blocchi Gutenberg personalizzati con ACF per il tuo sito WordPress, affidati al team di G Tech Group, specializzato nella realizzazione di siti web con le tecnologie più avanzate dell’ecosistema WordPress. Contattaci per una consulenza e porta il tuo sito al livello successivo con blocchi personalizzati professionali.

Migliora il Tuo Sito WordPress

Scopri le nostre guide complete sugli altri plugin essenziali per WordPress:

#ACF #Blocchi #Custom Blocks #Gutenberg #Wordpress