Créer une requête Ajax avec WordPress

C’est quoi l’Ajax ?

Pour faire simple, Ajax nous permet d’aller chercher des informations sur le serveur sans pour autant recharger toute la page. Voici une définition plus complète :

Par exemple, les « Load more » que l’on retrouve en bas de page utilisent Ajax pour charger automatiquement les articles suivants lorsque l’internaute arrive à la fin de la liste.

Dans ce cours, on va charger de manière asynchrone les commentaires d’un article, afin de ne pas trop alourdir le chargement initial de la page. Voici un schéma pour bien comprendre ce qu’il se passe lors d’une requête.

Tout commence par un internaute qui demande à afficher une page. Le serveur l’envoie, et le navigateur l’interprète. Jusque là, on est sur un fonctionnement classique.

Ensuite, l’internaute clique sur le bouton “Charger les commentaires”. Javascript va alors lancer une requête Ajax au serveur.

Le serveur va exécuter une fonction spécialement destinée à traiter cette requête, et va récupérer les données, générer le HTML correspondant pour le renvoyer enfin au client.

Côté client, Javascript récupère ce contenu, et va l’injecter dans la page. Les commentaires apparaissent à l’écran.

Et voilà ! On a ainsi évité de nombreuses requêtes et allégé la charge du serveur. On va maintenant voir comment le faire concrètement.

Quelles possibilités avec Ajax dans WordPress ?

Grâce à WordPress, la manière de gérer une requête Ajax est plutôt simple, et nous permettra de nombreuses utilisations comme par exemple :

• Afficher les commentaires lors d’un clic ;
• Afficher la définition d’un mot lorsqu’on le survole ;
• Lancer une recherche dynamique ;
• Afficher les prochains articles en bas de page (load more) ;
• …

Dans la formation développeur d’extensions, on verra même comment utiliser Ajax dans l’interface d’administration pour enregistrer nos paramètres en temps réel.

Dans ce cours on va se concentrer sur l’affichage des commentaires. Mais une fois que vous aurez compris le principe d’Ajax, vous pourrez utiliser la même logique pour faire tout ce que vous voulez !

#1 • HTML : Préparer le formulaire pour Ajax

On va commencer par préparer le markup de notre page. On va devoir envoyer des informations via Javascript à notre serveur, comme notamment l’identifiant de l’article dans lequel on veut récupérer les commentaires.

Et pour cela, on va utiliser un formulaire classique. La différence, c’est que le formulaire ne s’enverra pas, afin d’éviter le rechargement de la page : c’est JS qui va s’en occuper, en Ajax.

Dans l’action de la balise <form>, on va indiquer l’URL qui réceptionne les requêtes Ajax dans WordPress. Et elle est disponible via la fonction admin_url().

Ne vous inquiétez pas : même si c’est une adresse de l’administration WordPress, elle est tout de même joignable par un utilisateur du site, en toute sécurité.

Ensuite on a besoin de passer plusieurs informations :

• postid : L’identifiant de l’article pour lequel on veut récupérer les commentaires. Celui qu’on consulte en somme ;
• nonce : c’est un jeton de sécurité, pour s’assurer que la requête provient bien de ce site, et pas d’un autre. On évite ainsi les attaques XSS. On en reparle à la fin du cours, dans la section dédiée à la sécurité ;
• action : cela permet d’indiquer à WordPress quelle fonction on va lancer en PHP, grâce à un système de hook qu’on va étudier juste après.

Enfin, la liste avec la classe comments réceptionnera le HTML généré par le serveur, afin d’afficher nos commentaires.

Alternative

Si vous préférez, vous pouvez passer toutes les données grâce aux attributs data- HTML 5, et utiliser un simple bouton au lieu d’un formulaire :

Au final on se retrouve avec un HTML beaucoup plus léger. À vous de voir !

#2 • Javascript : Préparer la requête Ajax

Une requête Ajax, comme on l’a vu, c’est du JS qui communique avec du PHP. Pour permettre cela, on va préparer le terrain :

Créer le fichier JS

Tout d’abord, il va nous falloir un fichier Javascript que je vais créer dans js/script.js.

Ce que je fais dedans, c’est de l’encapsulation, ça permet d’isoler notre code afin d’éviter les conflits avec les autres scripts, et d’utiliser le $ de jQuery. C’est une bonne pratique que je vous conseille d’appliquer à tous vos fichier JS.

Charger le script

On va ensuite charger notre script, comme on l’a appris dans le cours « charger les scripts et styles ». Et ça va se passer dans le fichier functions.php de notre thème :

