Visualizzare i Campi ACF nel Frontend: Template e Shortcode

Dal Backend al Frontend: Mostrare i Dati ACF

Creare campi personalizzati con ACF è solo metà del lavoro. La vera magia avviene quando i dati inseriti nel backend vengono visualizzati nel frontend del sito, nelle pagine che i visitatori effettivamente vedono. ACF offre due approcci principali per portare i dati dal pannello di amministrazione al sito pubblico: l’utilizzo di funzioni PHP nei template del tema e l’uso di shortcode direttamente nell’editor dei contenuti. Ciascun approccio ha i propri vantaggi e i propri contesti di utilizzo ideali.

In questo articolo esploreremo entrambe le metodologie in dettaglio, partendo dalle funzioni PHP fondamentali di ACF fino ad arrivare alla creazione di shortcode personalizzati. Vedremo anche come gestire correttamente i diversi tipi di campo nel frontend, come applicare la formattazione appropriata e come garantire la sicurezza dell’output. Che tu sia uno sviluppatore esperto o un webmaster con conoscenze PHP di base, questa guida ti fornirà tutti gli strumenti necessari per integrare perfettamente i campi ACF nel design del tuo sito.

Le Funzioni PHP Fondamentali di ACF

ACF mette a disposizione due coppie di funzioni PHP principali per recuperare e visualizzare i valori dei campi. La prima coppia è get_field() e the_field(): get_field(nome_campo) recupera il valore del campo e lo restituisce come variabile PHP (senza stamparlo), mentre the_field(nome_campo) recupera il valore e lo stampa direttamente nell’output HTML. La regola pratica è semplice: usa the_field() quando vuoi stampare direttamente il valore nel template e get_field() quando devi elaborare il valore prima di visualizzarlo.

La seconda coppia è get_sub_field() e the_sub_field(), che funzionano in modo identico ma sono specifiche per i sottocampi all’interno di Repeater, Flexible Content e Group. Queste funzioni devono essere usate esclusivamente all’interno di un loop have_rows(), altrimenti non restituiscono alcun valore. È un errore comune cercare di usare get_field() per accedere ai sottocampi di un Repeater: questo non funziona e restituirà sempre null.

Entrambe le coppie di funzioni accettano un secondo parametro opzionale che specifica il post ID da cui recuperare il valore. Se omesso, ACF utilizza il post corrente nel loop di WordPress. Questo parametro diventa obbligatorio in due situazioni: quando recuperi valori dalle Options Page (passando la stringa option) e quando recuperi valori da un post diverso da quello corrente (passando l’ID numerico del post).

Visualizzare Campi di Testo nel Template

I campi di tipo Text e Text Area sono i più semplici da visualizzare. Per un campo di testo breve come un sottotitolo, puoi inserire il seguente codice direttamente nel file template del tema (ad esempio single.php o un template part dedicato):

<?php
$sottotitolo = get_field(sottotitolo);
if($sottotitolo): ?>
    <h2 class="entry-subtitle"><?php echo esc_html($sottotitolo); ?></h2>
<?php endif; ?>

Nota tre elementi fondamentali in questo codice. Primo: il controllo if($sottotitolo) che verifica se il campo ha un valore prima di visualizzarlo, evitando di mostrare tag HTML vuoti quando il campo non è compilato. Secondo: l’uso di esc_html() per l’escaping del valore, che previene attacchi XSS convertendo eventuali caratteri HTML speciali nelle corrispondenti entità. Terzo: il wrapping in un tag HTML con una classe CSS che ti permette di stilizzare il campo nel foglio di stile del tema.

Per i campi Text Area, il trattamento è leggermente diverso. Se hai configurato il campo con l’opzione “New Lines” impostata su “Automatically add paragraphs”, il valore restituito conterrà già i tag <p>. In questo caso, usa wp_kses_post() per l’escaping invece di esc_html(), poiché il primo consente i tag HTML sicuri (paragrafi, grassetti, link) mentre il secondo li convertirebbe tutti in testo visibile.

Visualizzare Campi Immagine

I campi Image di ACF possono restituire tre formati diversi in base all’impostazione “Return Format”: Array, URL o ID. Ciascun formato richiede un approccio leggermente diverso nel template. Il formato Array è il più completo e versatile:

<?php
$immagine = get_field(immagine_autore);
if($immagine): ?>
    <img src="<?php echo esc_url($immagine[url]); ?>"
         alt="<?php echo esc_attr($immagine[alt]); ?>"
         width="<?php echo esc_attr($immagine[width]); ?>"
         height="<?php echo esc_attr($immagine[height]); ?>" />
