Formation « Développer un thème WordPress sur mesure »

La boucle WordPress et les templates tags

Lecture : 9 minutes • Pratique : 15 minutes • 2

C’est grâce au mécanisme appelé Boucle WordPress (en anglais The Loop) que l’on peut afficher dans nos templates les données administrées dans le CMS. Voyons comment les utiliser.

Qu’est-ce que la boucle WordPress ?

Lorsque l’on développe un thème WordPress, impossible de passer à côté de la boucle WordPress. Voyons à quoi ce concept correspond :

Cours dédié

Boucle WordPress

Définition

La boucle WordPress est le mécanisme matérialisé par un petit bout de code PHP qui permet d’afficher les données entrées via l’interface d’administration. Elle permet de préparer les données (titre, contenu, catégories, lien, image à la Une…) et de les appeler via des fonctions dédiées au nom explicite, comme the_content().

Traduction : The Loop

Cette boucle a la particularité d’être exactement la même sur tous les templates de page que l’on va créer. Il suffira alors de la copier/coller dans tous nos modèles.

Maintenant que l’on a vu le template hierarchy, on va commencer par aller modifier le fichier front-page.php qui s’affichera lorsqu’on demande la page d’accueil :

PHP
front-page.php et page.php

Copiez exactement le même code pour page.php. À l’avenir notre page d’accueil sera différente des pages « standards » mais pour le moment ça nous suffira.

Lorsque l’on affiche le site dans le navigateur, on a bien le contenu de notre page d’accueil qui s’affiche :

La page d'accueil du site
Notre page d’accueil, en core un peu succinte !

Cool ! Pour mes captures, j’ai triché en ajoutant un peu de CSS, donc ne vous étonnez pas que ça rende moins bien chez vous. On abordera le CSS dans WordPress dans quelques cours.

Bon, là, vous êtes en train de vous dire que pour faire des grosses mises en page, WordPress sera vite limité. En effet. Pour aller plus loin il faudra utiliser un Page builder comme Elementor ou ajouter des champs personnalisés avec ACF. Et c’est ce que l’on verra plus tard, alors patience !

Pour le moment, revenons-en à ma boucle. On va l’étudier un peu plus en détails :

PHP

La première fonction, have_posts() contrôle qu’il y a bien quelque chose à afficher, quel que soit le cas de figure (afficher le contenu d’une page, un article, une liste d’articles…).

Vient ensuite une boucle PHP while. Vous allez me dire : à quoi bon ? Puisqu’il n’y a qu’un seul contenu à afficher : la page ? Eh bien comme je disais plus haut, ce code a été conçu pour être valide dans toutes les situations. Il marchera donc que ce soit pour afficher un seul contenu (un article ou une page) ou le blog (liste des articles).

La fonction qui suit, the_post() permet de préparer les données de l’article à afficher afin de les afficher à l’intérieur de la boucle, via les template tags.

Que sont les templates tags ?

Cours dédié

Template Tags

Définition

Les Templates Tags sont des fonctions incluses dans WordPress permettant d’afficher dans votre thème les contenus que vous avez administré dans l’interface d’édition. Ces fonctions sont à destination des développeurs de thèmes afin de rendre leurs pages dynamiques. Il en existe des dizaines, certaines permettant d’afficher le contenu de l’article comme the_title() et the_content(), d’autres sont là pour afficher les commentaires, l’auteur… ou même encore certaines qui permettent de récupérer des informations générales du site comme bloginfo().

Traduction : marqueurs de modèle

Ils en existe de plusieurs sortes mais on va se concentrer pour le moment sur ceux permettant d’afficher les données de notre article. Dans le code vu plus haut, on en a utilisé deux :

PHP

La fonction the_title() permet d’afficher le titre et the_content() va afficher le contenu de la page, c’est-à-dire ce que l’on a écrit avec l’éditeur visuel.

Ce sont les deux template tags les plus utilisé ! Il en existe d’autres que l’on va voir avec les pages du blog, mais pour les pages, on n’a pas besoin de grand chose de plus.