D’ailleurs si vous souhaitez charger votre script uniquement dans les pages single du blog, vous pourriez ajouter un conditional tag :

Ça va dépendre de si vous faites un script pour tout votre site, ce qui est judicieux lorsqu’il y a peu de JS, ou si vous préférez faire un script par fonctionnalité.

Référez-vous au cours sur le Template Hierarchy si vous n’êtes pas à l’aise avec les différents modèles de pages utilisés par WordPress.

On va maintenant écrire notre première requête, grâce à la fonction fetch de Javascript, qui permet de lancer des requêtes Ajax en toute simplicité.

Dans ce premier exemple on va dire que les commentaires ne sont pas affichés automatiquement au chargement de la page. À la place, un bouton bleu permettra au clic de les charger dynamiquement :

Et voici le code à insérer dans notre JS. Il parait un peu long, mais ne vous inquiétez pas, tout va vous paraitre très vite très clair :

Tout d’abord, on pose un événement sur la soumission du formulaire avec submit. On enchaine directement avec un e.preventDefault() pour empêcher l’envoi de la requête, sinon la page va se recharger. Après tout c’est le fonctionnement par défaut d’un formulaire.

Ensuite, on récupère l’URL de WordPress qui permet de traiter les requêtes Ajax. On a placé cette information dans l’attribut action de la balise <form> en html.

Puis on va récupérer toutes les données qu’on va devoir envoyer au serveur, à savoir l’action (obligatoire), le nonce (pour la sécurité) et, dans notre exemple, l’identifiant de l’article en cours.

Pour cela on va lire la valeur des champs qui se trouvent dans notre formulaire, référencé par this, via les méthodes find et val.

Avant d’aller plus loin, essayez un console.log() pour vérifier que vous récupérez bien les données !

Alternative : si vous avez utilisé les data- attributes

Du coup si vous avez opté pour le simple bouton à la place du formulaire, il y aura quelques changements à faire dans le script. Tout d’abord ce ne sera plus l’événement submit, mais click cette fois !

Et pour récupérer les données en data, plutôt qu’en champs, il faudra utiliser la fonction .data(). Dans cet exemple, this fait désormais référence au bouton :

Vérifiez que vous récupérez bien les données à l’aide d’un petit console.log().

La requête Ajax avec fetch

Et enfin, c’est le moment de lancer notre requête Ajax, via la méthode fetch de Javacript. Cette méthode est compatible avec tous les navigateurs depuis 2017. Vous pouvez donc l’utiliser sans souci.

Le premier paramètre, c’est l’URL à joindre, celle qu’on a récupéré dans l’action du formulaire.

Ensuite, il y a un objet contenant :

• La méthode qui sera toujours POST (car on envoie des informations au serveur) ;
• Les en-têtes sont également toujours les mêmes ;
• Et le corps qui contient les données à envoyer, qu’on passe dans la fonction URLSearchParams pour les mettre en forme correctement dans la requête.

La suite, dans then, sera lancé uniquement quand le serveur aura répondu : on entre bien dans un fonctionnement asynchrone. Pendant ce temps là, le reste du code JS peut continuer de tourner sans problème, et sans blocage.

Pour le moment, on va passer du côté serveur, et donc sur du PHP, pour réceptionner et traiter la requête.

#3 . PHP : Réceptionner et traiter la requête Ajax en PHP

C’est dans functions.php que va se dérouler la suite lorsqu’on code un thème. Pour traiter la requête, on va passer par un hook dédié à cet effet.

Le hook en question commence par wp_ajax_ et se termine par le nom de l’action arbitraire que vous avez définie en JS. Pour moi c’est donc wp_ajax_capitaine_load_comments.

Par défaut, les requêtes Ajax sont dédiées seulement aux utilisateurs connectés. Pour les rendre accessibles à tous les utilisateurs, il faudra ajouter le second hook wp_ajax_nopriv.

Les deux appellent la même fonction : capitaine_load_comments().

A partir de là, vous allez pouvoir faire ce que vous voulez : récupérer des articles, des utilisateurs, des commentaires, enregistrer de nouvelles données… Dans tous les cas, le coeur de WordPress est complètement chargé, donc vous avez accès à tout le CMS.

Vérifications des données

On commence tout d’abord par vérifier l’existence du jeton de sécurité, le fameux nonce de WordPress, et on va ensuite contrôler que les données obligatoires ont bien été envoyées, dans notre cas, l’identifiant de l’article :

