Hiérarchie des fichiers modèles

Les fichiers modèles des thèmes constituent les pièces du puzzle que WordPress assemble pour afficher les pages de votre site. Certains modèles (les fichiers d’entête ou de pied de page, par exemple) sont utilisés pour toutes les pages générées ; d’autres ne sont utilisés que sous certaines circonstances.

Cet article explique comment WordPress détermine quel fichier modèle utiliser pour chaque écran. Si vous voulez personnaliser un thème WordPress, cela vous aidera à savoir quel fichier modèle doit être modifié.

Note : vous pouvez aussi utiliser les marqueurs conditionnels pour déterminer les modèles qui seront chargés sur un écran spécifique.

Description de la hiérarchie des fichiers modèles

Vue d’ensemble

WordPress utilise la chaîne de requête pour déterminer le modèle à mettre en place pour afficher l’écran demandé. La chaîne de requête est une information contenue dans l’URL de chaque page de votre site.

Pour le dire simplement, WordPress parcourt la hiérarchie des fichiers modèles jusqu’à ce qu’il trouve un fichier modèle correspondant à la chaîne de requête demandée. Pour déterminer le fichier modèle à utiliser, WordPress suit le processus suivant :

1. Le CMS fait correspondre chaque chaîne de requête à un type de requête afin de déterminer l’écran en cours d’affichage (par exemple, l’écran des résultats de recherche, l’écran de liste des articles d’une catégorie donnée, etc.).
2. Il sélectionne le modèle à utiliser en utilisant l’ordre de la hiérarchie des fichiers modèles.
3. Il identifie parmi les fichiers modèles présents dans le répertoire du thème actif ceux qui correspondent à l’écran en cours d’affichage, et utilise le premier fichier modèle dans l’ordre de la hiérarchie.

À l’exception du fichier modèle de base index.php qui doit être présent dans tout thème, les personnes qui développent des thèmes sont libres de choisir si elles veulent ou non implémenter tel ou tel fichier modèle. Si WordPress ne trouve pas le premier fichier attendu pour le type d’écran dans la liste des fichiers modèles du thème actif, il passe au fichier suivant de la hiérarchie. En dernier lieu, si aucun fichier n’a été trouvé, c’est le fichier index.php qui sera utilisé.

Surcharge des modèles d’un thème en utilisant un thème enfant

Lorsque vous utilisez un thème enfant, tout fichier ajouté dans le répertoire de votre thème enfant sera chargé en lieu et place du fichier du même nom présent dans le thème parent. Par exemple, si les deux thèmes contiennent un fichier category.php, alors ce sera celui du thème enfant qui sera utilisé.

Si un thème enfant contient un fichier modèle spécifique tel que category-licornes.php et que le thème parent contient un fichier modèle moins prioritaire tel que category.php, alors c’est le fichier modèle category-licornes.php du thème enfant qui sera utilisé.

À l’inverse, si le thème enfant contient un modèle général tel que category.php alors que le thème parent contient un fichier modèle spécifique tel que category-licornes.php, alors c’est le fichier modèle du thème parent qui sera utilisé.

Exemples

Si votre site est accessible à l’adresse https://example.com/blog/ et si un internaute essaye d’accéder à une page de catégorie à l’adresse https://example.com/blog/category/photos-de-chatons/, alors WordPress va essayer de trouver un fichier modèle correspondant dans le répertoire de votre thème ou de votre thème enfant. La procédure est la suivante :

1. Recherche d’un modèle correspondant exactement au slug de catégorie passé dans l’URL. Dans l’exemple ci-dessus, le slug sera photos-de-chatons, WordPress cherchera donc un fichier category-photos-de-chatons.php.
2. Si le fichier category-photos-de-chatons.php n’existe pas et si l’identifiant de cette catégorie est 4 alors il cherchera un fichier nommé category-4.php.
3. Si le fichier category-4.php n’existe pas dans le thème, alors WordPress cherchera à utiliser un fichier modèle plus générique, category.php.
4. Si category.php n’existe pas, alors il cherchera à utiliser un fichier d’archive encore plus générique, archive.php.
5. Enfin, si WordPress ne trouve pas non plus de fichier archive.php alors il utilisera le fichier de base (obligatoirement présent) du thème, index.php.

Représentation graphique de la hiérarchie des fichiers modèles

Le schéma suivant montre l’arbre de décision utilisé par WordPress pour déterminer le fichier modèle à utiliser en fonction de la hiérarchie des fichiers modèles.

La hiérarchie des fichiers modèles en détail

Bien que la hiérarchie des fichiers modèles puisse être plus simple à visualiser sous la forme du diagramme ci-dessus, les sections suivantes décrivent l’ordre dans lequel les fichiers modèles sont appelés pour chaque type de requête.

Affichage de la page d’accueil d’un blog

Par défaut, WordPress est réglé pour afficher les derniers articles de blog sur la page d’accueil de votre site. Vous pouvez changer ce réglage pour utiliser une page d’accueil statique, mais ce cas est décrit dans la section suivante.

