Guida ai Custom Post Type di WordPress

Cosa sono i custom post type

La piattaforma WordPress include di default due tipi di contenuto: gli articoli (post del blog) e le pagine. Tuttavia, la maggior parte dei siti ha contenuti che non rientrano in nessuno di questi due tipi. Progetti di portfolio, prodotti, recensioni, eventi, annunci immobiliari, ricette o membri del team sono esempi di contenuti che richiedono una struttura e una visualizzazione proprie. I custom post type ti permettono di creare nuovi tipi di contenuto con campi, tassonomie e template dedicati.

I custom post type sono un concetto fondamentale dello sviluppo WordPress che trasforma WordPress da piattaforma di blogging a CMS (Content Management System) completo. Ogni plugin di WordPress che aggiunge un nuovo tipo di contenuto — come i prodotti di WooCommerce, gli eventi di The Events Calendar o i plugin di portfolio — utilizza i custom post type dietro le quinte. Comprendere i CPT ti dà il pieno controllo sulla struttura dei contenuti del tuo sito.

Registrare un custom post type

La funzione register_post_type

Un custom post type si registra tramite la funzione WordPress register_post_type, chiamata all'interno dell'hook init. La funzione accetta due argomenti: uno slug, che è l'identificatore interno del tipo di contenuto, e un array di argomenti che definiscono il comportamento e l'aspetto nel pannello di amministrazione. Lo slug dovrebbe essere al singolare, in minuscolo, senza spazi e con un massimo di 20 caratteri. Ad esempio, per i progetti di portfolio lo slug sarebbe project, per gli immobili property, per le ricette recipe.

Argomenti principali

• labels: Un array di etichette che WordPress usa nell'interfaccia di amministrazione, tra cui name per il plurale, singular_name per il singolare, add_new per il pulsante di aggiunta, edit_item per il titolo della pagina di modifica e search_items per la ricerca.
• public: Indica se il tipo di contenuto è pubblicamente disponibile nel frontend. Imposta true per i contenuti che i visitatori devono vedere.
• has_archive: Indica se il tipo di contenuto ha una pagina archivio che mostra tutti gli elementi, simile alla pagina del blog per gli articoli.
• supports: Quali funzionalità di WordPress sono disponibili per questo tipo di contenuto, tra cui title, editor, thumbnail, excerpt, custom-fields, comments e revisions.
• menu_icon: Un'icona Dashicons mostrata nella barra laterale di amministrazione. WordPress include oltre 300 icone per scopi diversi.
• rewrite: Definisce la struttura degli URL per questo tipo di contenuto. Ad esempio, lo slug portfolio crea URL come iltuosito.com/portfolio/nome-progetto.
• show_in_rest: Abilita l'editor Gutenberg e l'accesso tramite REST API. Imposta true per i siti WordPress moderni.

Advanced Custom Fields (ACF)

Perché usare ACF

I campi personalizzati di WordPress sono il meccanismo di base per aggiungere dati extra ai contenuti, ma l'interfaccia nativa è poco pratica. Il plugin Advanced Custom Fields trasforma l'esperienza di creazione dei contenuti aggiungendo campi intuitivi come input di testo, area di testo, selettore di immagini, datepicker, campo Google Maps, campi relazionali e molto altro. ACF è lo standard de facto nello sviluppo WordPress, con oltre 2 milioni di installazioni attive, ed è utilizzato da agenzie di tutto il mondo.

Tipi di campo

ACF offre oltre 30 tipi di campo organizzati in categorie. I campi di base includono testo, area di testo, numero, email, URL e password. I campi di scelta sono select, checkbox, radio button, button group e true/false. I campi di contenuto sono immagine, file, editor WYSIWYG, oEmbed per i video e galleria. I campi relazionali sono link, post object, page link, relationship e tassonomia. I campi di layout sono group, repeater per le sezioni ripetibili, flexible content per i layout modulari e clone. Il campo repeater è particolarmente potente perché consente di creare strutture ripetibili come un elenco di membri del team, sezioni con icone o una tabella di specifiche tecniche.

