Ajax dans WordPress

Il y a deux composants principaux pour tout échange AJAX dans WordPress. Le JavaScript ou jQuery côté client et le PHP côté serveur. Tous les échanges AJAX suivent la séquence d’événements suivante.

1. Un événement de la page déclenche une fonction JavaScript ou jQuery. Cette fonction recueille des données de la page et les envoie au serveur par le biais d’une requête HTTP. Étant donné qu’il est difficile de gérer les requêtes HTTP avec JavaScript et que jQuery est de toute façon intégré à WordPress, nous allons nous concentrer uniquement sur le code jQuery à partir d’aujourd’hui. AJAX avec du JavaScript pur est possible, mais cela ne vaut pas la peine de le faire quand jQuery est disponible.
2. Le serveur reçoit la requête et fait quelque chose avec les données. Il peut assembler des données connexes et les renvoyer au navigateur du client sous la forme d’une réponse HTTP. Ce n’est pas une obligation, mais comme il est souhaitable de tenir l’utilisateur informé de ce qui se passe, il est très rare de ne pas envoyer une réponse.
3. La fonction jQuery qui a envoyé la requête AJAX initiale reçoit la réponse du serveur et en fait quelque chose. Elle peut mettre à jour un élément de la page et/ou présenter un message à l’utilisateur d’une manière ou d’une autre.

Utiliser AJAX avec jQuery

Nous allons maintenant définir la partie « faire des choses » de l’extrait de l’article sur jQuery. Nous allons utiliser la méthode $.post(), qui prend trois paramètres : l’URL à laquelle envoyer la requête POST, les données à envoyer et une fonction de rappel pour gérer la réponse du serveur. Mais avant cela, nous devons nous préparer à l’avance. Nous procédons à l’affectation suivante pour l’utiliser plus tard dans la fonction de rappel. L’objectif sera plus clair dans la section Callback.

var this2 = this;

Toutes les requêtes AJAX de WordPress doivent être envoyées à wp-admin/admin-ajax.php. L’URL correcte et complète doit provenir de PHP, jQuery ne peut pas déterminer cette valeur par lui-même, et vous ne pouvez pas coder en dur l’URL dans votre code jQuery et vous attendre à ce que quelqu’un d’autre utilise votre plugin sur son site. Si la page provient de la zone d’administration, WordPress définit l’URL correcte dans la variable JavaScript globale ajaxurl. Pour une page de la zone publique, vous devrez établir vous-même l’URL correcte et la transmettre à jQuery à l’aide de wp_localize_script() . Ce point sera abordé plus en détail dans la section PHP. Pour l’instant, sachez que l’URL qui fonctionnera à la fois pour le front et le back-end est disponible en tant que propriété d’un objet global que vous définirez dans la section PHP. Dans jQuery, elle est référencée comme suit :

my_ajax_obj.ajax_url

Données

Toutes les données qui doivent être envoyées au serveur sont incluses dans le tableau de données. Outre les données nécessaires à votre application, vous devez envoyer un paramètre d’action. Pour les requêtes susceptibles d’entraîner une modification de la base de données, vous devez envoyer un nonce afin que le serveur sache que la requête provient d’une source légitime. Notre exemple de tableau de données fourni à la méthode .post() ressemble à ceci :

{
  _ajax_nonce: my_ajax_obj.nonce, // nonce
  action: "my_tag_count", // action
  title: this.value // data
}

Chaque composant est expliqué ci-dessous.

Nonce

Nonce est un mot-valise de « Number used ONCE » (numéro utilisé une seule fois). Il s’agit essentiellement d’un numéro de série unique attribué à chaque instance d’un formulaire servi. Le nonce est établi par un script PHP et transmis à jQuery de la même manière que l’URL, en tant que propriété d’un objet global. Dans ce cas, il est référencé comme my_ajax_obj.nonce.

Le plus simple est d’associer cette valeur de nonce à _ajax_nonce. Vous pouvez utiliser une clé différente si elle est coordonnée avec le code PHP vérifiant le nonce, mais il est plus facile d’utiliser la valeur par défaut et de ne pas se soucier de la coordination. Voici comment se présente la déclaration de cette paire clé-valeur :

_ajax_nonce: my_ajax_obj.nonce

Action

Toutes les requêtes AJAX de WordPress doivent inclure un argument action dans les données. Cette valeur est une chaîne arbitraire qui est utilisée en partie pour construire une balise d’action que vous utilisez pour accrocher le code de votre gestionnaire AJAX. Il est utile que cette valeur soit une brève description de l’objectif de l’appel AJAX. Sans surprise, la clé de cette valeur est « action ». Dans cet exemple, nous utiliserons « my_tag_count » comme valeur d’action. La déclaration de cette paire clé-valeur ressemble à ceci :

action: "my_tag_count"

