La boucle WordPress est un ensemble d’instructions en php permettant d’afficher articles et pages correspondant à l’adresse web (url) demandée par le visiteur du site. L’adresse web peut être saisie dans un navigateur (directement ou via un favori) ou obtenue en cliquant sur un permalien interne au site.

WordPress analyse l’adresse web conformément à la structure des permaliens et recherche dans la Base de Données l’article, les articles ou la page à  afficher

A noter : le codex WordPress fournit des informations sur la boucle, en anglais, notamment dans les articles The Loop et The Loop in Action.

Comprendre « la boucle WordPress »

La boucle est un ensemble d’instructions en php (le langage de programmation utilisé par WordPress avec Javascript) permettant d’afficher articles et pages. La boucle est insérée dans le fichier index.php du thème.

Voici la boucle dans le fichier index.php du thème twentythirteen :

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

	<?php /* The loop */ ?>
	<?php while ( have_posts() ) : the_post(); ?>
		<?php get_template_part( 'content', get_post_format() ); ?>
	<?php endwhile; ?>

	<?php twentythirteen_paging_nav(); ?>

<?php else : ?>
	<?php get_template_part( 'content', 'none' ); ?>
<?php endif; ?>

La boucle commence par un test :

if ( have_posts() )
Actions si « have_posts() » est vrai ⇒ boucle sur l’affichage des articles
else
Actions si « have_posts() » est faux ⇒ afficher une page d’erreur
endif

« have_posts() » est une fonction WordPress qui indique si au moins un article (ou une page ou un article personnalisé) correspond à l’adresse web. Des exemples de liens entre l’adresse web et les éléments à afficher sont présentés dans l’article sur les permaliens).

Voici un exemple de page qui s’affiche si aucun article ne correspond à l’adresse web :

S’il y a quelque chose à afficher, la boucle d’affichage est déclenchée :

while ( have_posts() )
Actions tant qu’il y a des articles ou une page à afficher
endwhile

La boucle s’exécute tant que have_posts () est vrai. S’il s’agit d’afficher un article ou une page, la boucle s’exécutera une seule fois. Dans le cas d’une archive (catégorie, étiquette, auteur, date), la boucle s’exécutera autant de fois qu’il y a d’articles à afficher.

Limiter le nombre d’itérations de la boucle via l’administration

Le nombre maximum d’articles affichés par une boucle peut être défini dans l’administration de WordPress (option Réglages Lecture):

Si on réaffiche les articles de la catégorie de démonstration, on peut vérifier que seuls deux articles apparaissent désormais sur la page (on remarquera en bas de page le menu de navigation permettant de demander l’affichage des articles suivants) :

Le menu de navigation est affiché par la fonction ‘twentythirteen_paging_nav();‘ spécifique au thème twentythirteen mais qui s’appuie sur des fonctions standard de WordPress; cette fonction est appelée après la fin de l’exécution de la boucle (après ‘endwhile;’).

La fonction the_post()

Cette fonction est la première à utiliser dans la boucle. Elle permet de récupérer toutes les informations sur l’article (ou la page) à afficher dans l’itération courante, tout en préparant l’itération suivante.
S’il n’y a plus rien à afficher, la fonction the_post() positionne have_post() à faux, permettant ainsi d’arrêter l’exécution de la boucle.

Pour l’illustrer, retirons l’appel de la fonction the_post() dans le fichier index.php:

<?php /* The loop */ ?>
<?php while ( have_posts() ) :  ?>
	<?php get_template_part( 'content', get_post_format() ); ?>
<?php endwhile; ?>

Voici l’affichage de la page d’accueil :

La boucle affiche le premier article uniquement et sans limite (on parle d’une boucle infinie) car elle ne passe plus à l’article suivant du fait de l’absence de la fonction the_post().

L’affichage d’un article ou d’une page dans la boucle

L’affichage est déclenché par l’instruction suivante :

<?php get_template_part( 'content', get_post_format() ); ?>

La fonction get_template_part permet d’exécuter les instructions contenues dans un fichier php à l’endroit où elle est appelée. C’est comme si on récupérait du code dans un fichier php et qu’on venait l’insérer dans la boucle.

Get_template_part a deux paramètres :

1. ‘content‘ : début du nom du fichier php à insérer,
2. get_post_format() : fonction permettant de récupérer le format associé à l’article :

Dans le répertoire contenant le thème twentythirteen, on constate qu’il existe des fichiers dont le nom commence par ‘content’ et qui se terminent par les noms des différents formats d’articles.

Par exemple, ‘get_template_part’ permet d’afficher un article dont le format est ‘video’ suivant les instructions contenues dans le fichier ‘content-video’.

Modifier la requête

WordPress analyse l’adresse web puis interroge la Base de Données afin de récupérer les articles et les pages à afficher. L’interrogation d’une Base de Données s’appelle une requête (query en anglais).

WordPress permet de modifier la requête avant d’interroger la BdD. C’est ce qui est fait dans ce site (dfarnier.fr) pour l’affichage des catégories.

A chaque catégorie correspond un ‘parcours’ (Installer, Connaître ou Administrer WordPress). Chaque parcours regroupe des articles, mais les plus anciens sont ceux qu’il faut lire en premier au contraire d’un blog qui affiche en premier les articles les plus récents :

add_action( 'pre_get_posts', 'wpdf_mod_aff_categories', 1 );

