Créer une page d’archive pour les taxonomies personnalisées de WordPress

Les taxonomies personnalisées sont aux custom post types ce que les catégories ou les tags sont aux articles. En termes clairs, un type de contenu personnalisé peut disposer d’un classement qui lui est propre.

Personnaliser la page d’archive d’une catégorie passe par le fichier category.php de votre thème, mais comment faire de même pour vos taxonomies ?

Commençons par rappeler l’architecture d’un thème WordPress – notamment pour ce qui est de la gestion des archives. Je vous renvoie à la hiérarchie des modèles de la documentation officielle, rubrique Custom Taxonomies.

Prenons un cas d’exemple simple : un custom post type Produits et une taxonomie personnalisée Catégories de produits.

La taxonomie liste des termes comme Livres, DVD, CD.

Ainsi, selon la hiérarchie des modèles, nous avons le choix entre 3 fichiers de taxonomie. Tout dépend du niveau de hiérarchie et de personnalisation à atteindre :

• taxonomy.php : le fichier de base pour afficher les archives d’une taxonomie personnalisée. Dans notre exemple, il s’agit des catégories de produits. Mais le même fichier sera utilisé si vous créez d’autres taxonomies sur-mesure ;
• taxonomy-NOM_DE_LA_TAXONOMIE_PERSO.php : ce fichier est déjà plus intéressant. Il suffit d’indiquer l’identifiant exact de la taxonomie personnalisée que vous avez créée, c’est-à-dire le premier paramètre de la fonction register_taxonomy(), et non son libellé. Ici, ce fichier sera de la forme taxonomy-categorie_produits.php par exemple et affichera les données issues des différentes catégories de produits ;
• taxonomy-TAXO_PERSO-TERME.php : les livres, les DVD ou encore les CD constituent les termes de notre taxonomie personnalisée Catégories de produits. Nous pouvons créer un fichier pour chacun de ces termes, désigné par son slug, pour pousser encore plus la personnalisation : taxonomy-categorie_produits-livres.php. Depuis WordPress 6.9, l’ID du terme fonctionne aussi (taxonomy-categorie_produits-12.php), mais le fichier qui porte le slug reste prioritaire.

Si aucun de ces fichiers n’existe dans votre thème, WordPress se rabat sur archive.php, puis sur index.php.

Je vous suggère de commencer simplement par le fichier taxonomy.php dans le cas où vous n’utilisez qu’une taxonomie sur-mesure.

Pour ce faire, connectez-vous sur votre serveur FTP puis localisez le dossier /wp-content/themes/NOM_DU_THEME/ et créez le fichier taxonomy.php pour débuter. Si votre thème reçoit des mises à jour, créez plutôt ce fichier dans le dossier de votre thème enfant : la prochaine mise à jour du thème ne l’effacera pas, et WordPress l’utilisera en priorité sur le fichier archive.php du thème parent.

Comme il s’agit d’une page d’archive classique, vous pouvez très bien copier / coller le code source du fichier archive.php et appliquer des modifications à votre guise (indiquer une sidebar spéciale, appliquer de nouvelles classes CSS, etc.).

Si votre thème n’a pas de fichier archive.php, ou si vous préférez partir d’une base propre, voici un exemple de fichier taxonomy-categorie_produits.php, à adapter à la structure et aux classes CSS de votre thème :

<?php
/**
 * Archive template of the terms of the "categorie_produits" taxonomy.
 */

get_header();
?>

<main id="main" class="site-main">

	<header class="page-header">
		<?php
		the_archive_title( '<h1 class="page-title">', '</h1>' );
		the_archive_description( '<div class="archive-description">', '</div>' );
		?>
	</header>

	<?php if ( have_posts() ) : ?>

		<?php
		while ( have_posts() ) :
			the_post();
			?>
			<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
				<h2 class="entry-title">
					<a href="<?php echo esc_url( get_permalink() ); ?>"><?php echo esc_html( get_the_title() ); ?></a>
				</h2>
				<?php the_excerpt(); ?>
			</article>
		<?php endwhile; ?>

		<?php the_posts_pagination(); ?>

	<?php else : ?>

		<p><?php esc_html_e( 'No products in this category yet.', 'wpchannel' ); ?></p>

	<?php endif; ?>

</main>

<?php
get_footer();

