ACF e i Repeater Field: Creare Contenuti Ripetibili e Flessibili

Cos’è il Repeater Field di ACF

Il Repeater Field è una delle funzionalità più apprezzate e potenti di Advanced Custom Fields PRO. Si tratta di un tipo di campo speciale che permette di definire un insieme di sottocampi che possono essere ripetuti un numero illimitato di volte dall’utente. In altre parole, il Repeater crea una struttura dati dinamica dove ogni “riga” contiene gli stessi campi, ma l’utente decide quante righe aggiungere in base alle proprie necessità.

Immagina di dover gestire una sezione FAQ in un sito web: ogni domanda ha una domanda e una risposta, ma il numero di FAQ varia da pagina a pagina. Senza il Repeater, dovresti creare un numero fisso di campi (domanda_1, risposta_1, domanda_2, risposta_2, ecc.) sperando che bastino, oppure ricorrere a soluzioni complicate. Con il Repeater, definisci semplicemente due sottocampi — “Domanda” e “Risposta” — e l’utente aggiunge quante coppie desidera con un clic sul pulsante “Aggiungi Riga”.

Il Repeater Field è disponibile esclusivamente nella versione ACF PRO e rappresenta uno dei principali motivi per cui molti sviluppatori decidono di passare dalla versione gratuita a quella premium. In questo articolo vedremo come configurare il Repeater, come utilizzarlo nei template del tema e quali sono le best practice per sfruttarlo al meglio nei tuoi progetti WordPress.

Creare un Repeater Field: Configurazione Passo per Passo

Per creare un campo Repeater, apri l’editor di un gruppo di campi (o creane uno nuovo) e aggiungi un nuovo campo selezionando il tipo Repeater dal menu a discesa. Come per qualsiasi campo ACF, assegna un’etichetta descrittiva (ad esempio “Caratteristiche Prodotto”) e verifica che il nome del campo (field name) sia coerente con le tue convenzioni di naming.

Una volta selezionato il tipo Repeater, l’interfaccia si espande mostrando una sezione dedicata ai sottocampi (Sub Fields). Qui puoi aggiungere tutti i campi che comporranno una singola riga del Repeater. Ogni sottocampo viene configurato esattamente come un campo normale: puoi usare qualsiasi tipo di campo ACF come sottocampo, inclusi Text, Image, Select, Wysiwyg, Date Picker e persino altri Repeater annidati (anche se questo approccio va usato con cautela per non complicare eccessivamente la struttura).

Continuando con l’esempio delle FAQ, aggiungi due sottocampi: un campo Text con etichetta “Domanda” e un campo Text Area con etichetta “Risposta”. Puoi configurare le opzioni di ogni sottocampo individualmente: rendere la domanda obbligatoria, impostare un placeholder per la risposta, aggiungere istruzioni e così via. L’ordine dei sottocampi determina l’ordine in cui appaiono in ogni riga del Repeater.

Opzioni di Configurazione del Repeater

Il campo Repeater offre diverse opzioni specifiche che controllano il suo comportamento e aspetto. L’opzione Minimum Rows definisce il numero minimo di righe che l’utente deve compilare: se impostato a 1, il Repeater mostrerà sempre almeno una riga vuota. L’opzione Maximum Rows limita il numero massimo di righe che possono essere aggiunte: utile per impedire l’inserimento di troppe voci in sezioni che hanno vincoli di design (ad esempio, un massimo di 6 testimonial visibili nella homepage).

L’opzione Layout controlla come le righe del Repeater vengono visualizzate nell’editor. Sono disponibili tre layout: Table mostra i sottocampi come colonne di una tabella, ideale quando hai pochi sottocampi con valori brevi; Block mostra ogni sottocampo su una riga separata all’interno di un blocco, perfetto per sottocampi con contenuti più lunghi come Text Area o Wysiwyg; Row è un compromesso tra i due, mostrando ogni riga come un blocco compatto con i sottocampi affiancati dove possibile.

Il layout Table è il più compatto e funziona eccellentemente per elenchi semplici come coppie chiave-valore, coordinate, orari di apertura o specifiche tecniche. Il layout Block è preferibile quando i sottocampi includono editor Wysiwyg, campi immagine o qualsiasi elemento che richiede più spazio verticale. Scegli il layout in base al tipo di contenuto che l’utente dovrà inserire: un layout sbagliato può rendere l’interfaccia scomoda e poco intuitiva.