Visualizzare i campi ACF

ACF mette a disposizione semplici funzioni PHP per visualizzare i valori dei campi nei temi. La funzione get_field restituisce il valore del campo, mentre the_field lo stampa direttamente. Per le immagini, get_field restituisce un array con URL, larghezza, altezza e testo alternativo. Per i campi repeater si usano have_rows e the_row in un ciclo while per iterare su tutte le righe. Per il flexible content si usa get_row_layout per determinare quale layout è in uso e visualizzare il template corrispondente. La documentazione di ACF è estremamente dettagliata, con esempi per ogni tipo di campo.

Tassonomie personalizzate

Cosa sono le tassonomie

Le tassonomie sono sistemi di classificazione dei contenuti. Di default WordPress dispone di due tassonomie: le categorie, che sono gerarchiche, e i tag, che sono piatti. Per i custom post type sono solitamente necessarie tassonomie personalizzate. Ad esempio, i progetti di portfolio possono avere una tassonomia tipo di progetto con valori come web design, branding e fotografia. Gli immobili possono avere tassonomie per la località, il tipo di proprietà e la fascia di prezzo. Le ricette possono avere cucina, tipo di piatto e livello di difficoltà.

Registrare le tassonomie

La funzione register_taxonomy si richiama all'interno dell'hook init, in modo simile a register_post_type. Accetta tre argomenti: lo slug della tassonomia, un array dei post type a cui si applica e un array di argomenti. L'argomento hierarchical determina se la tassonomia funziona come le categorie, con una relazione padre-figlio, oppure come i tag, con una struttura piatta. Le etichette definiscono come la tassonomia viene visualizzata nel pannello di amministrazione. L'argomento rewrite controlla la struttura degli URL delle pagine archivio della tassonomia.

Tassonomie gerarchiche vs piatte

Le tassonomie gerarchiche vengono visualizzate come un elenco di checkbox nel pannello di amministrazione, con la possibilità di creare termini padre e figlio. Usale per classificazioni con una struttura chiara, come le località in cui l'Italia ha sottocategorie come Roma, Milano e Napoli. Le tassonomie piatte vengono visualizzate come un campo di inserimento tag in cui digiti i termini separati da virgole. Usale per etichette flessibili come tecnologie, competenze o caratteristiche, dove non esiste una relazione gerarchica.

File di template per i custom post type

La gerarchia dei template di WordPress

WordPress usa una gerarchia specifica per determinare quale file di template utilizzare per visualizzare un contenuto. Per un custom post type con slug project, WordPress cerca i file nel seguente ordine. Per i singoli elementi cerca single-project.php, poi single.php, poi singular.php, poi index.php. Per la pagina archivio cerca archive-project.php, poi archive.php, poi index.php. Crea file di template specifici per il tuo CPT per avere il pieno controllo sulla visualizzazione.

Template single

Il template single visualizza un singolo elemento del tuo custom post type. Ad esempio single-project.php per un progetto di portfolio mostra il titolo del progetto, l'immagine in evidenza, la descrizione e i campi ACF come cliente, data, URL del progetto e galleria di immagini. Usa il loop di WordPress the_loop per accedere ai dati del post e le funzioni ACF per i campi personalizzati. Aggiungi la navigazione tra i progetti con previous_post_link e next_post_link e una sezione di progetti correlati basata sulla tassonomia.

Template archive

Il template archive visualizza un elenco di tutti gli elementi con filtri per tassonomia. Ad esempio archive-project.php mostra una griglia di progetti di portfolio con miniatura, titolo, categoria e breve descrizione. Aggiungi pulsanti di filtro per le tassonomie affinché i visitatori possano filtrare i progetti per tipo. La paginazione consente di navigare tra un gran numero di elementi. Per una visualizzazione avanzata usa WP_Query con argomenti personalizzati per ordinare, filtrare e raggruppare gli elementi.

WP_Query per i custom post type

Query personalizzate