Attention

Les template tags doivent impérativement être utilisés à l’intérieur de la boucle WordPress afin de fonctionner de manière optimale.

La boucle dans le cas du blog

On va maintenant aller voir ce que donne la boucle dans le cas du blog ! Et ici, on va pouvoir utiliser d’autres templates tags. Pour cela on va ajouter quelques lignes de PHP dans nos templates :

La liste des derniers articles (archive et home)

On commence avec la page d’archives, qui liste par défaut les 10 derniers articles publiés sur le blog :

PHP
archive.php et home.php

D’après le template hierarchy, la page d’accueil du blog a un modèle différent, via home.php, au cas où vous voudriez que la page principale du blog soit différente des autres archives (affichage par auteur ou catégorie par exemple). En fait c’est rarement le cas. Du coup pour le moment on va copier le même code dans archive.php, ainsi que dans home.php. Un peu plus tard, on viendra corriger cette répétition de code.

Comme on n’a pas (encore) de menu sur notre site pour accéder au blog, on va passer par l’admin WordPress : Pages > Toutes les pages, puis survoler notre page Blog et cliquer sur Afficher. Si votre page s’appelle blog, ajoutez simplement /blog/ à la fin de l’adresse de votre site. On tombe sur la liste des articles :

La page archive affiche les derniers articles du blog, en ordre chronologique.
La page d’accueil du blog, avec un peu de CSS personnalisé

Notez que cette fois, on met des <h2> pour les titres d’article, et le titre principal de la page est « Le blog Capitaine WP ». Pour rappel il ne devrait toujours n’y avoir qu’un seul <h1> par page.

Voyons maintenant les nouveaux templates tags ajoutés :

L’image mise en avant

La fonction the_post_thumbnail() permet d’afficher l’image mise en avant (anciennement image à la Une).

Pour rappel on avait activé cette fonctionnalité grâce à la fonction add_theme_support('post-thumbnails') dans le fichier functions.php, dans le cours « Créer la base de son thème« .

L’image mise en avant se configure dans la barre d’outils latérale :

Cette fonction ne renvoie pas que l’URL de l’image, mais carrément toute la balise <img>: Cela permet de ne pas afficher une balise vide si aucune image n’a été définie.

La date

Pour afficher la date, on dispose de 2 fonctions : the_date(), et the_time(). Dans cette dernière on doit indiquer le format d’affichage via les paramètres de Date PHP classiques. D’ailleurs je récupère, grâce à la fonction get_option(), la valeur indiquée dans Réglages > général > Format de date.

Mais pas besoin de tout cela sur la première fonction. Alors pourquoi diantre ne pas utiliser the_date() tout simplement ?

PHP

En fait cette fonction n’affiche qu’une seule fois la même date : si plusieurs articles sont publiés le même jour, seul le premier affichera la date. En réalité on s’en sert pour un classement chronologique ou on affiche d’abord une date, puis la liste des articles publiés ce jour ci.

C’est pour cela que dans notre cas précis, the_time() sera plus indiqué.

L’auteur

La fonction the_author() permet d’afficher le nom de l’auteur, tel qu’il l’a défini dans Utilisateurs > Votre profil > Nom à afficher publiquement. Par mesure de sécurité, évitez d’afficher votre identifiant de connexion.

Le nombre de commentaires

Et pour finir il existe également des template tags dédiés aux commentaires comme comments_number() qui affiche le nombre de commentaires publiés dans cet article.

Par défaut il va afficher : Pas de commentaire, 1 commentaire ou X commentaires. Mais vous allez pouvoir personnaliser cet affichage. Si on s’en réfère à la documentation, on voit qu’on peut ajouter 3 paramètres : un pour chaque cas.

PHP

Dans le cas du site Capitaine WP, j’ai opté pour n’afficher que le nombre de commentaires, suivi d’une icône « bulle ». Le signe % est un caractère magique qui sera remplacé par le nombre réel de commentaires, lorsqu’il y en a au moins deux (pluriel).

