taxonomy.php : le gabarit générique de toute taxonomie personnalisée

Une extension qui déclare une taxonomie personnalisée avec register_taxonomy() ne fournit jamais son propre gabarit d’affichage : c’est au thème de savoir l’habiller. Quand ce dernier n’a rien prévu de spécifique, l’archive de cette taxonomie ne casse pas pour autant, elle retombe sur un fichier générique trop souvent absent des thèmes classiques : taxonomy.php.

Ce que couvre exactement ce fichier

La hiérarchie de templates réservée aux taxonomies suit un ordre précis. Pour une taxonomie nommée destination et un terme bretagne, WordPress cherche d’abord taxonomy-destination-bretagne.php, puis taxonomy-destination.php, puis enfin taxonomy.php. Ce dernier fichier n’a besoin de connaître ni le nom de la taxonomie ni celui du terme affiché : il s’appuie sur des fonctions génériques comme single_term_title() ou get_queried_object() pour afficher le bon intitulé, quel que soit le contexte réel de la requête.

Deux taxonomies bien connues du cœur, la catégorie et l’étiquette, ne passent jamais par ce fichier : elles disposent de leur propre branche de hiérarchie, avec category.php et tag.php. taxonomy.php ne concerne donc que les taxonomies déclarées par un thème ou une extension, jamais les deux taxonomies natives des articles.

Comportement réel et cas limites

Un cas limite fréquent concerne les taxonomies déclarées avec l’argument 'public' => false ou sans 'rewrite' activé : leur archive n’a alors aucune URL publique accessible, et taxonomy.php ne se déclenche jamais pour elles, même s’il existe dans le thème. Autre cas limite : une taxonomie partagée entre plusieurs types de contenu (par exemple une taxonomie de destination utilisée à la fois par des articles et par un type personnalisé « circuit ») affiche dans taxonomy.php un mélange des deux types de contenu dans la même boucle, ce qui surprend souvent lors des premiers tests si le gabarit ne filtre pas explicitement par post_type.

Il faut aussi noter que taxonomy.php reçoit exactement la même requête principale que celle affichée normalement par archive.php pour les types de contenu personnalisés : la variable globale $wp_query contient déjà tous les articles du terme demandé, sans qu’aucune requête additionnelle ne soit nécessaire dans le gabarit lui-même.

Pièges fréquents en intégration

• Un thème qui ne fournit ni taxonomy.php ni archive.php, et qui retombe alors sur index.php sans que personne ne comprenne pourquoi l’archive de la taxonomie ressemble à la page d’accueil.
• Une condition is_tax() ajoutée par précaution dans archive.php pour distinguer les taxonomies personnalisées, alors qu’un simple fichier taxonomy.php aurait évité cette branche de code entière.
• Un titre de terme affiché en anglais ou avec des balises HTML brutes faute d’utiliser single_term_title(), qui échappe correctement le nom du terme contrairement à un accès direct à l’objet du terme.

Cas concret avec code

Voici un taxonomy.php qui affiche le nom et la description du terme, puis la liste des contenus associés, quel que soit le type de contenu concerné :

<?php get_header(); ?>

<main id="contenu-taxonomie">
  <header class="archive-header">
    <h1><?php single_term_title(); ?></h1>
    <?php
    $description = term_description();
    if ( ! empty( $description ) ) {
        echo '<div class="archive-description">' . wp_kses_post( $description ) . '</div>';
    }
    ?>
  </header>

  <?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
      <article>
        <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
        <?php the_excerpt(); ?>
      </article>
    <?php endwhile; ?>
    <?php the_posts_pagination(); ?>
  <?php else : ?>
    <p>Aucun contenu associé à ce terme pour l'instant.</p>
  <?php endif; ?>
</main>

<?php get_footer(); ?>

La fonction term_description() récupère automatiquement la description saisie dans l’écran d’édition du terme, indépendamment de la taxonomie concernée.

Quand ne pas s’arrêter à ce fichier

Dès qu’une taxonomie précise nécessite un affichage vraiment différent des autres, par exemple une grille de vignettes pour une taxonomie de destinations touristiques quand toutes les autres taxonomies s’affichent en simple liste, il vaut mieux créer taxonomy-destination.php plutôt que de multiplier les conditions dans taxonomy.php. Ce dernier reste pertinent comme filet de sécurité générique, pas comme lieu où empiler des if ( is_tax( 'destination' ) ) qui finissent par le rendre illisible.

Un gabarit générique n’a de valeur que tant qu’il reste générique. Dès qu’une taxonomie mérite un traitement à part, mieux vaut lui donner son propre fichier que de charger taxonomy.php de conditions qui ne concernent qu’elle.

Garder ce fichier simple, appuyé sur les fonctions génériques du cœur plutôt que sur des conditions nominatives, évite qu’il ne devienne au fil des extensions installées un empilement de cas particuliers impossible à maintenir.