Custom Post Type WordPress: quando usarli e come crearli con ACF o codice

Un Custom Post Type WordPress non serve a creare semplicemente più pagine sul sito. Serve a rappresentare un contenuto con una propria identità editoriale: qualcosa che viene pubblicato più volte, ha dati ricorrenti, può richiedere un archivio, filtri, relazioni e un template dedicato.

Un esempio tipico è un sito che pubblica eventi. Ogni evento ha titolo, descrizione, data, prezzo, iscrizione e forse relatori o sede. Trattare questi elementi come normali articoli rende presto difficile mantenere dati coerenti e costruire pagine utili. Un CPT permette invece di modellare il contenuto prima ancora di progettarne la grafica.

Quando un Custom Post Type è la scelta giusta

Cosa cambia rispetto ad articoli e pagine

WordPress include già post type nativi, come articoli, pagine e allegati. Con register_post_type() è possibile registrarne altri, con schermata amministrativa, permalink, archivio, tassonomie, capability e supporti selezionati.

Un CPT non crea automaticamente una nuova tabella nel database: i suoi contenuti vengono salvati nella normale tabella dei post e distinti dal valore post_type. Può però avere regole pubbliche e gestionali completamente diverse dagli articoli.

Un CPT è adatto quando il contenuto:

• viene creato e aggiornato ripetutamente;
• ha proprietà ricorrenti, come data, prezzo, indirizzo o documento allegato;
• merita una pagina singola, un archivio o filtri propri;
• deve essere riutilizzato in più sezioni del sito;
• richiede relazioni, permessi o un workflow editoriale distinto.

Per gli eventi, ad esempio, un archivio degli appuntamenti futuri e filtri per tipologia possono essere realmente utili. Lo stesso ragionamento vale per corsi, immobili, case study, risorse scaricabili o membri di un team.

Non creare un CPT per una sola pagina istituzionale, per articoli che differiscono soltanto per categoria o per una necessità esclusivamente grafica risolvibile con blocchi e template. Evitalo anche quando un plugin verticale già gestisce correttamente il dominio funzionale necessario. Un CPT non produce vantaggi SEO automatici: pagine e archivi devono avere un’utilità concreta per chi cerca informazioni.

CPT, tassonomie, campi ACF e relazioni: progettare il modello

La scelta più utile avviene prima di installare plugin o scrivere codice. Per l’esempio degli eventi, ogni informazione va collocata nello strumento corretto.

La città chiarisce bene la differenza. Può essere un campo di testo se viene solo mostrata nella scheda evento. Diventa una tassonomia se gli utenti devono trovare una raccolta utile come “Eventi a Milano”. Se invece la sede ha indirizzo, mappa, contatti, immagini e viene usata da molti eventi, ha senso un CPT Sedi collegato agli eventi.

Una regola pratica: una pagina e una vita editoriale proprie suggeriscono un CPT; la necessità di aggregare e filtrare suggerisce una tassonomia; una proprietà descrittiva è un campo; un elenco interno è un repeater.

ACF o codice: quale strada scegliere e dove registrare il CPT

Advanced Custom Fields permette di creare field group e, dalla sua interfaccia, anche post type e tassonomie. Il codice con un plugin proprietario offre invece maggiore controllo sulla distribuzione e sul ciclo di sviluppo. Non sono scelte incompatibili.

ACF è una buona scelta quando i campi e il modello devono essere modificabili dal team. Repeater, Flexible Content e Options Page sono funzionalità da verificare in base alla licenza e alla versione adottata. Le definizioni possono essere esportate in PHP oppure salvate come Local JSON nella cartella acf-json, così da sincronizzarle tra staging e produzione.

La registrazione via codice è preferibile quando il CPT fa parte di un prodotto, deve essere distribuito, sottoposto a code review o mantenuto indipendente da ACF e dal tema.

Il file functions.php può funzionare, ma lega il modello dei contenuti al design: cambiando tema, il CPT può sparire dal pannello amministrativo. Registralo invece in un plugin dedicato o, quando appropriato, in un mu-plugin.

La chiave tecnica deve essere breve, stabile, minuscola e prefissata. La chiave di un post type può avere fino a 20 caratteri, quella di una tassonomia fino a 32. Nell’esempio useremo acme_evento e acme_tipo_evento, evitando nomi generici che potrebbero entrare in conflitto con temi o plugin. Lo slug pubblico può essere diverso: qui sarà eventi. Cambiare la chiave tecnica richiede una migrazione dei contenuti; cambiare uno slug già pubblicato richiede redirect 301, controlli sui link interni, canonical e sitemap.

Tutorial: creare il CPT Eventi e la tassonomia con un plugin

Crea la cartella wp-content/plugins/acme-eventi e al suo interno il file acme-eventi.php. Attiva poi il plugin dal pannello di WordPress.

