Heartbeat API Komme i gang

Med 3.6, aka "Oscar", nettopp utgitt, kan vi se på noen av de nye funksjonene som er tilgjengelige for utviklere. Spesielt i denne serien ser jeg på den nye hjertebanken API, og demonstrerer hvordan du kan bruke den i pluginene og temaene dine.

Hva er Heartbeat API?

Heartbeat API muliggjør regelmessig kommunikasjon mellom brukerens nettleser og serveren. En av de opprinnelige motivasjonene var å tillate låseposter og advarselbrukere når flere enn en bruker forsøker å redigere et innlegg, eller varsle brukeren når innloggingen er utløpt.

Denne "kommunikasjonen" innebærer rutinemessig å sende data til serveren, som deretter reagerer med passende data. API gir mulighet for plugins å legge ved egne data i begge ender, noe som gir plugin din muligheten til å kommunisere mellom server og nettleser. Du kan tenke på disse stadiene (data sendt fra nettleser til server og svar sendt fra server til nettleser) som de to "beats" som utgjør en hjertesyklus. Hele denne prosessen gjentas med jevne mellomrom. Alt dette skjer i bakgrunnen, så mesteparten av tiden vil du sannsynligvis aldri vite at den er der.

Sende data fra nettleser til server

Heartbeat starter som standard automatisk, men sender bare data til serveren når den har data som skal sendes. For å kreve data må du bruke wp.heartbeat.enqueue () Funger i JavaScript-filen din. Denne funksjonen tar tre argumenter:

Håndtak - (streng) Dette er bare en strengidentifikator for dine data. Pass på at den er unik.
Data - (objekt) Dataene som skal sendes som et objekt.
Overstyring - (bool) Enten å over-ride eksisterende data. Hvis det er sant, erstattes alle data som tidligere er lagt til med håndtaket. Hvis feil og data allerede eksisterer for det håndtaket, gjør det ingenting.

For eksempel:

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

Merk: Eventuelle data som sendes med et slag, blir umiddelbart fjernet fra køen. Data som er kalkulert etter det punktet sendes med neste takt.

For å sjekke om et bestemt håndtak allerede har data som venter i køen, eller for å hente dataene, kan du bruke wp.heartbeat.isQueued (). Denne funksjonen tar et håndtak som eneste argument og returnerer heller null eller tilhørende data som venter i køen.

Dette er nyttig, for eksempel hvis du vil legge til ekstra argumenter for allerede data i kø:

 // Data for å legge til var new_data = 'version': '3.6'; hvis (data = wp.heartbeat.isQueued ('wptuts-plugin')) // Data eksisterer allerede - fusjonere data med nye data new_data = jQuery.extend (data, new_data);  // Kjøre og over-ride eksisterende data wp.heartbeat.enqueue ('wptuts-plugin', new_data, true); / * wptuts-plugin har nå data og new_data knyttet til det: 'foo': 'bar', 'wp': 'tuts', 'version': '3.6'; * /

Tips: Du bør liste 'hjerteslag'som en avhengighet for eventuelle JavaScript-filer som bruker denne APIen. Vi vil dekke dette, sammen med et fungerende eksempel plugin, i del tre.

Sende data fra server til nettleser

Ved neste "beat" sendes de ovennevnte dataene til serveren, når disse dataene er mottatt på serversiden, er det tre kroker som utløses:

heartbeat_received - Dette filtrerer serverens svar på nettleseren. Den sender også dataene mottatt fra nettleseren og admin skjerm-ID (eller "front" hvis denne forespørselen er fra frontend).
heartbeat_send - Denne kroken filtrerer også serverens svar på nettleseren. Den eneste forskjellen mellom det ovennevnte filteret er at den ikke overfører de mottatte dataene.
heartbeat_tick - Denne handlingen utløses like før svaret er angitt. Den overfører responsarrangementet og skjerm-ID som argumenter.

Hvis den nåværende brukeren er logget ut, er krokene:

heartbeat_nopriv_received
heartbeat_nopriv_send
heartbeat_nopriv_tick

utløses i stedet. (nopriv står for ingen privilegier)

For det meste trenger du sannsynligvis bare det første av disse filtrene: heartbeat_received / heartbeat_nopriv_received. Disse filtrene sender data mottatt fra nettleseren, og tillater oss å sjekke om vi har data knyttet til håndtaket vårt, før du inkluderer vårt svar:

 funksjon wptuts_respond_to_browser ($ respons, $ data, $ screen_id) hvis (isset ($ data ['wptuts-plugin'])) // Vi har data med vårt håndtak! La oss svare med noe ... // ekko $ data ['wptuts-plugin'] ['foo']; // utskrifter 'bar'; $ respons ['wptuts-plugin'] = array ('hello' => 'verden');  returner $ respons;  // Logget på brukere: add_filter ('heartbeat_received', 'wptuts_respond_to_browser', 10, 3); // Logget ut brukere add_filter ('heartbeat_nopriv_received', 'wptuts_respond_to_browser', 10, 3);

Lytte til retur "Beat"

Til slutt, for å fullføre syklusen, kan vi lytte etter når svaret fra serveren mottas av nettleseren. Når dette skjer, utløser WordPress hendelsen hjerterytme-tick. Vi kan hekte på dette med vår tilbakeringing for å behandle svaret:

 jQuery (dokument) .ready (funksjon ($) $ (dokument) .on ('heartbeat-tick.wptuts-plugin', funksjon (hendelse, data) if (data.hasOwnProperty ('wptuts-plugin'))  console.log (data ['wptuts-plugin']); // Skriver til konsollen 'hallo': 'world';;);

Merk: Det anbefales sterkt at du bruker namespaced hendelser, det er du bind din tilbakeringing til heartbeat-tick. unikt navneområde som ovenfor, og ikke bare hjerterytme-tick.

Det er i hovedsak hvordan du kan dra nytte av Heartbeat API. I neste del av serien ser vi på måter du kan manipulere taktens puls på. I den siste delen lager vi et fungerende eksempel på et plugin som bruker API.

Kode