Au moindre souci, on utilise wp_send_json_error qui va interrompre le script, et renvoyer un message d’erreur. Le second paramètre permet de définir le code d’erreur HTTP 403, qui veut dire : Accès interdit (Forbidden).

Ensuite, on récupère les données et on les traite : on part du principe qu’on ne peut pas faire confiance aux données, il font donc les nettoyer.

Pour les textes, utilisez simplement la fonction sanitize_text_field() de WordPress. Elle s’occupe de tout et vous évitera toute injection SQL ou autre fourberie.

Et pour les nombres, un simple intval() classique de PHP suffira.

Ensuite, on va vérifier que l’article est bien publié, et en visibilité publique. Comme l’identifiant de l’article est présent dans le formulaire, il faut partir du principe que l’internaute peut modifier cette valeur, et tenter au hasard de récupérer les commentaires d’autres articles, dont certains pourraient être privés. On en reparle à la fin du cours, dans la partie sécurité.

Récupérer les commentaires

Une fois qu’on a l’identifiant de l’article, on utilise :

• D’abord get_comments afin de récupérer les commentaires bruts ;
• Et ensuite wp_list_comments qui les met en page en HTML ;

Mais j’aurai pu tout aussi bien lancer une WP Query et récupérer un template via get_template_part() par exemple !

Et enfin, on renvoie le tout à JS sous forme d’une chaine HTML, qui sera injecté dans la page :

Dans ce cas précis, c’est du HTML qui sera renvoyé à notre page. Mais on aurait pu tout aussi bien renvoyer des données brutes sous forme de JSON. On le verra d’ailleurs dans les prochains cours.

Astuce : organiser le functions.php en plusieurs sous-fichiers

Si le fichier functions.php commence à devenir trop gros, n’hésitez pas à le scinder en utilisant des includes(). J’ai pour habitude de séparer mon fichier en plusieurs plus petits, et mes requêtes Ajax finissent en général dans includes/ajax.php.

#4 : JS • Réceptionner les données

Afin que tout fonctionne, j’aime bien tester les différents éléments au fur et à mesure que je construits ma requête. Et pour cela on va utiliser la console du navigateur, et plus particulièrement l’onglet Network :

Vous verrez passez les requêtes sous le nom de admin-ajax.php. D’ailleurs vous pouvez filtrer les requêtes pour ne voir passer que les requêtes Ajax, ou fetch/XHR dans le jargon.

Si tout se passe bien vous devriez voir le résultat s’afficher, ici du HTML (brut).

Afficher les données dans la page

Lorsque la requête est terminée et les données retournées, le .then() de notre fetch se lance. L’argument response contient le contenu envoyé par PHP.

D’ailleurs voici ce que nous renvoie PHP :

On reçoit à chaque fois 2 éléments :

• Une propriété success sous forme de booléen true/false ;
• Une propriété data, qui contient ce que vous avez passé en paramètre : du html ou des données brutes, au choix.

On décide alors de l’injecter dans le bloc .comments, et on en profite également pour cacher le formulaire et son bouton, qui nous a permis d’afficher ces commentaires. Et le tour est joué !

Bug • Comment trouver le problème ?

Si ça ne marche pas, il va falloir vérifier plusieurs choses, côté JS mais aussi en PHP. À chaque étape, utilisez un console.log() en JS et un var_dump() en PHP pour vérifier que tout va bien. Le but étant de trouver à quel moment précis il y a un problème. Par exemple :

Les console.log() devraient apparaitre dans la console du navigateur, sous l’onglet Console.

Et s’il y a la moindre erreur, elle apparaitra en rouge. De cette manière, vous allez pouvoir facilement débugguer vos requêtes et comprendre d’où vient le souci.

Faites-en de même pour PHP :

Par contre, les var_dump() de PHP vont apparaitre dans l’onglet network de l’inspecteur. Sélectionnez d’abord la requête Ajax correspondante dans la liste, et cliquez sur Preview pour observer le résultat.

Et si par malheur vous faites une erreur de PHP, vous ne la verrez pas apparaitre dans l’onglet Network. Pour voir l’erreur, il faudra activer le log d’erreurs PHP afin de le consulter, et trouver l’erreur.

Si vous avez une erreur 400 « bad request »

Si vous voyez une erreur 400 dans la console du navigateur, dans l’onglet Réseau, c’est que la requête Ajax n’a pas fonctionné.

Et pour cause, WordPress n’a pas trouvé l’action correspondante côté PHP : le nom de l’action donné en JS ne correspond pas au hook PHP de functions.php.