L’extrait

Cette fois on utilise la fonction the_excerpt() à la place de the_content() afin de n’afficher qu’un extrait de l’article, et pas l’article en entier. Le but reste que la personne clique sur l’article de son choix pour l’afficher.

L’extrait fonctionne en trois temps. Il va d’abord regarder si l’auteur a renseigné le champ extrait dans la barre latérale à droite :

Le champ permettant de renseigner l'extrait de l'article
C’est dans la barre latérale, à droite, que vous pouvez saisir l’extrait

Si le champ est vide, il va cette fois regarder dans l’article si le bloc Lire la suite est présent :

l'article contient un bloc "Lire la suite" qui fera la démarcation entre l'extrait et l'article complet.
Le bloc « Lire la suite »

Et sinon il va couper automatiquement l’article après 55 mots (on pourra d’ailleurs modifier cette valeur plus tard).

Je déconseille la dernière option : en général le découpage se fait en plein milieu d’une phrase et ce n’est pas élégant.

Utilisez :

  • Le bloc Lire la suite pour faire apparaitre le début (controlé) de l’article
  • Le champ Extrait si vous voulez une description de l’article différente du contenu

Aparté: The Excerpt VS The Content

En réalité c’est légèrement plus compliqué que ça ! Vous pourriez aussi conserver the_content() : dans le cas d’une page archive il s’arrête aussi dès qu’il voit le bloc « Lire la suite ». De plus il ajoutera un lien (lire la suite) mais qui est plus difficile à personnaliser en CSS.

Par contre il ignore complètement le champ « Extrait » et affiche l’article en entier si le bloc « Lire la suite » n’est pas présent.

En définitive je préconise l’utilisation de the_excerpt() en priorité sur les pages archive.

À éviter

Ne mettez pas de balise <p> autour du contenu ou de l’extrait car ils en auront surement déjà et il est impossible d’imbriquer plusieurs paragraphes ensemble en HTML. Vous pouvez par contre les entourer d’une <div>.

Le Permalien

La fonction the_permalink() permet d’afficher le lien vers l’article. il faut placer cette fonction dans l’attribut href de la balise <a>. On appelle ces liens des permaliens et ils sont générés automatiquement par WordPress.

Vous pouvez configurer la structure des permaliens dans Réglages > Permaliens.

Dans cet exemple je n’ai mis le lien que sur le texte « Lire la suite », mais j’aurais pu également l’appliquer sur le titre ainsi que sur l’image mise en avant, de la même manière.

Conseil

Pour de belles URLs et un meilleur référencement optez pour la configuration « Titre de publication » /%postname%/ qui est normalement le réglage par défaut.

Afficher un article (single)

Passons maintenant aux articles. En cliquant sur un lien dans la page du blog, c’est la page single.php qui est appelée. Voici le code PHP que j’ai choisi d’y mettre :

PHP
single.php

Copiez-le dans single.php et affichez un article sur votre blog :

Le modèle single.php affiche l'article dans son intégralité.
La page single avec quelques nouvelles informations comme les catégories, étiquettes et l’avatar de l’auteur

On va passer en revue les nouveaux template tags utilisés dans cette page :

L’avatar de l’auteur

la fonction get_avatar() permet de récupérer l’avatar de l’auteur, en se servant du service Gravatar. Si vous n’en n’avez pas déjà fait un, allez le créer gratuitement sur ce site.

Le saviez-vous ?

Gravatar appartient à Automattic, la maison mère de WordPress. Ce service d’avatars décentralisé est utilisé par de nombreux services web comme Github ou Stack Overflow par exemple.

Vous allez me demander pourquoi je n’ai pas utilisé the_avatar() : tout simplement parce que cette fonction n’existe pas ! Pourquoi ? Eh bien, euh, bonne question !