Par défaut, le fichier modèle home.php est utilisé pour afficher la liste des articles de votre blog. Si home.php n’existe pas, alors WordPress utilisera index.php.

Ordre des fichiers modèles :

1. home.php.
2. index.php.

À noter : si front-page.php existe, alors il est toujours utilisé pour votre page d’accueil à la place de home.php.

Affichage de la page d’accueil générale de votre site

Le fichier modèle front-page.php est utilisé pour afficher la page d’accueil de votre site, qu’elle soit réglée pour afficher les deniers articles (cas décrit dans la section précédente) ou une page statique (voir article concernant l’utilisation d’une page d’accueil statique). Le modèle de page d’accueil générale prend la priorité sur le modèle de page d’accueil du blog (home.php). Si le fichier front-page.php n’existe pas, alors WordPress utilisera soit home.php, soit le fichier page.php, suivant les réglages de lecture utilisés sur votre site. Si aucun de ces fichiers modèles n’existe dans votre thème, alors WordPress utilisera le fichier index.php.

1. front-page.php – utilisé pour la page d’accueil du blog comme pour la page d’accueil statique de votre site.
2. home.php – si WordPress ne trouve aucun fichier front-page.php dans le thème et si le site est configuré pour afficher les derniers articles du blog sur la page d’accueil, alors il essayera de charger ce fichier.
3. page.php – utilisé si vous avez configuré WordPress pour afficher une page d’accueil statique et si aucun fichier front-page.php n’existe dans votre thème.
4. index.php – utilisé si aucun fichier modèle décrit ci-dessus n’est proposé par le thème.

Affichage de la page de politique de confidentialité

Le fichier modèle privacy-policy.php est utilisé pour afficher la page de politique de confidentialité de votre site (voir les réglages de confidentialité).

Ordre des fichiers modèles :

1. privacy-policy.php.
2. Modèle de page personnalisé – le modèle de page assigné à la page.
3. page-{slug}.php – si le slug de la page est privacy, WordPress cherchera un fichier modèle page-privacy.php.
4. page-{id}.php – Si l’identifiant de la page est 6, WordPress cherchera un fichier modèle page-6.php.
5. page.php.
6. singular.php.
7. index.php.

Publication seule

Ordre des fichiers modèles :

1. single-{post-type}-{slug}.php – premièrement, WordPress va chercher un modèle permettant d’afficher cette publication spécifique. Par exemple, si le type de publication est product et si son slug est cookie, alors WordPress cherchera un fichier single-product-cookie.php.
2. single-{post-type}.php – si le type de publication est product, WordPress cherchera un fichier single-product.php.
3. single.php – ce sera le fichier modèle utilisé si aucun fichier ne correspond aux cas décrits ci-dessus.
4. singular.php – idem.
5. index.php.

Page seule

Fichier modèle utilisé pour afficher une page statique (sur WordPress, il s’agit du type de publication natif page). À noter que contrairement aux autres types de publication, les pages ont un comportement spécifique :

1. Modèle de page personnalisé – le modèle de page assigné à la page.
2. page-{slug}.php – si le slug de la page est contact, WordPress cherchera un fichier modèle page-contact.php.
3. page-{id}.php – si l’identifiant de la page est 6, WordPress cherchera un fichier modèle page-6.php.
4. page.php.
5. singular.php.
6. index.php.

Archive de catégorie

Ordre des fichiers modèles :

1. category-{slug}.php – si le slug de la catégorie est nouveautes, WordPress cherchera un fichier modèle category-nouveautes.php.
2. category-{id}.php – si l’identifiant de la catégorie est 4, WordPress cherchera un fichier modèle category-4.php.
3. category.php.
4. archive.php.
5. index.php.

Archive d’étiquette

Ordre des fichiers modèles :

1. tag-{slug}.php – si le slug de l’étiquette est france, WordPress cherchera un fichier modèle tag-france.php.
2. tag-{id}.php – si l’identifiant de l’étiquette est 4, WordPress cherchera un fichier modèle tag-4.php.
3. tag.php.
4. archive.php.
5. index.php.

Taxonomies personnalisées

Les taxonomies personnalisées suivent un ordre légèrement différent des taxonomies natives :

1. taxonomy-{taxonomy}-{term}.php – si la taxonomie est departement, et si le terme de taxonomie est ardeche, alors WordPress cherchera un fichier modèle taxonomy-departement-ardeche.php.
   Dans le cas spécifique des formats de publications, la taxonomie est nommée post_format et le terme de taxonomie est post-format-{format}. Cela donnera donc un fichier modèle taxonomy-post_format-post-format-link.php pour le format de publication ayant le slug link.
2. taxonomy-{taxonomy}.php – si la taxonomie est departement, WordPress cherchera le fichier modèle taxonomy-departement.php.
3. taxonomy.php.
4. archive.php.
5. index.php.

Types de publications personnalisés

Les types de publications personnalisés utilisent l’ordre suivant pour afficher leur page d’archive (liste des publications du même type) :

