La API de Heartbeat Cómo empezar

Con 3.6, también conocido como "Oscar", recién lanzado, echemos un vistazo a algunas de las nuevas características que están disponibles para los desarrolladores. En particular, en esta serie, veré la nueva API de heartbeat y demostraré cómo puede usarla en sus complementos y temas..

¿Qué es la API de Heartbeat??

La API de heartbeat permite una comunicación regular entre el navegador del usuario y el servidor. Una de las motivaciones originales fue permitir el bloqueo de publicaciones y advertir a los usuarios cuando más de un usuario está intentando editar una publicación, o advertir al usuario cuando su inicio de sesión ha caducado..

Esta "comunicación" implica el envío rutinario de datos al servidor, que luego responde con los datos apropiados. La API permite que los complementos adjunten sus propios datos en ambos extremos, lo que le da a su complemento la capacidad de comunicarse también entre el servidor y el navegador. Puede pensar en estas etapas (datos enviados desde el navegador al servidor y respuesta enviada desde el servidor al navegador) como los dos "tiempos" que constituyen un ciclo cardíaco. Todo este proceso se repite a intervalos regulares. Todo esto sucede en segundo plano, por lo que la mayoría de las veces probablemente nunca sepas que está ahí..

Enviando datos desde el navegador al servidor

Por defecto, Heartbeat comienza a ejecutarse automáticamente, pero solo envía datos al servidor cuando tiene datos para enviar. Para encolar datos debes usar el wp.heartbeat.enqueue () Funciona en tu archivo JavaScript. Esta función toma tres argumentos:

Encargarse de - (cadena) Esto es solo un identificador de cadena para sus datos. Asegúrate de que sea único.
Datos - (objeto) Los datos a enviar como un objeto..
Anular - (bool) Si se debe anular existente datos. Si es verdadero, se reemplazan todos los datos agregados previamente con el identificador proporcionado. Si es falso y ya existen datos para ese manejo, no hace nada..

Por ejemplo:

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

Nota: Todos los datos que se envían con un tiempo se eliminan inmediatamente de la cola. Los datos en cola después de ese punto se envían con el siguiente tiempo..

Para verificar si un identificador en particular ya tiene datos en espera en la cola, o para recuperar esos datos, puede usar wp.heartbeat.isQueued (). Esta función toma un controlador como su único argumento y devuelve cualquiera nulo o los datos asociados esperando en la cola.

Esto es útil, por ejemplo, si desea agregar argumentos adicionales a los datos ya en cola:

 // Datos para agregar var new_data = 'version': '3.6'; if (data = wp.heartbeat.isQueued ('wptuts-plugin')) // Los datos ya existen - fusionar datos con nuevos datos new_data = jQuery.extend (data, new_data);  // Poner en cola y anular los datos existentes wp.heartbeat.enqueue ('wptuts-plugin', new_data, true); / * wptuts-plugin ahora tiene los datos y new_data asociados: 'foo': 'bar', 'wp': 'tuts', 'version': '3.6'; * /

Propina: Deberías enumerarlatido del corazón'como una dependencia para cualquier archivo JavaScript que haga uso de esta API. Cubriremos esto, junto con un complemento de ejemplo de trabajo, en la tercera parte..

Enviando datos desde el servidor al navegador

En el siguiente 'tiempo', los datos anteriores se envían al servidor. Cuando se reciben estos datos del lado del servidor, hay tres enlaces que se activan:

heartbeat_received - Esto filtra la respuesta del servidor al navegador. También pasa los datos recibidos desde el navegador y la identificación de la pantalla del administrador (o "frente" si esta solicitud es del frente).
heartbeat_send - Este gancho también filtra la respuesta del servidor al navegador. Su única diferencia con el filtro anterior es que no pasa los datos recibidos.
heartbeat_tick - Esta acción se activa justo antes de que se establezca la respuesta. Pasa la matriz de respuesta y la ID de pantalla como argumentos.

Si el usuario actual se desconecta, los ganchos:

heartbeat_nopriv_received
heartbeat_nopriv_send
heartbeat_nopriv_tick

se activan en su lugar. (nopriv representa sin privilegios)

En su mayor parte, probablemente solo necesitará el primero de estos filtros: heartbeat_received / heartbeat_nopriv_received. Estos filtros pasan los datos recibidos del navegador y, por lo tanto, nos permiten verificar si tenemos datos asociados con nuestro identificador, antes de incluir nuestra respuesta:

 función wptuts_respond_to_browser ($ response, $ data, $ screen_id) if (isset ($ data ['wptuts-plugin'])) // ¡Tenemos datos con nuestro identificador! Respondamos con algo ... // echo $ data ['wptuts-plugin'] ['foo']; // imprime 'bar'; $ response ['wptuts-plugin'] = array ('hello' => 'world');  devolver $ respuesta;  // Usuarios registrados: add_filter ('heartbeat_received', 'wptuts_respond_to_browser', 10, 3); // Usuarios desconectados add_filter ('heartbeat_nopriv_received', 'wptuts_respond_to_browser', 10, 3);

Escuchando el regreso 'Beat'

Finalmente, para completar el ciclo, podemos escuchar cuando el navegador recibe la respuesta del servidor. Cuando esto sucede, WordPress activa el evento. latido del corazón. Podemos conectarnos a esto con nuestra devolución de llamada para procesar la respuesta:

 jQuery (document) .ready (function ($) $ (document) .on ('heartbeat-tick.wptuts-plugin', function (event, data) if (data.hasOwnProperty ('wptuts-plugin'))  console.log (data ['wptuts-plugin']); // Imprime en la consola 'hello': 'world'););

Nota: Se recomienda encarecidamente que utilice eventos con espacios de nombre, es decir, vincule su devolución de llamada a corazón-tick. espacio de nombres único como arriba, y no solo latido del corazón.

Eso, en esencia, es cómo aprovechar la API de Heartbeat. En la siguiente parte de la serie veremos formas de manipular el pulso del ritmo. En la parte final, crearemos un ejemplo funcional de un complemento que utiliza la API..

Código