WordPress et Ajax : les bases

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 :

Les « Load more » par exemple utilisent Ajax pour charger automatiquement les articles suivants lorsque l’internaute arrive en bas de page.

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 la 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 commentaires, 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 ;
• Faire 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.

Préparer notre thème pour Ajax

Une requête Ajax, 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 » :

Rendre accessible ajaxurl en JS

Afin de lancer notre requête Ajax, il va falloir indiquer l’URL de WordPress dédiée à l’écoute de nos requêtes. Il y a en effet une URL spéciale qui se charge de réceptionner et traiter les requêtes, c’est la page admin-ajax.php.

Pour obtenir cette URL, on utilise admin_url('admin-ajax.php'). On a ensuite besoin de la transmettre à Javascript, et pour cela on va utiliser la fonction wp_localize_script().

Celle-ci va écrire une variable juste avant le chargement d’un script, afin que celui-ci puisse en bénéficier. Le premier paramètre sert justement à indiquer quel script aura besoin de cette variable. J’ai indiqué le même nom que dans wp_enqueue_script(), à savoir capitaine.

Affichez n’importe quelle page de votre site, et consultez son code source. Vous devriez voir ajaxurl déclarée juste avant votre script.

Lancer une requête Ajax côté Javascript

On va maintenant écrire notre première requête, grâce à la fonction $.ajax de jQuery. Notez qu’on aurait pu tout aussi bien utiliser du JS natif.

Dans ce premier exemple on va dire que les commentaires ne sont pas affichés automatiquement, et qu’il faudra cliquer sur un bouton pour les faire apparaitre :

Voici à quoi ressemble le HTML :

Et voici le code à insérer dans notre JS :

La requête est découpée en 2 parties : la requête sortante, puis le code à exécuter une fois qu’elle est terminée. La fonction done() attendra donc les résultats, quelle fournira via l’argument response.

La requête attend plusieurs paramètres : l’url est définie par notre ajaxurl. On indique également que l’on veut une requête de type POST afin d’envoyer des informations, qui seront stockées dans data.

Afin que la requête fonctionne avec WordPress, il faut indiquer au minimum l’action. C’est elle qui va nous permettre de savoir quelle fonction lancer côté PHP. Son nom est complètement arbitraire, à vous de le définir afin qu’il soit éloquent.

On envoie également l’identifiant de l’article en cours, que l’on a préalablement affiché dans le HTML dans les attributs du bloc comments. Sinon WordPress ne saura pas de quel article on fait référence.

Réceptionner et traiter la requête Ajax en PHP

Il nous faut maintenant écrire la fonction PHP qui va récupérer cette requête, et la traiter. Et pour cela on va passer par un hook dédié à cet effet.

Et on va écrire ce code dans functions.php.

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_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 : écrire, lire des données et utiliser toutes les fonctions disponibles dans le coeur de WordPress, car même dans une requête Ajax, celui-ci est complètement initialisé.

Dans cet exemple on récupère d’abord l’id de l’article, puis on utilise les fonctions get_comments et wp_list_comments qui nous permettent d’afficher les commentaires 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 !

C’est donc 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.

Toujours finir avec un wp_die()

Et enfin, pour terminer chaque requête Ajax, il est bon de déclencher sans plus attendre la fin de l’exécution du PHP une fois qu’on a renvoyé les données souhaitées. Et pour cela on utilise la fonction wp_die() de WordPress (qui renvoie un die PHP mais avec un hook en plus).

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.

Tester la requête

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 XHR dans le jargon.

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

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

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

En cas de souci : débugguer la requête

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 echo en PHP pour vérifier que tout va bien. Par exemple :

Le but étant de définir à quel point il y a un souci. Faites pareil pour PHP :

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.

Si 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.

Et voilà, vous savez désormais utiliser Ajax dans votre thème WordPress. Dans les prochains cours (premium) 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.