1. archive-{post_type}.php – si le type de publication est product, WordPress cherchera le fichier modèle archive-product.php.
2. archive.php.
3. index.php.

(pour le fichier modèle destiné à l’affichage d’une publication d’un type de publication donné, se référer à la section Publication seule).

Archive par auteur ou autrice

La page d’archive des articles publiés par un auteur ou une autrice est affichée selon l’ordre suivant :

1. author-{nicename}.php – si le slug du nom de l’auteur ou de l’autrice est camille, WordPress cherchera le fichier modèle author-camille.php.
2. author-{id}.php – si l’identifiant de l’auteur ou de l’autrice est 6, WordPress cherchera le fichier modèle author-6.php.
3. author.php.
4. archive.php.
5. index.php.

Archive par date

Les pages d’archive proposant une liste d’articles publiés à une date donnée sont générées dans l’ordre suivant :

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

Résultats de recherche

L’écran affichant la liste des résultats de recherche est généré dans l’ordre suivant :

1. search.php.
2. index.php.

Erreur 404 (page introuvable)

L’écran affichant la page d’erreur 404 est généré dans l’ordre suivant :

1. 404.php.
2. index.php.

Fichiers attachés

L’affichage d’un fichier attaché seul (type de publication attachment) utilise l’ordre suivant :

1. {MIME-type}.php – peut être n’importe quel type MIME. Par exemple, image.php, video.php, pdf.php.
   Pour le type MIME text/plain, l’ordre suivant est utilisé :
   1. text-plain.php.
   2. plain.php.
   3. text.php.
2. attachment.php.
3. single-attachment-{slug}.php – par exemple, si le slug du fichier attaché est vacances, WordPress cherchera le fichier modèle single-attachment-vacances.php.
4. single-attachment.php.
5. single.php.
6. singular.php.
7. index.php.

Publications embarquées

Le modèle des publications embarquées est utilisé pour afficher une publication lorsqu’elle est embarquée sur une autre publication.

1. embed-{post-type}-{post_format}.php – WordPress cherche d’abord un modèle utilisable lorsque la publication à embarquer utilise un type de publication spécifique avec un format spécifique. Par exemple, si le type de publication est post et s’il a le format audio, alors WordPress cherchera le fichier modèle embed-post-audio.php.
2. embed-{post-type}.php – si le type de publication est product, WordPress cherchera embed-product.php.
3. embed.php – le fichier modèle générique pour tous les contenus embarqués.
4. En derniers recours, WordPress utilisera son propre fichier modèle, que vous pouvez trouver au chemin suivant sur votre installation WP : wp-includes/theme-compat/embed.php.

Gestion des caractères spéciaux

Depuis WordPress 4.7, les caractères spéciaux sont supportés, dans l’ordre suivant pour une page nommée « Bonjour tout le monde 😀 » et ayant l’identifiant 6:

• page-bonjour-tout-le-monde-😀.php.
• page-bonjour-tout-le-monde-%f0%9f%98%80.php (code de l’émoticône).
• page-6.php.
• page.php.
• singular.php.

Le même comportement s’applique pour les autres types de publications, les noms de termes de taxonomies, ou encore les auteurs et autrices.

Modifier la hiérarchie des fichiers modèles

Le système de modèles de WordPress vous permet de modifier la hiérarchie des fichiers modèles à l’aide de filtres. Le filtre à utiliser (voir la documentation de la fonction get_query_template() (en anglais) sera toujours {$type}_template, où $type correspond au type de modèle.

Voici une liste des filtres disponibles nativement dans la hiérarchie des fichiers modèles :

• embed_template
• 404_template
• search_template
• frontpage_template
• home_template
• privacypolicy_template
• taxonomy_template
• attachment_template
• single_template
• page_template
• singular_template
• category_template
• tag_template
• author_template
• date_template
• archive_template
• index_template

Exemple d’utilisation du filtrage des fichiers modèles

Par exemple, prenons la hiérarchie des fichiers modèles utilisée par défaut pour l’affichage des archives de contenus d’un auteur ou d’une autrice :

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

Si l’on souhaite ajouter un type de fichier modèle author-{role}.php qui serait utilisé avant de basculer sur author.php, il est possible de manipuler la hiérarchie en utilisant le filtre author_template. Le résultat serait que par exemple, pour une requête d’URL /author/camille où le compte camille aurait un rôle editor (correspondant au rôle d’éditeur/éditrice), la page d’archive pourrait être générée par le fichier modèle author-editor.php s’il est présent dans le répertoire du thème actif.

Exemple d’implémentation :

function wpdocs_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', 'wpdocs_author_role_template' );

Ressources

• Cours Template Hierarchy sur Learn WordPress (en anglais)
• Cours Template Tour sur Learn WordPress (en anglais)

Traduit par Jb Audras
Relu par Marie-Aude Koiransky & Jenny Dupuy
Dernière mise à jour le 17 août 2022

Contribuer à la documentation en français de WordPress