La fonction the_archive_title() affiche le nom du terme consulté, précédé de celui de la taxonomie (« Catégorie de produits : Livres »), et the_archive_description() sa description, si vous en avez saisi une. La boucle liste ensuite les produits du terme : leur titre et leur adresse sont échappés avec esc_html() et esc_url() avant d’être affichés. Enfin, the_posts_pagination() ajoute les liens vers les pages suivantes quand le terme compte plus de produits que le nombre d’articles par page défini dans Réglages > Lecture.

Retournez à présent sur votre site puis tentez d’accéder à une catégorie de produits. Si vous venez de déclarer la taxonomie, vous obtiendrez sans doute une page d’erreur 404 : c’est normal ! WordPress n’a pas encore enregistré les règles de réécriture de ses adresses. Rendez-vous dans Réglages > Permaliens, dans le back office de WordPress : le simple affichage de cet écran régénère ces règles, sans rien modifier.

Actualisez la page pour constater le bon affichage des données.

La page reste en erreur 404, ou s’affiche sans aucun produit ? Vérifiez la déclaration de votre taxonomie et de votre type de contenu :

• contrairement à register_post_type(), register_taxonomy() n’a pas de paramètre has_archive : chaque terme dispose de sa page d’archive dès lors que la taxonomie est publique. Les paramètres public et publicly_queryable valent true par défaut ; si l’un d’eux vaut false, l’adresse d’un terme renvoie vers la page d’accueil ;
• par défaut, l’adresse d’un terme reprend l’identifiant de la taxonomie (/categorie_produits/livres/). Le paramètre rewrite permet de la modifier : 'rewrite' => array( 'slug' => 'categorie-produits' ) donne /categorie-produits/livres/, tandis que 'rewrite' => false la remplace par /?categorie_produits=livres. Après chaque changement, repassez par Réglages > Permaliens ;
• si votre type de contenu est déclaré avec 'exclude_from_search' => true, l’archive s’affiche mais reste vide : sur une page de taxonomie, WordPress ne cherche que parmi les types de contenu inclus dans la recherche.

Dans ce dernier cas, laissez ce paramètre à false ou, si vos produits doivent rester absents des résultats de recherche, indiquez à WordPress le type de contenu à afficher sur ces archives, dans le fichier functions.php de votre thème enfant :

function wpc_produits_taxonomy_archive( $query ) {
	if ( ! is_admin() && $query->is_main_query() && $query->is_tax( 'categorie_produits' ) ) {
		$query->set( 'post_type', 'produit' );
	}
}
add_action( 'pre_get_posts', 'wpc_produits_taxonomy_archive' );

Avec un thème à blocs

Avec un thème à blocs comme Twenty Twenty-Five, les modèles ne sont plus des fichiers PHP mais des fichiers HTML, rangés dans le dossier templates du thème. La hiérarchie reste la même : taxonomy-categorie_produits-livres.html, taxonomy-categorie_produits.html, taxonomy.html, puis archive.html et index.html.

Le plus simple reste toutefois de créer ce modèle sans code, depuis l’éditeur du site :

1. rendez-vous dans Apparence > Éditeur > Modèles et cliquez sur Ajouter un modèle ;
2. choisissez Archives de Catégorie de produits : WordPress forme ce libellé avec le nom au singulier de votre taxonomie ;
3. sélectionnez Pour tous les éléments, ou Pour un élément spécifique pour réserver le modèle à un seul terme, Livres par exemple ;
4. dans la fenêtre Choisir une composition, cliquez sur Contenu de secours : le modèle reprend le contenu de celui que votre thème utilisait jusqu’ici pour ces pages (avec Twenty Twenty-Five, le modèle Toutes les archives : titre, description du terme et liste des contenus) ;
5. adaptez la mise en page à votre guise, puis enregistrez.

Si votre taxonomie n’apparaît pas dans la liste, vérifiez qu’elle est déclarée avec 'show_in_rest' => true : sans ce paramètre, l’éditeur du site ne la voit pas. Un fichier HTML placé dans le dossier templates du thème fonctionne, lui, dans tous les cas.

En ayant suivi ce tutoriel, vous devriez être en-mesure de créer des pages d’archives de vos différentes rubriques de façon personnalisée en fonction des données affichées.

Pour aller plus loin, voyez comment classer une archive de CPT selon les termes d’une taxonomie.