Le premier paramètre attendu est l’identifiant de l’utilisateur dont on doit afficher l’avatar. Dans notre cas, c’est l’auteur. On récupère son identifiant par un autre template tag get_the_author_meta('ID').

PHP

Le second paramètre est la taille de l’image. En effet Gravatar peut la générer à la volée pour vous. J’ai défini 40 pour une image carrée de 40px de côté.

Les catégories et les étiquettes

Et enfin on utilise the_category() et the_tags() pour afficher la catégorie et les éventuelles étiquettes (anciennement mots-clés).

Cela aura pour effet d’afficher des listes <ul><li>. En cliquant sur une catégorie, vous afficherez une archive des derniers articles de cette catégorie seulement.

Notez que je n’ai pas affiché les catégories ni les étiquettes dans la page archive, mais j’aurais pu tout à fait le faire : le choix des informations que vous allez afficher ou non est complètement arbitraire en fonction des besoins de votre site. Les template tags fonctionnent dans n’importe quelle boucle.

Liste des Template Tags les plus utilisés

Pour résumer, voici la liste des templates tags que l’on va utiliser le plus régulièrement :

  • the_title() : affiche le titre de l’article ou la page ;
  • the_content() : affiche le contenu, écrit depuis l’éditeur visuel (Gutenberg ou TinyMCE) ;
  • the_post_thumbnail() : affiche l’éventuelle image mise en avant ;
  • the_excerpt() : affiche un extrait de l’article, soit le contenu du champ extrait, soit le début de l’article jusqu’à la balise Lire la suite ;
  • the_category() : affiche une liste de la ou les catégories sélectionnées ;
  • the_tags() : affiche une liste des éventuelles étiquettes de l’article ;
  • the_author() : affiche le nom de l’auteur ;
  • the_author_link() : affiche le nom de l’auteur avec un lien vers son site personnel ;
  • the_date() : affiche une fois les dates où des articles ont été publiés ;
  • the_time() : affiche la date de publication de chaque article ;
  • the_permalink() : affiche l’URL vers l’article, à mettre dans une balise <a> ;
  • comment_number() : affiche le nombre de commentaires publiés dans l’article ;
  • get_avatar() : Récupère l’avatar d’un utilisateur depuis le service Gravatar ;

Utilisez-les comme bon vous semble dans vos templates !

Pour connaitre la liste complète de tous les templates tags, référez-vous à la documentation officielle : liste des template tags.

En règle générale, allez toujours faire un tour dans la documentation développeurs afin de tout savoir de la fonction que vous souhaitez utiliser et ses éventuels paramètres (comme on a pu le voir avec le nombre de commentaires) et en découvrir de nouvelles.

Un bon développeur lit la documentation ! Comme on dit dans le métier : RTFM !

Les équivalents en « get »

Parfois, vous aurez besoin de récupérer la valeur sans directement l’afficher dans votre template, afin de la traiter en PHP. Si vous souhaitez récupérer la valeur du titre sans l’afficher par exemple, the_title() ne fonctionnera pas, il faudra alors utiliser sont équivalent get_the_title() :

PHP
exemple.php

Retenez donc que :

  • Les fonctions en the_ affichent directement la donnée dans le template ;
  • Les fonctions en get_ la récupère sans l’afficher, en vue d’un traitement.

Comme vous pouvez vous en douter, il existe un équivalent « get » à chacun des template tags.


Grâce à la boucle WordPress, aux template tags et au template hierarchy, on a ajouté pas mal de dynamisme à notre thème ! Dans les cours suivants, on va voir quelques autres concepts utiles pour gérer nos templates.

2

Questions, réponses et commentaires

  1. Cisco

    Le 1 février 2019

    C’est juste génial de pouvoir lire un article d’une telle qualité et en Français, bravo Cap’tain et vivement la suite.

    Merci pour les ressources gratuites, pressé de pouvoir accéder aux contenus premiums

    1. Maxime BJ

      Le 2 février 2019

      Merci ! Et il est tout frais de la semaine dernière celui-là !

Laisser un commentaire