API Heartbeat Mise en route

Avec la version 3.6, également connue sous le nom de "Oscar", qui vient de paraître, examinons certaines des nouvelles fonctionnalités offertes aux développeurs. Dans cette série, je vais en particulier examiner la nouvelle API Heartbeat et expliquer comment vous pouvez l'utiliser dans vos plugins et vos thèmes..

Qu'est-ce que l'API Heartbeat??

L'API de pulsation permet une communication régulière entre le navigateur de l'utilisateur et le serveur. L'une des motivations initiales était d'autoriser le verrouillage des publications et d'avertir les utilisateurs lorsque plusieurs utilisateurs tentaient de modifier une publication, ou d'avertir l'utilisateur lorsque leur connexion avait expiré..

Cette "communication" implique l'envoi systématique de données au serveur, qui répond ensuite avec les données appropriées. L'API permet aux plugins de joindre leurs propres données aux deux extrémités, ce qui permet à votre plugin de communiquer également entre le serveur et le navigateur. Vous pouvez considérer ces étapes (données envoyées d'un navigateur à un serveur et réponse envoyées d'un serveur à un autre) comme les deux «battements» constituant un cycle cardiaque. Tout ce processus est répété à intervalles réguliers. Tout cela se passe en arrière-plan, donc la plupart du temps, vous ne saurez probablement jamais que c'est là..

Envoi de données d'un navigateur à un serveur

Par défaut, Heartbeat s'exécute automatiquement, mais il n'envoie jamais de données au serveur que lorsqu'il a des données à envoyer. Pour mettre les données en file d'attente, vous devez utiliser le wp.heartbeat.enqueue () fonctionner dans votre fichier JavaScript. Cette fonction prend trois arguments:

Manipuler - (chaîne) Ceci est juste un identifiant de chaîne pour vos données. Assurez-vous que c'est unique.
Les données - (objet) Les données à envoyer en tant qu'objet.
Passer outre - (bool) S'il faut passer outre existant Les données. Si la valeur est true, toutes les données précédemment ajoutées avec le descripteur fourni sont remplacées. Si false et que des données existent déjà pour ce handle, cela ne fait rien.

Par exemple:

 wp.heartbeat.enqueue ('wptuts-plugin', 'foo': 'bar', 'wp': 'tuts',, false);

Remarque: Toutes les données envoyées avec un temps sont immédiatement supprimées de la file d'attente. Les données mises en file d'attente après que ce point est envoyé avec le temps suivant.

Pour vérifier si un descripteur particulier a déjà des données en attente dans la file d'attente ou pour récupérer ces données, vous pouvez utiliser le wp.heartbeat.isQueued (). Cette fonction prend un handle comme seul argument et retourne soit nul ou les données associées en attente dans la file d'attente.

Ceci est utile, par exemple, si vous souhaitez ajouter des arguments supplémentaires à des données déjà en file d'attente:

 // Données à ajouter var new_data = 'version': '3.6'; if (data = wp.heartbeat.isQueued ('wptuts-plugin')) // Des données existent déjà - fusionnez des données avec de nouvelles données new_data = jQuery.extend (data, new_data);  // Met en file d'attente et annule les données existantes wp.heartbeat.enqueue ('wptuts-plugin', new_data, true); / * wptuts-plugin a maintenant les données et new_data qui lui sont associées: 'foo': 'bar', 'wp': 'tuts', 'version': '3.6'; * /

Pointe: Vous devriez lister 'battement de coeur'en tant que dépendance pour tous les fichiers JavaScript utilisant cette API. Nous allons couvrir cela, avec un exemple de travail plugin, dans la troisième partie.

Envoi de données d'un serveur à un navigateur

Au «temps» suivant, les données ci-dessus sont envoyées au serveur. Lorsque ces données sont reçues côté serveur, trois points d'accrochage sont déclenchés:

battement de coeur reçu - Ceci filtre la réponse du serveur au navigateur. Il transmet également les données reçues du navigateur et l'ID d'écran d'administrateur (ou "front" si cette demande provient du front-end).
heartbeat_send - Ce hook filtre également la réponse du serveur au navigateur. Sa seule différence avec le filtre ci-dessus est qu'il ne transmet pas les données reçues..
battement de coeur - Cette action est déclenchée juste avant que la réponse ne soit définie. Il passe le tableau de réponse et l'ID d'écran en arguments.

Si l'utilisateur actuel est déconnecté, les crochets:

heartbeat_nopriv_received
heartbeat_nopriv_send
heartbeat_nopriv_tick

sont déclenchés à la place. (nopriv représente pas de privilèges)

Pour la plupart, vous n'aurez probablement besoin que du premier de ces filtres: battement de coeur reçu / heartbeat_nopriv_received. Ces filtres transmettent les données reçues du navigateur et nous permettent donc de vérifier si nous avons des données associées à notre descripteur, avant d’inclure notre réponse:

 function wptuts_respond_to_browser ($ response, $ data, $ screen_id) if (isset ($ data ['wptuts-plugin']))) // Nous avons des données avec notre descripteur! Permet de répondre avec quelque chose… // echo $ data ['wptuts-plugin'] ['foo']; // affiche 'bar'; $ response ['wptuts-plugin'] = array ('hello' => 'world');  return $ response;  // Utilisateurs connectés: add_filter ('heartbeat_received', 'wptuts_respond_to_browser', 10, 3); // Utilisateurs déconnectés add_filter ('heartbeat_nopriv_received', 'wptuts_respond_to_browser', 10, 3);

Ecouter le retour 'Beat'

Enfin, pour terminer le cycle, nous pouvons écouter le moment où la réponse du serveur est reçue par le navigateur. Lorsque cela se produit, WordPress déclenche l'événement. battement de coeur. Nous pouvons nous en servir avec notre rappel pour traiter la réponse:

 jQuery (document) .ready (function ($) $ (document) .on ('heartbeat-tick.wptuts-plugin', fonction (événement, données) if (data.hasOwnProperty ('wptuts-plugin')))  console.log (data ['wptuts-plugin']); // Imprime sur la console 'hello': 'world'););

Remarque: Il est fortement recommandé d’utiliser des événements namespaced, c’est-à-dire de lier votre rappel à heartbeat-tick. espace de noms unique comme ci-dessus, et pas seulement battement de coeur.

Voilà, en gros, comment tirer parti de l’API Heartbeat. Dans la prochaine partie de la série, nous verrons comment vous pouvez manipuler le pouls du battement. Dans la dernière partie, nous allons créer un exemple de travail d’un plugin utilisant l’API.

Code