WordPress 3.0 – Post personalizzati (Custom Post Type) – Esempio completo

Una delle funzionalità più utili e potenti messe a disposizione da WordPress è la possibilità di personalizzare a piacere l’uso degli articoli e delle categorie.

Faccio una premessa.
Gli articoli che siamo abituati a usare hanno in realtà un «tipo» associato: il tipo “post”. Allo stesso modo, le pagine hanno associato il tipo “page”. Di default troviamo poi altri tre tipi: “attachment”, “revision” e “nav_menu_item”.

WordPress ci dà la possibilità di creare dei nuovi tipi, in pratica delle aree separate in cui possiamo inserire articoli e categorie senza intaccare quelli principali.
Se, per esempio, abbiamo un sito che si occupa di musica e a un certo punto decidiamo di inserire una sezione per i film, ci sarà utile creare una nuova area per i film, i cui articoli saranno tenuti ben distinti da quelli della musica.
I tipi personalizzati vengono denominati tecnicamente Custom Post Type (CPT).

In questo articolo vedremo un esempio completo e minimale su come realizzare i CPT.
Nello specifico, il nostro cliente immaginario ci ha commissionato la realizzazione di un’area per inserire i calendari delle partite di andata e ritorno di una squadra di pallavolo.
Quello di cui abbiamo bisogno è di creare un’area personalizzata chiamata “Calendario”, che si occupa esattamente come un qualsiasi post ma che in lato sito sarà visualizzata in una sezione a parte.

I file completi sono scaricabili gratuitamente al seguente link. All’interno troverete un txt contenente la descrizione generale con i passi da seguire.

Scarica gli script di questo articolo in formato zip

Il plugin “MM Custom Type Calendario” [mm_custom_types.php]

Le basi del CPT le costruiremo attraverso un comodo plugin, che potrà quindi essere esportato facilmente in altri progetti.
Il file “mm_custom_types.php” nello zip va inserito così com’è nella cartella dei plugin di WordPress. Il plugin va poi attivato come al solito nell’apposita area dell’admi.

Vediamo il contenuto del plugin.
Ho cercato di introdurre quanti più parametri possibili nella funzione, così da averli sottomano. Ogni parametro è commentato. In realtà, i valori attributi a gran parte di questi parametri sono quelli di default e quindi potevano essere omessi.
Per personalizzare i parametri vedete la documentazione ufficiale della funzione “register_post_type()” di WordPress (a fondo articolo trovate il link diretto).

Per prima cosa creiamo la funzione crea_calendari(). Sarà questa a definire i parametri per comporre il nostro CPT.
All’interno della funzione richiameremo register_post_type(), facendogli passare il riferimento (“calendario”, che in pratica sarà il nome univoco che identificherà il nostro CPT) e l’array contenente tutti i parametri definiti.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

function crea_calendari(){

    $labels = array(
        'name'               => __('Calendari'), //nome plurale dell'etichetta
        'singular_name'      => __('Calendario'), //nome singolare dell'etichetta
	'menu_name'	     => __('Calendari Menu'), //nome del menu
	'all_items'          => __('Elenco Calendari'), //testo per mostrare tutti gli elementi
        'add_new'            => __('Aggiungi Calendario'), //testo del pulsante di aggiunta nuovo elemento
        'add_new_item'       => __('Nuovo Calendario'), //testo da mostrare quando siamo all'interno di un nuovo elemento
        'edit_item'          => __('Modifica Calendario'), //testo di modifica dell'elemento
        'new_item'           => __('Nuovo Calendario'), //testo del nuovo elemento
        'view_item'          => __('Visualizza Calendario'), //testo di visualizzazione dell'elemento
        'search_items'       => __('Cerca Calendario'), //testo per la ricerca degli elementi
        'not_found'          => __('Calendario non trovato'), //testo quando non esistono elementi nell'elenco
        'not_found_in_trash' => __('Calendario non trovato nel cestino'), //testo quando non esistono elementi nel cestino
    );

    $args = array(
                'labels'             => $labels,
		'description'	     => 'Raccolta dei Calendari', //breve descrizione del post type
                'public'             => true, //se =true, viene visto sia da admin che in front-end
		'exclude_from_search' => false, //se =true gli elementi sono esclusi dalla ricerca front-end
		'publicly_queryable' => true, //indica se possono essere eseguite query lato front-end
		'show_ui'		=> true, //se =false, in admin non sarà mostrare l'interfaccia per la gestione del post type
		'show_in_nav_menus'	 => true, //indica se il post type può essere inserito nel nav menu
		'show_in_admin_bar'	 => true, //se =false, il post type non viene mostrato nel menu superiore "Nuovo" dell'admin

		//indica la posizione nei confronti degli altri elementi nel menu dell'admin.
		// 5 = sotto a Posts; 10 = a Media; 15 = a Links; 20 = a Pages; 25 = a Comments; 60 = al primo separatore;
		// 65 = a Plugins; 70 = a Users; 75 = a Tools; 80 = a Settings; 100 = al secondo separatore
		'menu_position'      => 5,

		'hierarchical'       => false, //indica se il post type ha un genitore (in genere usato solo per le pagine)

		//indica i valori del add_post_type_support() , ovvero quali elementi standard associare al post type
                'supports'      => array(
                                'title',
                                'editor',
                                'thumbnail',
				'excerpt'
                                ),

		//indica quali taxonomies associare al post type
		//il seguente, per esempio, permette di inserire categorie a cui associare i post type
		//in mancanza non sarà possibile creare categorie di post
		'taxonomies'		 => array('category'),

		'has_archive'        => true, //abilita la pagina di archivio per il post type

		//permette di riscrivere alcuni parametri per il post type, che altrimenti sarebbero uguali a quelli standard
		//
		'rewrite'            => array(
					'slug' => 'calendari' //il post type è raggiungibile all'indirizzo "mio_sito.it/calendari"
					)
    );

	//registra l'elemento "calendario" come post type, con gli argomenti definiti sopra
	register_post_type('calendario', $args);

}

