Le Marqueur de Modèle wp_list_categories(anglais), affiche une liste de Categories(anglais) en tant que liens. Quand un lien vers une catégorie est cliqué, tous les posts de cette Catégorie s'afficheront dans une Page Catégorie utilisant le Modèle de Catégorie(anglais) décrit dans les Règles de Hiérarchie des modèles.
wp_list_categories(anglais) fonctionne de la même manière que les deux Marqueurs de Modèle des versions de WordPress antérieures à la version 2.1 que sont : list_cats()(anglais) (obsolète), et wp_list_cats()(anglais) (obsolète).
<?php wp_list_categories('arguments'); ?>
$defaults = array('show_option_all' => '', 'orderby' => 'name', 'order' => 'ASC',
'show_last_update' => 0, 'style' => 'list','show_count' => 0, 'hide_empty' => 1,
'use_desc_for_title' => 1, 'child_of' => 0, 'feed' => '', 'feed_image' => '',
'exclude' => '', 'hierarchical' => true, 'title_li' => __('Categories'));
By default, the usage shows:
wp_list_categories();
Pour créer une liste classée par ordre alphabétique incluant seulement les Catégories dont les IDs sont 3, 5, 9 et 16, vous utiliserez, par exemple, le code suivant :
<ul>
<?php
wp_list_categories('orderby=name&include=3,5,9,16'); ?>
</ul>
L'exemple suivant affiche les catégories ordonnées par nom, montre le nombre de posts contenu dans chaque Catégorie, et exclue de la liste la Catégorie dont l'ID est 10.
<ul>
<?php
wp_list_categories('orderby=name&show_count=1&exclude=10'); ?>
</ul>
Le paramètre title_li permet de définir ou de masquer un titre pour la liste de Catégories générée par wp_list_categories. Par défaut, le paramètre est définit par '(__('Categories')', c'est-à-dire que le mot "Catégories" s'affiche comme titre de la liste. Aucun titre ne s'affiche si le paramètre est définit par une valeur vide ou nulle.
L'exemple de code suivant exclue les Catégories dont les IDs sont 4 ou 7 et masque le titre de la liste :
<ul>
<?php
wp_list_categories('exclude=4,7&title_li='); ?>
</ul>
Dans l'exemple suivant, seules les Catégories dont les IDs sont 9, 5 et 23 sont inclues et on a changé le titre de la liste pour le mot "Prose" stylisé avec une balise de titre <h2> :
<ul>
<?php
wp_list_categories('include=5,9,23&title_li=<h2>' . __('Prose') . '</h2>' ); ?>
</ul>
L'exemple de code suivant affiche les Sous-Catégories (ou 'Catégories Filles') de la 'Catégorie Mère' dont l'ID est 8, ordonnées par ID. Le nombre de posts de chaque Catégorie est visible, et l'attribut title des liens générés n'est pas renseigné par les Descriptions des Catégories.
Note: Si la 'Catégorie Mère' ne contient pas de post, elle ne s'affichera pas dans la liste.
<ul>
<?php wp_list_categories('orderby=id&show_count=1
&use_desc_for_title=0&child_of=8'); ?>
</ul>
L'exemple suivant génère une liste ordonnée par nom des Catégories, montre le nombre de posts par Catégorie, et fournit les liens vers les flux RSS de chaque Catégorie.
<ul>
<?php
wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
</ul>
Si vous souhaitez remplacer les liens vers les flux RSS par des images RSS, écrivez par exemple :
<ul>
<?php
wp_list_categories('orderby=name&show_count=1
&feed_image=/images/rss.gif'); ?>
</ul>
Par défaut, wp_list_categories() génère des éléments de liste <li> d'une liste non-ordonnée <ul>. Tous les éléments de la liste générée par wp_list_categories() sont marquée par la classe "page_item". Quand wp_list_categories() est appelée dans une Page 'Catégorie', l'élément de la liste qui désigne cette page en question sera marqué par une classe supplémentaire "current_page_item":
<ul>
<li class="page_item current_page_item">
[the current page]
</li>
<li class="page_item">
[another page]
</li>
</ul>
Ce qui pourra visuellement donner, par exemple, quand on se situe sur la Page Informatique :
Vous pouvez définir le style de ces classes dans une feuille de style CSS(anglais) :
.page_item { ... }
.current_page_item { ... }
Note : Les éléments de la liste générée par wp_list_categories (sauf si le paramètre style est définit par none) nécessite l'ouverture et la fermeture d'une balise <ul>. Voir les exemples ci-dessus.