function wpdf_mod_aff_categories( $query ) {
   if ( ! is_admin() && $query->is_main_query() && is_category ()){
     $query->set( 'order', 'ASC' );                       
   }
}

On distingue deux parties dans ce code :

1. l’utilisation d’un ‘crochet‘ (hook) qui permet d’indiquer à WordPress qu’il devra exécuter une fonction lorsqu’il passera en un point précis identifié par le premier paramètre de la fonction add_action() : ‘pre_get_posts‘,
2. la fonction que WordPress doit exécuter quand il passe sur le crochet ‘pre_get_posts’, dans l’exemple : wpdf_mod_aff_categories().

Nous étudierons ultérieurement l’utilisation des crochets qui sont un élément essentiel du développement en WordPress, mais pour l’instant analysons la fonction wpdf_mod_aff_categories() qui permet de modifier la requête. Cette fonction n’est bien évidemment pas une fonction standard, mais du code ajouté par le développeur.

La fonction commence par un test :

if ( ! is_admin() && $query->is_main_query() && is_category ())

WordPress passe sur le crochet ‘pre_get_posts’ avant chaque requête préalable à un affichage, or la modification que nous souhaitons réaliser ne concerne que l’affichage des catégories d’articles. Pour ne modifier la requête que lorsque c’est nécessaire, ‘wpdf_mod_aff_categories()’ effectue trois contrôles :

• is_admin() : est-on est côté visiteur  ? (pour éviter de modifier les requêtes provenant de l’administration)
• $query->is_main_query() : est-on est dans la requête principale ? ( celle qui correspond à l’adresse web et non une requête secondaire ajoutée par exemple par une extension)
• is_category () : est-on est en train d’afficher une catégorie d’articles ? (et non une page, des articles liés à une étiquette ou à un auteur…)

Si ces contrôles sont validés, l’instruction de modification de la boucle est exécutée  :

$query->set( ‘order’, ‘ASC’ );

Dans notre exemple, l’instruction modifie l’ordre de sélection qui doit être ascendant (du plus ancien au plus récent) et non l’ordre par défaut qui est descendant (du plus récent au plus ancien).

Nous verrons ultérieurement qu’il est possible de modifier profondément la requête.

Exécuter plusieurs boucles

Il est possible d’exécuter plusieurs boucles sur une même page.

Par exemple, ceci est utilisé sur ce site (dfarnier.fr) pour l’affichage des catégories d’articles avec :

• une première boucle affichant les titres des articles de la catégorie (il peut y avoir plusieurs pages pour une même catégorie si le nombre d’articles à afficher est supérieur au nombre maximal d’articles pour une page),
• une deuxième boucle affichant les articles de la catégorie.

$wpdf_aff_liste_titres = '<ul>';
if (have_posts()) : 
	while (have_posts()) :
		the_post();
		$wpdf_aff_liste_titres .= '<li><a href="'.get_the_permalink(). '">'.get_the_title().'</a></li>';
	endwhile;
endif;
$wpdf_aff_liste_titres .= '</ul>';
rewind_posts();

Nous retrouvons la structure de la boucle standard, l’affichage des articles étant remplacé par l’affichage des titres des articles (avec un lien vers l’affichage de l’article correspondant).

L’appel à la fonction rewind_posts() après la fin de boucle permet de s’assurer que la boucle est repositionnée en début de la liste des articles à afficher.
Dans notre exemple, elle n’est pas indispensable car la fonction ‘have_posts()’ se repositionne automatiquement en début de liste quand elle a atteint la fin de boucle. Cela reste néanmoins une bonne pratique à connaître.

Trouver le code d’une fonction du noyau WordPress

En utilisant le codex

• effectuer une recherche internet, par exemple : « wordpress codex have_posts »,
• sélectionner le choix permettant d’accéder à la page du codex :

Trois remarques :

• il est possible d’accéder directement à la page du codex décrivant une fonction en saisissant l’url « https://codex.wordpress.org/Function_Reference/ » suivi du nom de la fonction,
• la description de la fonction fait apparaître la particularité qui nous intéressait, à savoir qu’en fin de boucle, la fonction ‘have_posts()’ fait appel à la fonction ‘rewind_posts()’ (voire le surligné en jaune),
• il existe de nombreux liens vers d’autres parties du codex traitant de sujets (documentation générale, description d’autres fonctions…) en relation avec la fonction décrite.

En bas de page, on trouve un lien vers le code source de la fonction (et bien d’autres choses très intéressantes pour un développeur) :

Il est souvent nécessaire d’effectuer plusieurs recherches dans le source (la fonction recherche du navigateur y suffit très souvent) pour trouver réponse à ses questions. Dans notre exemple, la fonction ‘have_posts()’ ne fait qu’appeler la méthode ‘have_posts()’ de l’objet query. C’est dans cette méthode que l’appel à la fonction ‘rewind_posts()’ est effectué.

 En utilisant la référence WordPress

• se rendre à l’adresse « https://developer.wordpress.org/reference/« ,
• rechercher la fonction :

La recherche renvoie deux résultats : la fonction et la méthode ‘have_posts()’,

La page de description de la méthode ‘have_posts()’ permet de visualiser (encadrés bleu de haut en bas de l’image ci-dessous) :

• le fichier source en accédant par méthodes et fonctions,
• le source de la méthode (éventuellement en étendant l’affichage,)
• le fichier source dans la dernière version de WordPress (‘view on trac’)