La registrazione avviene su init, come previsto dalle API di WordPress. L’activation hook registra prima le strutture e poi rigenera le rewrite rules. Non chiamare flush_rewrite_rules() a ogni richiesta: è un’operazione costosa. Se durante lo sviluppo compare un 404, salva nuovamente la pagina Impostazioni → Permalink.

Aggiungere i campi con ACF e preparare contenuti interrogabili

In ACF crea un field group chiamato “Dati evento” e applicalo quando il post type è uguale a acme_evento. Una configurazione essenziale può includere:

• data di inizio e data di fine con Date Picker;
• orario con Time Picker;
• prezzo con campo Number;
• URL di iscrizione con campo URL;
• relatore con Relationship o Post Object;
• programma PDF con campo File;
• flag “In evidenza” con True/False.

Con Local JSON, ACF salva le definizioni nella cartella acf-json del tema o del plugin configurato. Versiona queste definizioni, non i contenuti editoriali inseriti nel database. In alternativa, esporta i field group in PHP e includili nel plugin del progetto.

Per recuperare eventi futuri bisogna usare un formato coerente con quello salvato. Il Date Picker ACF salva normalmente il valore nel database in formato Ymd; in questo caso un confronto numerico è appropriato:

$eventi_futuri = new WP_Query( array(
    'post_type'      => 'acme_evento',
    'posts_per_page' => 12,
    'meta_key'       => 'data_inizio',
    'orderby'        => 'meta_value_num',
    'order'          => 'ASC',
    'meta_query'     => array(
        array(
            'key'     => 'data_inizio',
            'value'   => current_time( 'Ymd' ),
            'compare' => '>=',
            'type'    => 'NUMERIC',
        ),
    ),
) );

I valori in wp_postmeta sono trattati come stringhe. Per date, prezzi e orari usa quindi il tipo corretto nella meta_query, ad esempio DATE, DATETIME, NUMERIC o DECIMAL, in base al formato realmente memorizzato.

Repeater molto estesi, Flexible Content complessi e filtri multipli su grandi cataloghi possono rendere più pesanti editor e front-end. Per volumi elevati, il modello dati va valutato prima di basarsi esclusivamente su post meta e query complesse.

Template, Gutenberg, REST API e SEO

In un classic theme, WordPress cercherà single-acme_evento.php per la pagina del singolo evento e archive-acme_evento.php per l’archivio. Nei block theme la logica della template hierarchy resta analoga, ma i template sono file HTML a blocchi nella cartella /templates. Le modifiche salvate dal Site Editor possono prevalere sui file forniti dal tema.

Il template front-end controlla la pagina pubblica. Un block template dell’editor definisce invece la struttura iniziale di un nuovo contenuto; un template lock limita quali blocchi l’editor può modificare. Sono strumenti distinti.

show_in_rest => true abilita il CPT per Gutenberg e per la REST API. Non basta però a esporre i campi ACF: nel field group va attivata anche l’opzione “Show in REST API”, secondo quanto indicato nella documentazione ACF sulla REST API.

Archivi e tassonomie vanno pubblicati solo se aiutano davvero la navigazione o intercettano una ricerca reale. Una sitemap può comunicare URL ai motori di ricerca, ma non garantisce l’indicizzazione. Le pagine pubbliche devono essere utili, raggiungibili con link crawlable e coerenti con i principi di contenuto utile per le persone. Archivi sottili o duplicati richiedono una scelta editoriale consapevole.

Controlli prima della pubblicazione e problemi frequenti

• 404 su singolo o archivio: verifica plugin attivo, registrazione su init, collisioni di slug e permalink rigenerati.
• Gutenberg assente: controlla show_in_rest e i supporti del post type.
• Campi ACF non nella REST API: attiva “Show in REST API” nel field group, oltre a show_in_rest sul CPT.
• CPT assente dalla home: non viene aggiunto automaticamente alla main query; modifica la query solo se esiste una reale esigenza editoriale.
• CPT duplicato: controlla che non sia registrato contemporaneamente da ACF, CPT UI, tema e plugin.
• CPT scomparso dopo un cambio tema: sposta la registrazione dal tema a un plugin dedicato.

Prima del rilascio verifica chiavi e slug, template singolo e archivio, tipi dei campi, permessi, URL esistenti e redirect. Mantieni Local JSON o export PHP nel repository, testa in staging, esegui backup e valuta sitemap e indicizzazione solo per le sezioni che meritano visibilità.

Per un nuovo progetto, parti dall’entità e dalle sue relazioni, non dalla schermata di configurazione. Crea alcuni eventi reali, verifica come vengono cercati e gestiti dal team, poi aggiungi archivi, tassonomie e relazioni solo quando migliorano davvero l’esperienza del sito.