<?php endif; ?>

L’array restituito dal campo Image contiene numerose informazioni utili: url, alt, title, caption, description, width, height, mime_type e un sotto-array sizes con gli URL di tutte le dimensioni registrate nel tema (thumbnail, medium, large e qualsiasi dimensione personalizzata). Puoi accedere a una dimensione specifica con $immagine[sizes][medium], che è utile per mostrare versioni più piccole dell’immagine in liste o anteprime.

Se il formato di ritorno è ID, puoi utilizzare le funzioni native di WordPress per generare il tag immagine con le dimensioni desiderate: wp_get_attachment_image($immagine_id, medium) genera un tag <img> completo con srcset e attributi responsive. Questo è spesso il metodo preferito dagli sviluppatori più esperti perché sfrutta appieno il sistema di immagini responsive di WordPress, generando automaticamente gli attributi srcset e sizes per il caricamento ottimale su diversi dispositivi.

Gestire Campi Relazionali nel Frontend

I campi relazionali (Post Object, Relationship, Taxonomy, User) restituiscono oggetti WordPress completi, permettendoti di accedere a tutte le proprietà del post, del termine o dell’utente selezionato. Per un campo Post Object con ritorno singolo:

<?php
$post_correlato = get_field(articolo_correlato);
if($post_correlato): ?>
    <div class="related-post">
        <h3><a href="<?php echo get_permalink($post_correlato->ID); ?>">
            <?php echo esc_html($post_correlato->post_title); ?>
        </a></h3>
        <p><?php echo esc_html($post_correlato->post_excerpt); ?></p>
    </div>
<?php endif; ?>

Per un campo Relationship che restituisce un array di oggetti post, il codice richiede un ciclo foreach per iterare su tutti gli elementi selezionati. Quando lavori con campi relazionali, assicurati di verificare che il post collegato sia ancora pubblicato e accessibile: un post messo in bozza o eliminato potrebbe essere ancora referenziato dal campo ACF, causando link rotti o informazioni inesatte nel frontend.

Utilizzare gli Shortcode ACF

ACF include un sistema di shortcode integrato che permette di inserire i valori dei campi direttamente nell’editor dei contenuti, senza toccare i file del tema. La sintassi base è [acf field="nome_campo"]. Questo shortcode stampa il valore del campo del post corrente. Per recuperare un valore da un post specifico, usa [acf field="nome_campo" post_id="123"].

Gli shortcode ACF sono particolarmente utili per chi gestisce i contenuti senza conoscenze di programmazione. Un editor può inserire il valore di un campo direttamente nel testo dell’articolo, nelle widget di testo o in qualsiasi area che supporta gli shortcode di WordPress. Ad esempio, un editor potrebbe scrivere: “Per informazioni chiamare il [acf field="telefono_aziendale" post_id="option"]” e il numero di telefono verrà automaticamente recuperato dalla Options Page.

Tuttavia, gli shortcode hanno alcune limitazioni importanti. Non supportano nativamente i campi complessi come Repeater, Flexible Content o Gallery. Per questi tipi di campo, è necessario creare shortcode personalizzati che gestiscano la logica di rendering. Inoltre, gli shortcode base di ACF non offrono opzioni di formattazione: il valore viene stampato così com’è, senza wrapping HTML, classi CSS o gestione degli errori.

Creare Shortcode Personalizzati per ACF

Per gestire casi d’uso più complessi, puoi creare shortcode personalizzati nel file functions.php del tema. Ecco un esempio di shortcode che visualizza un Repeater di testimonial con formattazione HTML completa:

<?php
function shortcode_testimonial_acf($atts) {
    $atts = shortcode_atts(array(
        max => -1,
    ), $atts);

    $output = ;
    if( have_rows(testimonial) ):
        $count = 0;
        $output .= <div class="testimonial-grid">;
        while( have_rows(testimonial) ): the_row();
            if($atts[max] > 0 && $count >= $atts[max]) break;
            $output .= <div class="testimonial-card">;
            $output .= <blockquote> . wp_kses_post(get_sub_field(testo)) . </blockquote>;
            $output .= <cite> . esc_html(get_sub_field(nome)) . </cite>;
            $output .= </div>;
            $count++;
        endwhile;
        $output .= </div>;
    endif;
    return $output;
}
add_shortcode(testimonial, shortcode_testimonial_acf);
?>