L’opzione Button Label ti permette di personalizzare il testo del pulsante per aggiungere nuove righe. Il testo predefinito è “Add Row”, ma è buona pratica personalizzarlo con un testo più specifico come “Aggiungi FAQ”, “Aggiungi Membro del Team” o “Aggiungi Caratteristica”. Questo piccolo dettaglio migliora significativamente l’esperienza utente, rendendo chiaro cosa accade quando si clicca il pulsante.

Casi d’Uso Pratici del Repeater

Il Repeater Field si presta a innumerevoli casi d’uso. Ecco alcuni dei più comuni nei progetti WordPress professionali. Team e Staff: un Repeater con sottocampi per foto, nome, ruolo, bio e link ai social network, permettendo di gestire la pagina del team senza creare un custom post type dedicato. Slider e Banner: immagine, titolo, sottotitolo, link e ordine per ogni slide, con totale controllo sulla sequenza e sul contenuto di ogni elemento.

Orari di Apertura: giorno della settimana (Select), orario apertura (Time Picker) e orario chiusura (Time Picker) per ogni riga, permettendo di gestire facilmente gli orari anche quando variano tra i giorni. Specifiche Tecniche: nome della specifica e valore, per creare tabelle di specifiche su misura per prodotti, immobili o veicoli. Timeline: data, titolo e descrizione per ogni evento, utile per cronologie aziendali, storie personali o percorsi formativi.

Prezzi e Piani: nome del piano, prezzo, elenco delle funzionalità incluse (con un sotto-Repeater annidato) e pulsante CTA, per creare tabelle prezzi completamente personalizzabili. Galleria con Didascalie: a differenza del campo Gallery standard che non supporta metadati per singola immagine, un Repeater con sottocampi Immagine, Titolo e Didascalia ti dà il pieno controllo su ogni elemento della galleria.

Visualizzare il Repeater nel Frontend con PHP

Per visualizzare i dati di un Repeater nel frontend, ACF fornisce funzioni PHP dedicate che semplificano enormemente il lavoro. La funzione principale è have_rows(), che funziona in modo simile al loop standard di WordPress. Ecco la struttura base per iterare sulle righe di un Repeater:

<?php if( have_rows(caratteristiche_prodotto) ): ?>
  <ul>
    <?php while( have_rows(caratteristiche_prodotto) ): the_row(); ?>
      <li>
        <strong><?php the_sub_field(nome); ?></strong>:
        <?php the_sub_field(valore); ?>
      </li>
    <?php endwhile; ?>
  </ul>
<?php endif; ?>

La funzione have_rows() verifica se il Repeater ha almeno una riga compilata e, insieme al ciclo while, itera su tutte le righe disponibili. All’interno del loop, the_row() avanza alla riga successiva, mentre the_sub_field() stampa il valore del sottocampo specificato e get_sub_field() lo restituisce come variabile senza stamparlo. È fondamentale chiamare the_row() all’inizio di ogni iterazione, altrimenti i sottocampi non verranno recuperati correttamente.

Per i sottocampi di tipo Image, il valore restituito dipende dall’impostazione “Return Format” del campo: se impostato su “Array”, get_sub_field(immagine) restituirà un array con URL, dimensioni e alt text; se impostato su “URL”, restituirà direttamente la stringa dell’URL; se impostato su “ID”, restituirà l’ID numerico dell’allegato, che potrai poi usare con wp_get_attachment_image() per generare il tag HTML dell’immagine con le dimensioni desiderate.

Repeater Annidati: Strutture Dati Complesse

ACF PRO permette di annidare Repeater all’interno di altri Repeater, creando strutture dati gerarchiche. Questa funzionalità è potente ma va utilizzata con giudizio. Un caso d’uso tipico è una tabella prezzi dove ogni piano (primo livello di Repeater) contiene un elenco di funzionalità (secondo livello di Repeater). La sintassi PHP per gestire Repeater annidati richiede loop have_rows() annidati, ciascuno con il proprio the_row().

Attenzione però: i Repeater annidati aumentano significativamente il numero di righe nel database. Ogni sottocampo di ogni riga di ogni livello genera una voce in wp_postmeta. Un Repeater a due livelli con 5 righe al primo livello e 10 righe al secondo livello con 3 sottocampi per livello genererà circa 5 * (3 + 10 * 3) + 1 = 166 righe di metadati per un singolo post. Per siti con migliaia di contenuti, questo può avere un impatto misurabile sulle performance delle query.

Come regola generale, limita i Repeater a un massimo di due livelli di annidamento. Se la tua struttura dati richiede tre o più livelli, è probabile che un approccio diverso sia più appropriato: considera l’uso di custom post type con relazioni, oppure il campo Flexible Content che offre una maggiore flessibilità strutturale senza i problemi di performance dei Repeater profondamente annidati.

Ordinare e Filtrare le Righe del Repeater