La nostra funzione sarà poi inizializzata con questa riga:

1

add_action('init', 'crea_calendari');

Una volta attivato il plugin, nel menu laterale dell’admin avremo una nuova area: “Calendari Menu”. Da qui sarà possibile visualizzare l’elenco dei calendari, aggiungere un nuovo calendario e associare a ognuno di essi una categoria da creare. Proprio come nei normali post.

Visualizzare la pagina nel front-end : creare il link nel menu

A questo punto possiamo gestire tutto in lato amministrazione, ma in lato front-end non abbiamo ancora una struttura adatta. Infatti, dobbiamo manipolare il “single.php” e il “archive.php” perché visualizzino i nostri CPT e non i soliti post.

Innanzitutto, dobbiamo creare un link per permettere all’utente di raggiungere la nostra area CPT, che nel nostro caso sarà “mio_sito.it/calendari”.
Nell’admin entrate in “Aspetto => Menu”. Si presume che abbiate un’idea di dove ci troviamo e di come si gestiscono i menu in WordPress (se non è così vi consiglio di provare a smanettare: è piuttosto intuitivo; quest’area permette infatti di creare a piacere un menu di navigazione da mostrare in lato front-end).
Nello spazio “link” a sinistra, aggiungete al vosto menu l’url “mio_sito.it/calendari” e il nome “Calendari”. Ricordate di salvare le modifiche.

Single-calendario.php e Archive-calendario.php

Passiamo adesso a creare i nuovi file.
Quello che dobbiamo fare è creare una nuova versione di “single.php” e “archive.php”, aggiungendo al loro nome il suffisso “-calendario” (in pratica creeremo “single-calendario.php” e “archive-calendario.php”).

Nello zip troverete due file: “single-calendario.php” e “archive-calendario.php”. Non dovrete fare altro che copiarli nella cartella del vostro tema.
Da notare il suffisso di entrambi i file, “-calendario”, che è lo stesso nome con cui abbiamo registrato il nostro CPT. In pratica, WordPress riconoscerà automaticamente che questi due file sono rispettivamente il single e l’archive da usare per il nostro CPT.

Come li ho creati?
Semplicemente, ho preso esattamente il contenuto di “single.php” e l’ho copiato in “single-calendario.php” (nota: nel mio caso faccio riferimento al tema “twentyfourteen” messo in dotazione durante l’installazione di WordPress: in base al tema che voi usate, il contenuto del single potrebbe variare leggermente).
Dopodiché, ho aggiunto queste righe subito prima del ciclo che stampa gli articoli:

1
2
3
4
5
6

$args = array(      
	'post_type' => 'calendario',
	'post__in' => array(get_the_ID()), 
	'posts_per_page' => 1
);
query_posts($args);

In pratica sto dicendo a WordPress: «Prendi tutti gli articoli di tipo “calendario” e stampami solo quello con id del post attuale».
Questo perché ci troviamo all’interno di un articolo e quello che ci serve è estrarre e stampare le informazioni di quell’articolo.

Allo stesso modo, ho creato “archive-calendario.php” copiandolo da “archive.php” e aggiungendogli questa query iniziale:

1
2
3
4
5

$args = array(      
	'post_type' => 'calendario',
	'posts_per_page' => 10
);
query_posts($args);

In questo caso specifico a WordPress di prendere tutti gli articoli di tipo “calendario” e di stamparmi nella pagina solo i primi 10.

Note di chiarezza conclusive

Come abbiamo capito, la particolarità di WordPress è che leggerà automaticamente la presenza di un nuovo “single-{nome_custom}.php” e “archive-{nome_custom}.php”, dove a {nome_custom} dobbiamo inserire il nome del nostro CPT.

Entrando più nello specifico, quando nel front-end cliccheremo sul link “mio_sito.php/calendari” finiremo nella pagina di “archive-calendario.php”, che conterrà l’elenco dei primi 10 articoli-calendario.
Se cliccherete su uno degli articoli, verrete indirizzati alla pagina “single-calendario.php”, che mostrerà le informazioni del singolo articolo.

Naturalmente il contenuto di “single-calendario.php” e “archive-calendario.php” potrete personalizzarlo a piacere, a seconda delle vostre competenze nell’uso del codice php e di WordPress.

Per avere un’idea sul campo di cosa stiamo parlando, provate a creare alcuni articoli e vedete cosa accade quando visitere la pagina “mio_sito.php/calendari”.

I Post Type e i Custom Post Type sul codex ufficiale di WordPress

La funzione register_post_type sul codex ufficiale di WordPress