WordPress et Ajax : les bases • Formation WordPress Capitaine WP

Ajax permet de lancer une requête asynchrone afin de contacter le serveur sans pour autant recharger la page, pour des pages web plus dynamiques. On va voir dans ce cours comment créer des requêtes Ajax avec WordPress en toute simplicité.

Sommaire du cours

C’est quoi l’Ajax ?
Quelles possibilités avec Ajax dans WordPress ?
Préparer notre thème pour Ajax
Lancer une requête Ajax côté Javascript
Réceptionner et traiter la requête Ajax en PHP
1. Toujours finir avec un wp_die()
2. Astuce : organiser le functions.php en plusieurs sous-fichiers
Tester la requête
En cas de souci : débugguer la requête

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 :

Ajax est le nom de la technologie permettant au navigateur de lancer une requête au serveur en temps réel pour lire ou écrire des données sans recharger la page. Ajax est également appelé XHR pour XML HTTP Request, même si on utilise en général le JSON. On parle de requêtes asynchrones car elles ne bloquent pas l’exécution du script pendant que les données transitent vers le serveur. Ajax permet un web beaucoup plus dynamique, et des économies de ressources serveur.

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.

Schéma client/serveur. Le serveur envoie une page HTML — 1. Le serveur envoie une nouvelle page à l’internaute

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

Schéma client/serveur. Le client, via JS, envoie une requête Ajax au serveur. — 2. Javascript envoie 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.

Schéma client/serveur. Le serveur renvoie juste le nouveau HTML, pas toute la page. — 3. Le serveur récupère les informations et les transmet au client

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

Schéma client/serveur. Enfin, Javascript injecte le HTML obtenu dans la page. — 4. Le client, via JS, récupère ces informations, et les injecte dans la page

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) ;
…

Astuce

Et à chaque fois, le but c’est de faire l’action SANS recharger la page.

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.

(function ($) {
  $(document).ready(function () {

    // Tout le code ira ici

  });
})(jQuery);

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 » :

<?php
function capitaine_assets() {

  // ...

  // Charger notre script
  wp_enqueue_script( 'capitaine', get_template_directory_uri() . '/js/script.js', array( 'jquery' ), '1.0', true );

  // Envoyer une variable de PHP à JS proprement
  wp_localize_script( 'capitaine', 'ajaxurl', admin_url( 'admin-ajax.php' ) );

}
add_action( 'wp_enqueue_scripts', 'capitaine_assets' );

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.

Le navigateur affiche le code source de la page afin de vérifier la présence de ajaxurl — La variable ajaxurl apparait bien, juste avant notre script

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 :

Les commentaires d'un article — Le bouton bleu va permettre de charger les commentaires

Voici à quoi ressemble le HTML :

<h2>Il y a <?php comments_number(); ?></h2>
<button class="comments-load-button">Charger les commentaires</button>
<ol class="comments" data-post-id="<?php echo get_the_ID(); ?>"></ol>

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

(function($) {
  $(document).ready(function () {

    $('.comments-load-button').click( function() {
        
        var post_id = $('.comments').attr('data-post-id');
        
        $.ajax({
          url: ajaxurl,
          type: "POST",
          data: {
            'action': 'load_comments',
            'post_id': post_id
          }
        }).done(function(response) {
          $('.comments').html(response); // Afficher le HTML
          $('.comments-load-button').hide(); // Cacher le bouton
        });
        
    });

  });
})(jQuery);

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.

<?php
add_action( 'wp_ajax_load_comments', 'capitaine_load_comments' );
add_action( 'wp_ajax_nopriv_load_comments', 'capitaine_load_comments' );

function capitaine_load_comments() {
  
  $post_id = $_POST['post_id'];
  
  $comments = get_comments(array(
    'post_id' => $post_id,
    'status' => 'approve'
  ));

  wp_list_comments(array(
    'per_page' => -1,
    'avatar_size' => 76
  ), $comments );

	wp_die();
}

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.

Attention

Il faut donc comprendre ici que le nom du hook n’est pas fixe : une partie de son nom change en fonction des cas. C’est assez courant dans WordPress. D’autres hooks fonctionnent aussi de cette manière.

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

Conseil

Finissez toujours vos fonctions issues d’Ajax avec un wp_die().

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.

<?php
include get_template_directory() . '/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 :

La console du navigateur, dans l'onglet network, montre le résultat de la requête asynchrone. — Dans la console, on peut vérifier ce que la requête a renvoyé

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

$.ajax({
    //..
}).done(function (response) {
    $('.comments').html(response); // Afficher le HTML
    $('.comments-load-button').hide(); // Cacher le bouton
});

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 :

(function ($) {
  $(document).ready(function () {
	
    console.log('Le script JS a bien été chargé');
    $('.comments-load-button').click(function () {
      
      console.log('Le clic sur le bouton a été pris en compte');
      var post_id = $(this).attr('data-post-id');
      console.log("L'identifiant est : " + post_id);

      $.ajax({
        //...
      }).done(function (response) {
        console.log("La requête est terminée !");
      });
    });
  });
})(jQuery);

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

<?php
add_action( 'wp_ajax_load_comments', 'capitaine_load_comments' );
add_action( 'wp_ajax_nopriv_load_comments', 'capitaine_load_comments' );

function capitaine_load_comments() {
  
	echo "PHP a bien exécuté la fonction";
	wp_die();
}

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

La console affiche une phrase à chaque étape réussie. — La console affiche chacune de nos étapes réussies

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.

L'erreur PHP n'est pas affichée dans l'onglet Network de la console du navigateur — S’il y a une erreur PHP, elle n’apparaitra pas directement

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.