Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Gerarchia dei template

Introduzione

I template di WordPress si combinano fra di loro come i pezzi di un puzzle per generare le pagine web del vostro sito WordPress. Alcuni template (ad esempio i file di template della testata e del piè di pagina) sono utilizzati in tutte le pagine mentre altri sono utilizzati solo per specifiche condizioni.

Di cosa parla questo articolo

Questo articolo cerca di rispondere alla seguente domanda:

Quale/i file utilizza WordPress quando si visualizza un certo tipo di pagina?

A chi può essere utile

Dall'introduzione dei Temi in WordPress 1.5, I Templates sono diventati sempre più configurabili. Per poter sviluppare temi per WordPress è essenziale comprendere a fondo il modo in cui WordPress seleziona i file dei template per visualizzare le varie pagine del blog. Se si cerca di personalizzare un tema di WordPress già esistente, questo articolo ha lo scopo di aiutarvi a decidere quale file dei template occorre modificare.

Utilizzo dei Tag condizionali

WordPress fornisce più di una via per far corrispondere i template al tipo di query. Gli sviluppatori di temi per WordPress possono utilizzare i Tag condizionali per controllare quali template verranno utilizzati per generare una certa pagina. Alcuni temi WordPress possono non implementare tutti i file dei template descritti in questo articolo. Alcuni temi usano i tag condizionali per caricare altri file dei template. Per ulteriori informazioni si veda la pagina Tag condizionali e "Basato su query" nello sviluppo dei temi.

La gerarchia dei file dei template

L'idea generale

WordPress utilizza le informazioni della Query String — contenute in ciascun link del proprio sito web — per decidere qual template o insiemi di template verranno utilizzati per visualizzare la pagina.