La classe WP_Query consente di creare query personalizzate per recuperare gli elementi di un custom post type secondo criteri specifici. L'argomento post_type definisce quale tipo di contenuto stai recuperando. posts_per_page controlla il numero di risultati. orderby e order definiscono l'ordinamento per data, titolo, menu_order o valore meta. tax_query filtra per tassonomia con la possibilità di combinare più tassonomie usando gli operatori AND o OR. meta_query filtra per i valori dei campi personalizzati con operatori come uguale, maggiore di, minore di, LIKE e BETWEEN.

Esempi di query

Per visualizzare gli ultimi 6 progetti di portfolio della categoria web design ordinati per data, usa WP_Query con gli argomenti post_type project, posts_per_page 6, tax_query con tassonomia project_type e termine web-design. Per visualizzare annunci immobiliari con un prezzo compreso tra 50.000 e 100.000 euro, usa meta_query con chiave price, tipo NUMERIC e operatore BETWEEN. Reimposta sempre l'oggetto post globale con wp_reset_postdata dopo le query personalizzate, per non compromettere il loop principale di WordPress.

REST API e Gutenberg

Accesso tramite REST API

Con l'argomento show_in_rest impostato su true, il tuo custom post type ottiene automaticamente un endpoint REST API all'indirizzo iltuosito.com/wp-json/wp/v2/slug. Questo consente di recuperare, creare, aggiornare ed eliminare elementi tramite chiamate API, che sono la base per l'accesso headless a WordPress e per i frontend in JavaScript. I campi ACF possono essere esposti nella REST API utilizzando il plugin ACF to REST API o registrando manualmente i campi con la funzione register_rest_field.

Blocchi Gutenberg

Con show_in_rest abilitato, il tuo CPT utilizza l'editor Gutenberg al posto dell'editor classico. Puoi creare blocchi Gutenberg personalizzati specifici per il tuo tipo di contenuto usando ACF Blocks, che permette di creare blocchi con template PHP e campi ACF senza conoscere React. Ad esempio, per un portfolio puoi creare un blocco che mostra una griglia di progetti selezionati, oppure per le ricette un blocco che formatta l'elenco degli ingredienti e i passaggi di preparazione con uno stile personalizzato.

Buone pratiche per i custom post type

Naming e organizzazione

Usa un prefisso per lo slug del tuo CPT per evitare conflitti con altri plugin e con gli aggiornamenti di WordPress. Ad esempio, invece di project usa myplugin_project. Raggruppa la registrazione di CPT e tassonomie in una classe o in un file separato per facilitare la manutenzione. Usa costanti per gli slug per evitare errori di battitura. Documenta ogni CPT con una descrizione del suo scopo, l'elenco dei campi ACF e le tassonomie.

Performance

Ogni custom post type aggiunge query al database, quindi evita di creare troppi CPT quando le tassonomie possono raggiungere lo stesso obiettivo. Ad esempio, invece di CPT separati per blog, notizie e tutorial, usa gli articoli standard con le categorie. I campi ACF vengono memorizzati come post meta nel database: per i campi usati frequentemente nelle query, valuta la creazione di una tabella personalizzata per ottenere prestazioni migliori. Memorizza nella cache le query WP_Query complesse usando la transient API per ridurre il carico sul database. Sulle nostre soluzioni di hosting WordPress abbiamo un ambiente ottimizzato per i siti con custom post type e query avanzate, con memoria PHP sufficiente e dischi SSD veloci per un'esperienza di amministrazione reattiva.

Conclusione

I custom post type trasformano WordPress da piattaforma di blogging in un potente CMS capace di gestire qualsiasi tipo di contenuto. La combinazione della funzione register_post_type per creare i tipi di contenuto, di ACF per i campi personalizzati, delle tassonomie personalizzate per la classificazione e dei file di template per la visualizzazione ti dà il pieno controllo sulla struttura e sulla presentazione dei contenuti. Queste conoscenze sono la base dello sviluppo WordPress professionale (inizia con la nostra guida) e aprono la possibilità di creare siti complessi come presentazioni di portfolio, cataloghi di prodotti, directory e applicazioni aziendali.