Le righe del Repeater vengono salvate e restituite nell’ordine in cui l’utente le ha disposte nell’editor (l’utente può riordinarle tramite drag and drop). Tuttavia, potresti voler ordinare le righe in base al valore di un sottocampo. Per farlo, devi recuperare tutte le righe come array e poi ordinarle con le funzioni di ordinamento PHP.

<?php
$rows = get_field(eventi);
if($rows) {
    // Ordina per data (sottocampo data_evento)
    usort($rows, function($a, $b) {
        return strtotime($a[data_evento]) - strtotime($b[data_evento]);
    });
    foreach($rows as $row) {
        echo <p> . esc_html($row[titolo_evento]) .  -  . esc_html($row[data_evento]) . </p>;
    }
}
?>

Questo approccio è utile per ordinare cronologicamente gli eventi, per valore numerico crescente o decrescente, oppure per qualsiasi altro criterio. Puoi anche filtrare le righe, mostrando solo quelle che soddisfano determinate condizioni: ad esempio, solo gli eventi futuri, solo le caratteristiche con un certo valore, solo i membri del team di un determinato dipartimento.

Repeater con Logica Condizionale

All’interno di un Repeater, puoi utilizzare la logica condizionale per mostrare o nascondere sottocampi in base ai valori di altri sottocampi nella stessa riga. Questa funzionalità è particolarmente utile per Repeater con sottocampi opzionali o contestuali. Ad esempio, in un Repeater per gestire i link di navigazione, potresti avere un campo Select “Tipo di Link” con opzioni “Interno” e “Esterno”: quando l’utente seleziona “Interno”, appare un campo Page Link; quando seleziona “Esterno”, appare un campo URL.

La logica condizionale all’interno dei Repeater funziona esattamente come per i campi normali, con una differenza importante: le condizioni possono riferirsi solo a sottocampi dello stesso Repeater e della stessa riga, non a campi esterni al Repeater o a sottocampi di altre righe. Questa limitazione è intenzionale e garantisce che ogni riga sia indipendente dalle altre.

Performance e Ottimizzazione dei Repeater

I Repeater sono potenti ma richiedono attenzione dal punto di vista delle performance. Ogni riga del Repeater genera una riga nel database per ogni sottocampo, più righe aggiuntive per i metadati interni di ACF. Questo significa che un post con un Repeater di 50 righe e 5 sottocampi avrà circa 300+ righe nella tabella wp_postmeta. Per siti con centinaia di post, la tabella può crescere rapidamente.

Per ottimizzare le performance con i Repeater, segui queste best practice: imposta sempre un Maximum Rows ragionevole per evitare inserimenti eccessivi; considera l’uso di custom post type invece dei Repeater quando le righe superano le 20-30 unità o quando hai bisogno di cercare e filtrare i dati singolarmente; utilizza la funzione get_field() con il parametro di formato appropriato per ridurre le query al database; e valuta l’implementazione di una strategia di caching per le pagine che mostrano dati da Repeater complessi.

Un altro aspetto da considerare è l’impatto dei Repeater sulla velocità dell’editor di amministrazione. Repeater con molte righe e sottocampi complessi (come Wysiwyg o Gallery) possono rallentare significativamente il caricamento della pagina di editing. In questi casi, il layout “Block” con le righe collassate di default offre una migliore esperienza rispetto al layout “Table”, perché riduce la quantità di elementi DOM renderizzati inizialmente.

Alternative al Repeater: Quando Usare Altre Soluzioni

Il Repeater non è sempre la scelta migliore. Per strutture dati con molti elementi o che richiedono ricerche e filtri avanzati, i custom post type con relazioni ACF sono spesso preferibili. Per layout complessi con sezioni eterogenee, il campo Flexible Content offre maggiore flessibilità. Per semplici elenchi di valori dello stesso tipo, un campo Checkbox o Select multiplo può essere sufficiente e più performante.

In sintesi, il Repeater Field è uno strumento straordinario quando usato nel contesto giusto: elenchi strutturati di media lunghezza (5-30 righe), con sottocampi relativamente semplici, dove l’ordine delle righe è significativo e non è necessario eseguire query complesse sui singoli valori. Per tutto il resto, valuta attentamente le alternative disponibili nell’ecosistema ACF e WordPress.

Se hai bisogno di implementare strutture dati complesse con Repeater e campi personalizzati ACF nel tuo sito WordPress, il team di G Tech Group è specializzato nella realizzazione di siti web su misura con architetture avanzate. Contattaci per una consulenza e scopri come possiamo aiutarti a costruire il sito perfetto per le tue esigenze.

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