Toutes les autres données dont le serveur a besoin pour accomplir sa tâche sont également incluses dans ce tableau. S’il y a beaucoup de champs à transmettre, il existe deux formats courants pour combiner les champs de données en une seule chaîne pour une transmission plus pratique : XML et JSON. L’utilisation de ces formats est facultative, mais ce que vous faites doit être coordonné avec le script PHP côté serveur. De plus amples informations sur ces formats sont disponibles dans la section Callback suivante. Il est plus courant de recevoir des données dans ce format que de les envoyer, mais cela peut fonctionner dans les deux sens.

Dans notre exemple, le serveur n’a besoin que d’une seule valeur, une chaîne de caractères unique pour le titre du livre sélectionné, nous utiliserons donc la clé « title ». Dans jQuery, l’objet qui a déclenché l’événement est toujours contenu dans la variable this. Par conséquent, la valeur de l’élément sélectionné est this.value. Notre déclaration de cette paire clé-valeur se présente comme suit :

title: this.value

Rappel

Le gestionnaire de rappel est la fonction à exécuter lorsqu’une réponse est renvoyée par le serveur après la requête. Une fois de plus, nous voyons généralement une fonction anonyme ici. La fonction reçoit un paramètre, la réponse du serveur. La réponse peut aller d’un oui ou d’un non à une énorme base de données XML. Les données au format JSON sont également un format utile pour les données. La réponse n’est même pas nécessaire. S’il n’y en a pas, il n’est pas nécessaire de spécifier un rappel. Dans l’intérêt de l’interface utilisateur, il est toujours bon de faire savoir à l’utilisateur ce qu’il est advenu d’une requête, et il est donc recommandé de toujours répondre et de fournir une indication que quelque chose s’est passé.

Dans notre exemple, nous remplaçons le texte actuel qui suit l’entrée radio par la réponse du serveur, qui comprend le nombre d’articles marqués par le titre du livre. Voici notre fonction de rappel anonyme :

function( data ) {
  this2.nextSibling.remove();
  $( this2 ).after( data );
}

contient l’intégralité de la réponse du serveur. Plus tôt, nous avons assigné à this2 l’objet qui a déclenché l’événement de changement (référencé comme this) avec la ligne var this2 = this ;. Cela s’explique par le fait que la portée des variables dans les fermetures ne s’étend que sur un niveau. En assignant this2 dans le gestionnaire d’événement (la partie qui contenait initialement « /* do stuff */ »), nous sommes en mesure de l’utiliser dans le callback où this serait hors de portée.

La réponse du serveur peut prendre n’importe quelle forme. Les quantités importantes de données doivent être encodées dans un flux de données pour en faciliter la manipulation. XML et JSON sont deux schémas d’encodage courants.

XML

XML est l’ancien format d’échange de données pour AJAX. C’est après tout le « X » d’AJAX. Il reste un format d’échange viable, même s’il peut être difficile à utiliser avec les fonctions natives de PHP. De nombreux programmeurs PHP préfèrent le format d’échange JSON pour cette raison. Si vous utilisez XML, la méthode d’analyse dépend du navigateur utilisé. Utilisez Microsoft.XMLDOM ActiveX pour Internet Explorer et utilisez DOMParser pour tous les autres. Notez qu’Internet Explorer n’est plus supporté par WordPress depuis la version 5.8.

JSON

JSON est souvent privilégié pour sa légèreté et sa facilité d’utilisation. Vous pouvez en fait analyser JSON en utilisant eval(), mais ne le faites pas ! L’utilisation de eval() comporte des risques de sécurité importants. Utilisez plutôt un analyseur dédié, qui est également plus rapide. Utilisez l’instance globale de l’objet analyseur JSON. Pour vous assurer qu’il est disponible, veillez à ce qu’il soit mis en file d’attente avec les autres scripts de la page. De plus amples informations sur la mise en file d’attente sont fournies plus loin dans la section PHP.

Résumé côté client

Maintenant que nous avons ajouté notre callback comme paramètre final de la fonction $.post(), nous avons terminé notre exemple de script jQuery Ajax. Tous les éléments réunis ressemblent à ceci :

jQuery(document).ready(function($) {         //wrapper
	$(".pref").change(function() {          //event
		var this2 = this;                  //use in callback
		$.post(my_ajax_obj.ajax_url, {      //POST request
			_ajax_nonce: my_ajax_obj.nonce, //nonce
			action: "my_tag_count",         //action
			title: this.value               //data
			}, function(data) {            //callback
				this2.nextSibling.remove(); //remove current title
				$(this2).after(data);       //insert server response
			}
		);
	} );
} );

Ce script peut être intégré dans un bloc de la page web ou être contenu dans son propre fichier. Ce fichier peut se trouver n’importe où sur Internet, mais la plupart des développeurs de plugins le placent dans un sous-dossier /js/ du dossier principal du plugin. À moins que vous n’ayez une raison de faire autrement, vous pouvez suivre la convention. Pour cet exemple, nous nommerons notre fichier myjquery.js