Questo shortcode può essere usato nell’editor come [testimonial] per mostrare tutti i testimonial, oppure [testimonial max="3"] per limitarne il numero. La chiave è usare sempre return (non echo) all’interno delle funzioni shortcode, e applicare l’escaping appropriato a ogni valore mostrato nell’output.

Template Part Dedicati ai Campi ACF

Per progetti di medie e grandi dimensioni, la best practice è creare template part dedicati per i blocchi di visualizzazione dei campi ACF, piuttosto che inserire tutto il codice direttamente nei template principali. Crea una cartella template-parts/acf/ nel tuo tema e inserisci file PHP separati per ogni blocco di campi. Ecco la struttura consigliata:

tema/
├── template-parts/
│   └── acf/
│       ├── hero-section.php
│       ├── team-members.php
│       ├── testimonials.php
│       ├── faq-section.php
│       └── cta-banner.php

Ogni template part può essere incluso nei template principali con get_template_part(template-parts/acf/hero-section). Questo approccio mantiene il codice organizzato, facilita la manutenzione e permette di riutilizzare gli stessi blocchi in più template. Se un blocco deve ricevere parametri personalizzati, usa il terzo argomento di get_template_part() (disponibile da WordPress 5.5) per passare un array di dati.

Formattazione e Escaping dei Valori

La corretta formattazione e l’escaping dei valori ACF nel frontend è un aspetto cruciale spesso trascurato. Ogni tipo di campo richiede un trattamento specifico per garantire sia la corretta visualizzazione sia la sicurezza. Per i campi Text e Email, usa esc_html(). Per i campi URL e Page Link, usa esc_url(). Per i campi Wysiwyg e Text Area con formattazione HTML, usa wp_kses_post(). Per i valori inseriti in attributi HTML (come alt, title, class), usa esc_attr().

Per i campi Number, puoi formattare il valore con number_format() per aggiungere separatori delle migliaia e decimali: number_format(get_field(prezzo), 2, ,, .) trasformerà “1500” in “1.500,00”. Per i campi Date Picker, il valore salvato è nel formato Ymd (es. “20260315”): per visualizzarlo in formato leggibile, usa date_i18n(d F Y, strtotime(get_field(data_evento))) che produrrà “15 Marzo 2026” nella localizzazione italiana.

I campi Select, Checkbox e Radio Button restituiscono valori diversi in base all’impostazione “Return Format”: possono restituire il valore, l’etichetta o entrambi come array. Verifica sempre quale formato è impostato prima di visualizzare il valore nel template: un errore comune è provare a stampare un array come stringa, che produce il warning “Array to string conversion”.

Gestire Campi Vuoti e Valori di Default

Non tutti i campi saranno sempre compilati, e il tuo codice frontend deve gestire elegantemente i campi vuoti. La pratica migliore è verificare sempre l’esistenza del valore prima di tentare di visualizzarlo. Per i campi semplici, un controllo if($valore) è sufficiente. Per i campi che possono avere il valore 0 o false come valori validi (ad esempio un campo Number con valore 0), usa il controllo più specifico if($valore !== null && $valore !== ).

Puoi anche implementare valori di fallback nel template per i campi non compilati. L’operatore null coalescing di PHP (??) è perfetto per questo scopo: $titolo = get_field(titolo_custom) ?? get_the_title(); usa il titolo personalizzato ACF se disponibile, altrimenti il titolo standard del post. Questo approccio garantisce che la pagina abbia sempre contenuto da mostrare, anche quando i campi ACF non sono stati compilati.

Infine, ricorda che la funzione get_field() restituisce false quando il campo non esiste o non ha valore, non null. Questo è un dettaglio importante quando fai confronti rigorosi. Inoltre, per i campi True/False, un valore non salvato restituisce null (che è falsy in PHP), mentre un valore esplicitamente impostato su “No” restituisce 0 o false. Comprendere queste sfumature ti eviterà bug sottili nel tuo codice frontend.

Se hai bisogno di assistenza per integrare i campi ACF nel frontend del tuo sito WordPress, il team di G Tech Group è specializzato nella realizzazione di siti web con template personalizzati e visualizzazioni avanzate dei dati. Contattaci per una consulenza e trasforma i tuoi dati strutturati in pagine web straordinarie.

Migliora il Tuo Sito WordPress

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

• Come Installare Elementor su WordPress
• Come Installare e Configurare WP Rocket
• Come Installare e Configurare SEOPress
• Come Installare e Configurare UpdraftPlus