La Boucle (The Loop) est utilisée par WordPress pour afficher chacun de vos Articles. Par l'utilisation de La Boucle, WordPress traite tous les Articles devant être affichés sur la page active et adapte leur présentation en utilisant les critères décrits par les marqueurs de La Boucle. Tous les morceaux de code HTML ou PHP placés entre le début et la fin de La Boucle seront exécutés pour chaque Article. Quand la documentation de WordPress signifie que "Ce Marqueur doit être inséré dans La Boucle", comme pour les Marqueurs de Modèle spécifiques ou des plugins, c'est de La Boucle dont on parle.
Par exemple, dans WordPress 1.5, parmis les informations affichées par défaut par La Boucle, on trouve : le titre (the_title()), l'heure (the_time()), et les Catégories (the_category()) de chaque Article. D'autres informations peuvent être affichées pour chaque Article en utilisant les Marqueurs de Modèle appropriés, ou (pour les utilisateurs avancés) en accédant à la variable $post, qui contient les informations de l'Article quand La Boucle est en cours d'exécution.
Pour les débutants, un aperçu de La Boucle est disponible ici : The Loop in Action (en anglais).
La Boucle doit être présente dans index.php et dans tous les fichiers du Thème affichant des Articles. Elle est légèrement différente selon votre version de WordPress. En premier lieu, vous devriez "trouver quelle version de WordPress vous utilisez".
Elle est (probablement) la même que pour WordPress 1.5
Assurez-vous que l'appel au header du modèle est réalisé au début de votre modèle de Thème. Si vous utlisez La Boucle dans une de vos créations (et que ce n'est pas un modèle), mettez WP_USE_THEMES à false.
<?php define('WP_USE_THEMES', false); get_header(); ?>
La Boucle commence ici :
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
et finit là :
<?php endwhile; else: ?>
<p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
<?php endif; ?>
Assurez-vous que l'appel du fichier wp-blog-header.php est fait au début de votre page index. N'oubliez pas que le chemin d'accès du fichier wp-blog-header.php doit être le même que celui du fichier wp-blog-header.php :
<?php /* Don't remove this line. */ require('./wp-blog-header.php'); ?>
La Boucle commence ici :
<?php if ( $posts ) : foreach ( $posts as $post ) : start_wp(); ?>
et finit là :
<?php endforeach; else: ?>
<p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
<?php endif; ?>
Pour WordPress v1.5 seulement
Cet exemple, utilisant la syntaxe pour version 1.5, affiche chaque Article avec son Titre (qui est utilisé comme lien vers le Permalien de l'Article), sa Catégories, et son Contenu. C'est un exemple très simple, et vos thèmes utiliseront probablement plus d'informations dont l'affichage sera grandement facilité par l'utilisation de styles CSS.
Cependant, afin d'être un peu plus didactique, cet exemple permet l'utilisation d'un style différent pour les Articles de la Catégorie 3. Pour cela, le Marqueur de Modèle in_category() est utilisé.
La balise <!-- --> est un commentaire HTML qui ne sera pas utilisé par les navigateurs si vous utilisez cet exemple. Elle ne sert qu'à annoter le code.
<!-- Début de la Boucle. -->
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<!-- Ce qui suit teste si l'Article en cours est dans la Catégorie 3. -->
<!-- Si c'est le cas, le bloc div reçoit la classe CSS "post-cat-three". -->
<!-- Sinon, le bloc div reçoit la classe CSS "post". -->
<?php if ( in_category('3') ) { ?>
<div class="post-cat-three">
<?php } else { ?>
<div class="post">
<?php } ?>
<!-- Affiche le Titre en tant que lien vers le Permalien de l'Article. -->
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
<!-- Affiche la Date. -->
<small><?php the_time('F jS, Y'); ?></small>
<!-- Affiche le corps (Content) de l'Article dans un bloc div. -->
<div class="entry">
<?php the_content(); ?>
</div>
<!-- Affiche une liste des Catégories des Articles séparée par des virgules. -->
<p class="postmetadata">Posted in <?php the_category(', '); ?></p>
</div> <!-- Fin du premier bloc div -->
<!-- Fin de La Boucle (mais notez le "else:" - voir la suite). -->
<?php endwhile; else: ?>
<!-- Le premier "if" testait l'existence d'Articles à afficher. Cette -->
<!-- partie "else" indique que faire si ce n'est pas le cas. -->
<p>Sorry, no posts matched your criteria.</p>
<!-- Fin REELLE de La Boucle. -->
<?php endif; ?>
Note : Chaque partie de code HTML doit être située en dehors des balises <?php ?>. De même, tout code PHP (même les plus petit éléments comme les accolades : } ) doit être inclus dans des balises <?php ?>. Vous pouvez ainsi entremêler un code PHP et un code HTML code, même au sein d'éléments tels que if et else, comme vous avez pu le voir dans l'exemple ci-dessus.
Pour WordPress v1.5 et versions ultérieures
Cet exemple permet d'exclure une Catégorie spécifique de l'affichage. Il est basé sur l'exemple ci-dessus.
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<!-- Si l'Article est dans la Catégorie que nous souhaitons exclure, nous passons à l'Article suivant. -->
<?php if (in_category('3')) continue; ?>
<div class="post">
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
<small><?php the_time('F jS, Y'); ?></small>
<div class="entry">
<?php the_content(); ?>
</div>
<p class="postmetadata">Posted in <?php the_category(', '); ?></p>
</div> <!-- fin du premier bloc div -->
<?php endwhile; else: ?>
<p>Sorry, no posts matched your criteria.</p>
<?php endif; ?>
Note : Si vous utilisez cet exemple pour votre page principale, vous devez utiliser un Modèle (thème) différent pour les archives de vos Catégories. Sinon, WordPress excluera tous les Articles de la Catégorie 3, y compris dans l'affichage de cette Catégorie !
Cependant, si vous souhaitez utiliser le même modèle, vous pouvez éviter cela par l'utilisation du marqueur is_home() :
...
<?php if (in_category('3') && is_home() ) continue; ?>
...
De cette manière, les Articles de la Catégorie 3 ne seront exclus de l'affichage que sur la page principale. Il existe d'autres Marqueurs conditionnels qui peuvent être utilisés pour gérer l'affichage en fonction de certaines conditions liées aux pages affichées.
A noter : bien que l'Article n'est pas affiché, il est cependant compté par WordPress comme ayant été montré, ce qui signifie que si vous avez paramétré Wordpress pour qu'il n'affiche que sept Articles et que deux des sept derniers proviennent de la Catégorie 3, alors la page principale ne contiendra que cinq Articles. Si cela pose un problème, il existe une manière plus complexe de faire qui est décrite dans la Layout and Design FAQ ou bien, vous pouvez utiliser le marqueur query_posts si vous souhaitez simplement exclure une catégorie de la boucle.
Cette section traite de l'utilisation avancée de The Loop. C'est un peu technique, mais cela ne doit pas vous effrayer. Nous allons commencer par le plus facile et développer à partir de là. Avec un peu de bon sens, de patience et d'enthousiasme, vous aussi vous pourrez utiliser des boucles multiples.
Tout d'abord, "pourquoi voudriez-vous utiliser une Boucle multiple ?" En général, la réponse est que vous souhaitez réaliser quelquechose avec le premier groupe d'Article, et quelquechose d'autre avec un autre groupe, mais afficher les deux groupes sur la même page. Quelquechose peut vouloir dire à peu près n'importe quoi; les seules limites sont vos talents en PHP et votre imagination.
Nous allons voir des exemples plus bas, mais auparavant, vous devriez vous familiariser avec les bases. Prenez une Boucle simple, elle consiste en :
<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); ?>
<!-- faire des trucs ... -->
<?php endwhile; ?>
En français, (Les pros du PHP et ceux qui sont familier de la programmation peut sauter ce paragraphe), le code ci-dessus se lirait ainsi : Si nous allons afficher de Articles, alors récupérons-les un par un. Pour chacun des Articles de la liste, affichons-le en utilisant <!-- faire des trucs ... -->. Quand ce sera fait avec le dernier Article, stop. Les lignes contenues dans faire des trucs dépendent du modèle utilisé.
Note sur Faire des trucs : dans cet exemple, c'est un emplacement du code dans lequel on pourra déterminer comment formater et afficher chaque Article sur une page. Ce code variera en fonction du thème utilisé. Si vous regardez dans le fichier index.php du thème Kubrick (livré avec Wordpress), la section Faire des trucs ira de la ligne :
<?php while (have_posts()) : the_post(); ?>
A la ligne :
<?php comments_popup_link('No Comments »', '1 Comment »', '% Comments »'); ?>
Explication pour les programmeurs :
Les marqueurs have_posts() et the_post() permettent de manipuler l'objet global $wp_query qui contient toutes les actions. $wp_query est appelé dans l'entête du blog (balises <head>) et alimente les arguments provenant de GET et PATH_INFO. $wp_query récupère les arguments et construit puis exécute une requête à la base de donnée dont le résultat est un tableau d'Articles. Ce tableau est sauvegardé dans l'objet et retourné vers l'entête où il est stocké dans le tableau global $posts (ceci afin de maintenir la compatibilité ascendante avec les anciennes versions).
Une fois que WordPress a fini de charger l'entête du blog et avance dans l'exécution du modèle, nous arrivons à notre Boucle d'Article. have_posts() charge $wp_query->have_posts() qui vérifie s'il reste des Articles dans le tableau $posts avec un simple compteur. Et the_post() appelle $wp_query->the_post() qui incrémente ce compteur et initialise la variable globale $post et les données globales de l'Article. Quand la Boucle sera finie, have_posts() renverra false et c'en sera fini.
Voici ci-après deux exemples de Boucles multiples. La clé pour l'utilisation de Boucles multiples est que $wp_query ne peut être appelé qu'une fois. Pour contourner cela, il est possible de ré-utiliser la requête en utilisant rewind_posts() ou en créant un nouvel objet. C'est ce qui est montré dans l'exemple 1. L'exemple 2 montre l'utilisation d'une variable pour stocker les résultats d'un query. L'exemple 3 explique l'utilisation de la fonction update_post_caches(); qui permet d'éviter certains problèmes habituels liés aux plugins. Enfin, ‘multiple loops in action’ donne quelques idées permettant d'utiliser les Boucles multiples afin de mettre en évidence les Articles appartenant à une Catégorie définie sur la page d'accueil de votre blog.
rewind_posts() est appelé afin de créer une Bcoule sur la même requête une seconde fois. Cela va ré-initialiser le compteur et permettre la réalisation d'une nouvelle Boucle.
<?php rewind_posts(); ?>
<?php while (have_posts()) : the_post(); ?>
<!-- Faire des trucs... -->
<?php endwhile; ?>
Si le traitement des Articles de la requête d'origine est terminé, et que vous voulez utiliser une requête différente, vous pouvez ré-utiliser l'objet $wp_query en appelant query_posts() qui lancera une nouvelle requête, construira un nouveau tableau d'Articles et ré-initialisera le compteur, vous permettant de relancer une nouvelle Boucle.
// Récupère les 10 derniers Articles dela Catégorie special_cat.
<?php query_posts('category_name=special_cat&showposts=10'); ?>
<?php while (have_posts()) : the_post(); ?>
<!-- Faire des trucs pour special_cat... -->
<?php endwhile;?>
Si vous avez besoin de conserver la requête originale, vous pouvez créer un nouvel objet.
<?php $my_query = new WP_Query('category_name=special_cat&showposts=10'); ?>
<?php while ($my_query->have_posts()) : $my_query->the_post(); ?>
<!-- Do special_cat stuff... -->
<?php endwhile; ?>
L'objet de requête my_query est utilisé ici puisqu'on ne peut utiliser have_posts() et the_post() qui utuilisent l'objet $wp_query. A la place, les éléments du nouvel objet my_query seront utilisés.
Une autre manière d'utiliser les Boucles multiples propose une réponse différente à l'impossibilité d'utiliser have_posts() et the_post(). Pour cela, vous devez stocker la requête initiale dans une variable, et la rappeler quand une nouvelle Boucle commence. De cette manière, vous pouvez utiliser toutes les fonctions standard qui s'appuient sur les variables globales.
Par exemple :
// on commence ici
<?php $temp_query = $wp_query; ?>
<!-- Faire des trucs... -->
<?php query_posts('category_name=special_cat&showposts=10'); ?>
<?php while (have_posts()) : the_post(); ?>
<!-- Faire des trucs de special_cat... -->
<?php endwhile; ?>
// retour au cheminement normal du programme
<?php $wp_query = $temp_query; ?>
Note : En PHP 5, l'opérateur "=" référence les objets au lieu de les copier comme en php4. Pour que l'exemple 2 fonctionne en php5, vous devrez utiliser le code suivant :
// on commence ici
<?php $temp_query = clone $wp_query; ?>
<!-- Faire des trucs... -->
<?php query_posts('category_name=special_cat&showposts=10'); ?>
<?php while (have_posts()) : the_post(); ?>
<!-- Faire des trucs de special_cat... -->
<?php endwhile; ?>
// retour au cheminement normal du programme
<?php $wp_query = clone $temp_query; ?>
Certains plugins ne gèrent pas correctement les boucles multiples. C'est parfois le cas de plugins qui manipulent les mots-clé et les marqueurs des Articles et qui ne fonctionnent que pour la première occurence d'une boucle dans une page où cette boucle consiste en un sous-ensemble d'Articles. Si cela vous arrive, il vous est possible d'utiliser la forme suivante de la boucle de base qui ajoute l'utilisation de la fonction update_post_caches($posts). Cette fonction ré-initialise le cache des Articles et n'est pas encore documentée. Cette implémentation ne doit être utilisée sur la seconde boucle d'une page que si la première boucle ne ramène qu'un sous-ensemble d'Articles.
Remplacer simplement :
<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); ?>
<!-- Faire des trucs... -->
<?php endwhile; ?>
Par :
<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); update_post_caches($posts); ?>
<!-- Faire des trucs... -->
<?php endwhile; ?>
La meilleure façon de comprendre le fonctionnement des boucles multiples est d'en montrer un exemple réel. L'utilisation probablement la plus courante de boucles multiples est l'affichage sur une page de deux ou plus listes d'Articles. Cela est souvent le cas quand un webmestre veut mettre en avant les derniers Articles rédigés et les Articles d'une Catégorie spécifique.
En laissant de côté tous les problèmes de formattage et de CSS, nous partirons donc de l'hypothèse que nous souhaitons afficher deux listes d'Articles. La première contiendra les Articles les plus récents (les 10 derniers Articles rédigés), et la seconde contiendra un Article de la Catégories 'featured'. L'Article de la Catégorie ‘featured’ doit apparaître en premier suivi de la seconde liste d'Articles (la liste 'standard'). Le truc est qu'aucun Article ne doit apparaître dans les deux listes à la fois.
Step 1. Récupérer un seul Article de la Catégorie ‘featured’.
<?php $my_query = new WP_Query('category_name=featured&showposts=1');
while ($my_query->have_posts()) : $my_query->the_post();
$do_not_duplicate = $post->ID; ?>
<!-- Faire des trucs... -->
<?php endwhile; ?>
En français, le code ci-dessus se lirait ainsi :
Charger dans $my_query le résultat de la requête ramenant tous les Articles de la Catégorie appelée 'featured' et d'ailleurs, ne ramener qu'un Article. Puis, mettre dans la variable $do_not_duplicate le numéro d'ID de l'Article ramené. Rappelez-vous que les lignes Faire des trucs contiennent toutes les options d'affichage associées à l'Article ramené.
Notez que nous aurons besoin de la valeur de $do_not_duplicate dans les étapes suivantes pour nous assurer que cet Article n'apparaîtra pas dans la seconde liste.
Step 2. La seconde Boucle, qui ramène les X derniers Articles (sauf un).
Le code suivant ramène les X derniers Articles (comme défini dans les Options WordPress), sépare celui déjà affiché dans la première boucle et affiche les autres en utilisant les lignes Faire des trucs.
<?php if (have_posts()) : while (have_posts()) : the_post(); if( $post->ID == $do_not_duplicate ) continue; update_post_caches($posts); ?> <!-- Faire des trucs... --> <?php endwhile; endif; ?>
En français, le code ci-dessus se lirait ainsi :
Ramèner tous les Articles, si on tombe sur un Article égal à $do_not_duplicate, ne rien faire (continue), sinon, afficher tous les autres Articles en utilisant Faire des trucs. En même temps, mettre à jour le cache pour que les marqueurs et les mots-clé fonctionnent correctement avec les plugins. Rappelez-vous, la variable $do_not_duplicate contient l'ID de l'Article déjà affiché.
Le Résultat Final
Voici quelle sera l'allure fianle de notre morceau de code, toujours sans aucun élément de mise en page :
<?php $my_query = new WP_Query('category_name=featured&showposts=1');
while ($my_query->have_posts()) : $my_query->the_post();
$do_not_duplicate = $post->ID;?>
<!-- Faire des trucs... -->
<?php endwhile; ?>
<!-- Faire d'autres trucs... -->
<?php if (have_posts()) : while (have_posts()) : the_post();
if( $post->ID == $do_not_duplicate ) continue; update_post_caches($posts); ?>
<!-- Faire des trucs... -->
<?php endwhile; endif; ?>
En final, on obtiendra une page avec deux listes. La première liste ne contiendra qu'un Article -- le dernier de la Catégorie 'featured'. La seconde contiendra les X derniers Articles (comme défini dans les Options WordPress) à l'exception de l'Article déjà affiché dans la première liste. Ainsi, dès qu'un nouvel Article 'featured' est publié, il prendra la place dans la première liste, et celui qui y apparaissait apparaîtra dans la seconde liste (enfin, cela dépend évidemment du nombre d'article que vous affichez et s'il fait toujours partie des X derniers publiés). Cette technique (ou une technique similaire) est souvent utilisée en conjonction avec des éléments de Hiérarchie de Modèles (en anglais) qui permettent de créer des mises en pages différentes pour home.php et index.php. Voir les ressources supplémentaires au bas de cette page.
Pour en apprendre plus sur la Boucle WordPress, et les différents marqueurs de modèle qui ne fonctionne que dans la Boucle, voici des ressources supplémentaires (en anglais).