Vérifiez alors :

• Que vous avez bien une donnée action dans votre JS ;
• Que le nom de l’action en PHP est exactement le même que le hook WordPress, sans wp_ajax_ devant ;
• Que le fichier contenant votre hook PHP est bien appelé (s’il n’est pas directement dans functions.php).

Sécurité : des requêtes vraiment robustes !

Pour terminer, je vous propose de passer en revue les quelques éléments essentiels que l’on a utilisé afin de sécuriser vos requêtes Ajax.

Sécuriser sa requête Ajax avec un jeton Nonce

Tout d’abord, et afin d’éviter les attaques XSS (Cross Script Scripting), vous devez impérativement ajouter un Nonce, un code généré par WordPress qui permet de certifier que l’action a été envoyée par le serveur, et pas un autre.

Pour cela il faut tout d’abord générer le nonce avec la page, et lui donner un nom. Celui-ci peut-être le même que l’action, pour plus de simplicité :

Vous pouvez d’ailleurs utiliser la fonction wp_nonce_field() qui génère le champ pour vous. Le premier paramètre est le nom de l’action, et le second le nom du champ.

Côté traitement de la requête, il faut en premier lieu vérifier ce Nonce :

Et si vous faites un plugin

Si vous être en train de coder une extension, vous allez devoir utiliser la fonction check_admin_referer() qui permet de s’assurer que l’action provient bien d’une page de l’administration de WordPress, et pas en dehors. Elle remplacera alors wp_verify_nonce().

On en reparlera dans la formation sur les extensions. Vous pouvez consulter la documentation de cette fonction ici.

Les requêtes privées

Par défaut, le hook que vous déclarez pour traiter les requête Ajax ne fonctionnera que pour les utilisateurs connectés.

Si vous souhaitez aussi donner la possibilité à n’importe quel visiteur de lancer une requête, comme par exemple charger les commentaires, ou les articles suivants, alors il faudra déclarer un second hook avec no_priv :

Dans ce cas, il vous incombe de vérifier que la fonction de callback ma_fonction ne permet pas de faire des actions sensibles, comme la suppression d’un article ou la création d’un utilisateur.

Dans la fonction d’ailleurs, n’hésitez pas à utiliser les fonctions de vérification de rôle si besoin, comme :

Traitement des données : Trust no one !

À partir du moment où les données viennent du front, il faut considérer qu’elles ne sont pas fiables. Vous devez alors impérativement les nettoyer afin d’éviter toute injection SQL ou toute autre filouterie :

Profitez-en pour tester l’existence de la donnée en amont, afin d’éviter des erreurs PHP :

Et si vous avez besoin de tester une adresse e-mail, WordPress possède une fonction pour ça :

Utiliser les fonctions de WordPress pour terminer la requête

Votre requête Ajax doit impérativement se terminer par wp_send_json_success ou wp_send_json_error côté PHP.

Ces fonctions vont permettre de renvoyer des données en JSON, et de terminer proprement l’exécution du script PHP, un peu comme un die.

Pensez à tous les cas de figure.

Et là, ce n’est pas évident. Comme l’identifiant de l’article est indiqué dans le formulaire, rien empêche à l’internaute de modifier cette valeur, et tenter de récupérer des commentaires d’un autre article.

À priori pas de souci me direz-vous. Mais imaginez qu’il existe sur le blog des articles privés, ou des articles repassés en brouillon. Il ne faut pas que l’internaute puisse accéder à ces commentaires.

Il faut donc vérifier que l’article est publié, et public.

Cet exemple est très simpliste, mais si gérez des articles protégés par mot de passe, il faudra des vérifications supplémentaires.

Et enfin, ne réinventez pas la roue !

Utilisez tout le temps les méthodes officielles de WordPress. De cette manière, vous aurez la meilleure sécurité possible. Ne tentez pas de créer votre propre route Ajax, ou de traiter la requête hors d’un hook. Ce serait vraiment dommage !

---

Et voilà, vous savez désormais utiliser Ajax dans votre thème ou extension WordPress.

Il y avait pas mal de concepts à prendre en compte dans ce premier cours, dont notamment la sécurité, ainsi que des préparatif à faire en HTML, en JS et en PHP.

Mais maintenant que vous avez la technique, vous allez pouvoir l’utiliser pour toutes vos requêtes : après tout la recette reste la même.

Dans les prochains cours on va voir comment créer un « load more », faire une recherche en direct et bien d’autres encore, afin de devenir incollable avec Ajax.