Per prima cosa, WordPress fa corrispondere ciascuna Query String ad un tipo di query — decide che tipo di pagina è stata richiesta (una pagina di ricerca, una pagina di categoria, l'home page ecc.).

Quindi vengono selezionati i template — e viene generato il contenuto della pagina web — nell'ordine suggerito dalla gerarchia dei template di WordPress, in funzione di quali template sono disponibili in uno specifico Tema WordPress.

WordPress cerca, nella directory del tema corrente, file dei template con nomi specifici ed utilizza il file dei template che corrisponde per primo nella sezione di query appropriata come elencato di seguito.

Con l'eccezione del file dei template di base index.php, gli sviluppatori dei temi possono scegliere se implementare o meno un particolare file di template. Se WordPress non riesce a trovare un file di template con il nome corrispondente, passa al nome di file successivo nella gerarchia. Se WordPress non riesce a trovare nessuna file di template corrispondente alle sue necessità verrà usato il file index.php (il file di template usato per la home page del tema).

Esempi

Se ad esempioil vostro blog si trova su http://example.com/blog/ ed un visitatore fa clic su un link ad una categoriadel tipo http://example.com/blog/category/mia-cat/: Ecco la sequenza che utilizza WordPress nella gerarchia dei template per cercare e generare il file corretto.

WordPress cerca un file di template nella directory del tema corrente che corrisponda all'ID di categoria.

  1. Se la categoria ha come abbreviazione (slug) mia-cat, WordPress cerca un template di nome category-mia-cat.php.
  2. Se non lo trova e l'ID di categoria è 4, WordPress cerca un template di nome category-4.php.
  3. Se manca, WordPress cerca in seguito un file generico di categoria, category.php.
  4. Se anche questo file non esiste allora WordPress cerca un fle di template di archivio generico, archive.php.
  5. Infine se manca anche questo file, WordPress utilizza alla fine il file di template principale del tema, index.php.

Se un visitatoe arriva alla vostra home page a http://example.com/blog/, si verifica la seguente sequenza:

  1. WordPress per prima cosa determina se ha una pagina frontale statica. Se è impostata una pagina statica allora WordPress carica questa pagina secondo la gerarchia dei template di pagina.
  2. Se non è stata impostata una pagina iniziale statica allora WordPress cerca un file dei template di nome home.php e lo utilizza per generare la pagina richiesta.
  3. Se manca home.php WordPress cerca nella drectory del tema correntemente attivo un file denominato index.php e utilizza questo template per generare la pagina.

Schema generale

Il seguente diagramma mostra quali file di template vengono richiamati per generare una pagina di WordPress in base alla gerarchia dei template di WordPress.

Schema grafico della struttura della gerarchia dei template di WordPress Immagine a dimensione reale (png)

Un diagramma più dettagliato, che comprende anche i tag condizionali relativi ai template e le classi CSS inserite nel body, è disponibile qui.

La gerarchia dei template in dettaglio

La sezione seguente descrive l'ordine con il quale i file dei template vengono richiamati da WordPress per ciascun tipo di query.

Visualizzazione Home Page

File dei template utilizzato per visualizzare l'indice degli articoli del blog, sia che vi sia o meno una pagina iniziale statica. Nota: nel caso di Paigina inziale del sito, il template per la Front Page ha la precedenza rispetto al template per l'indice degli articoli del blog (Home).

  1. home.php
  2. index.php

Visualizzazione Pagina iniziale

File dei template utilizzato per visualizzare la pagina iniziale del sito, quando la pagina iniziale mostra un indice degli articoli del bog o una pagina statica. il template per la Front Page ha la precedenza rispetto al template per l'indice degli articoli del blog (Home).

  1. front-page.php - Utilizzato sia per Gli ultimi articoli' o per Una pagina statica secondo le impostazioni della sezione La pagina iniziale mostra: in Impostazioni -> Lettura
  2. Regole di visualizzazione pagina - Quando nella sezione La pagina iniziale mostra: in Impostazioni -> Lettura il template per la Pagina iniziale ha la precedenza rispetto al template per l'indice degli articoli del blog (Home).
  3. Regole di visualizzazione Home Page - Quando nella sezione La pagina iniziale mostra: in Impostazioni -> Lettura viene impostato Pagina articoli

Visualizzazione articolo singolo

File di template utilizzato per mostrare una pagina di un singolo articolo.

  1. single-{post_type}.php - Se il post type fosse prodotto, WordPress cercherà single-prodotto.php.
  2. single.php
  3. index.php

Visualizzazione pagina

File di template utilizzato per mostrare una pagina statica (post-type page)

  1. file di template personalizzato - Il Template di pagina assegnato alla Pagina. Si veda get_page_templates().
  2. page-{slug}.php - Se l'abbreviazione (slug) della pagina è news-recenti, WordPress cercherà di utilizzare page-news-recenti.php
  3. page-{id}.php - Se l?ID di pagina è 6, WordPress cercherà di utilizare page-6.php
  4. page.php
  5. index.php

Visualizzazione categoria

File di template utilizzato per mostrare una pagina di indice archivio di categoria

  1. category-{slug}.php - Se l'abbreviazione della categoria fosse news, WordPress cercherà category-news.php
  2. category-{id}.php - Se l'ID di categoria fosse 6, WordPress cercherà category-6.php
  3. category.php
  4. archive.php
  5. index.php

Visualizzazione tag

File di template utilizzato per mostrare una pagina di indice archivio di tag

  1. tag-{slug}.php - Se l'abbreviazione del tag fosse untag, WordPress cercherà tag-untag.php
  2. tag-{id}.php - Se l'ID del tag fosse 6, WordPress cercherà tag-6.php
  3. tag.php
  4. archive.php
  5. index.php

Visualizzazione tassonomie personalizzate

File di template utilizzato per mostrare una pagina di indice archivio per una Tassonomia personalizzata

  1. taxonomy-{taxonomy}-{term}.php - Se la tassonomia fosse unatax, ed il terminae della tassonomia fosse untermine WordPress cercherà taxonomy-unatax-untermine.php. Nel caso di un formato articolo, la tassonomia è 'post_format' ed il termine è 'post-format-{formato}. Quindi taxonomy-post_format-post-format-link.php
  2. taxonomy-{taxonomy}.php - Se la tassonomia fosse unatax, WordPress cercherà taxonomy-unatax.php
  3. taxonomy.php
  4. archive.php
  5. index.php

Visualizzazione di tipi articoli personalizzati (Custom Post Types)

File di template utilizzato per mostrare una pagina di indice archivio per un tipo di articolo personalizzato (Custom Post Type)

  1. archive-{post_type}.php - Se il tipo articolo fosse prodotto, WordPress cercherà archive-prodotto.php.
  2. archive.php
  3. index.php

(Per mostrare in singolo tipo di articolo personalizzato si faccia riferimento alla sezione precedente Visualizzazione singolo articolo.)

Visualizzazione autore

File di template utilizzato per mostrare una pagina di indice archivio per un autore

  1. author-{nicename}.php - Se il nice name dell'autore fosse rami, WordPress cercherà author-rami.php.
  2. author-{id}.php - Se l'ID dell'autore fosse 6, WordPress cercherà author-6.php.
  3. author.php
  4. archive.php
  5. index.php

Visualizzazione date

File di template utilizzato per mostrare una pagina di indice archivio in base ad una data

  1. date.php
  2. archive.php
  3. index.php

Visualizzazione risultati ricerca

File di template utilizzato per mostrare una pagina di indice archivio per una ricerca

  1. search.php
  2. index.php

Visualizzazione 404 (Non trovato)

File di template utilizzato per mostrare una pagina di errore Server 404

  1. 404.php
  2. index.php

Visualizzazione allegati

File di template utilizzato per mostrare la pagina di un singolo allegato (post-type attachment)

  1. MIME_type.php - Può essere un qualsiasi MIME type (image.php, video.php, application.php). Per text/plain, nell'ordine:
    1. text.php
    2. plain.php
    3. text_plain.php
  2. attachment.php
  3. single-attachment.php
  4. single.php
  5. index.php

Filtri della gerarchia

Il sitema di template di WordPress permette di filtrare la gerarchia. Il filtro (che si trova nella funzione get_query_template() ) utilizza il filtro di nome: "{$type}_template" dove $type è il nome del file nella gerarchia senza l'estensione .php.

Elenco completo:

  • index_template
  • 404_template
  • archive_template
  • author_template
  • category_template
  • tag_template
  • taxonomy_template
  • date_template
  • home_template
  • front_page_template
  • page_template
  • paged_template
  • search_template
  • single_template
  • text_template, plain_template, text_plain_template (Tutti i mime types)
  • attachment_template
  • comments_popup


Esempio

Prendiamo ad esempio la gerarchia standard per gli autori:

  • author-{nicename}.php
  • author-{id}.php
  • author.php

Per aggiungere author-{role}.php prima di author.php dobbiamo manipolare la gerarchia attuale utilizzando l'hook 'author_template'. Ciò permette ad una richiesta per /author/username dove username ha il ruolo di editore di utilizzare per la visualizzazione author-editor.php se questo è presente nella directory del tema.

function author_role_template( $templates='' )
{
	$author = get_queried_object();
	$role=$author->roles[0];
	
	if(!is_array($templates) && !empty($templates)) {
		$templates=locate_template(array("author-$role.php",$templates),false);
	} 
	elseif(empty($templates)) {
		$templates=locate_template("author-$role.php",false);
	}
	else {
		$new_template=locate_template(array("author-$role.php"));
		if(!empty($new_template)) array_unshift($templates,$new_template);
	}
	
	return $templates;
}
add_filter( 'author_template', 'author_role_template' );

Changelog

  • 1.5 :
    • Introduzione del sistema dei temi.

File sorgente

Correlati

Template Hierarchy: Category Templates, Tag Templates, Taxonomy Templates, Page Templates, Post Type Templates, Author Templates, Date Templates, Search Templates, 404 Templates, Attachment Templates, Loop Templates