Начиная с версии 3.6, также известной как «Оскар», давайте взглянем на некоторые новые функции, доступные для разработчиков. В частности, в этой серии я расскажу о новом API сердцебиения и продемонстрирую, как вы можете использовать его в своих плагинах и темах.
Что такое Heartbeat API?
API heartbeat обеспечивает регулярную связь между браузером пользователя и сервером. Одна из первоначальных мотивов заключалась в том, чтобы разрешить блокировку постов и предупреждать пользователей, когда более одного пользователя пытаются редактировать пост, или предупреждать пользователя, когда их вход в систему истек.
Это «общение» включает в себя регулярную отправку данных на сервер, который затем отвечает любыми подходящими данными. API позволяет подключаемым модулям прикреплять свои собственные данные на обоих концах, давая вашему плагину возможность также обмениваться данными между сервером и браузером. Вы можете думать об этих этапах (данные, отправленные из браузера на сервер, и ответ, отправленный с сервера в браузер) как два «удара», которые составляют сердечный цикл. Весь этот процесс повторяется через равные промежутки времени. Все это происходит в фоновом режиме, поэтому большую часть времени вы, вероятно, никогда не узнаете, что это там.
Отправка данных из браузера на сервер
По умолчанию Heartbeat запускается автоматически, но отправляет данные на сервер только при наличии данных для отправки. Чтобы поставить в очередь данные, вы должны использовать wp.heartbeat.enqueue() в вашем файле JavaScript. Эта функция принимает три аргумента:
-
Handle— (строка) Это просто строковый идентификатор для ваших данных. Убедитесь, что это уникально. -
Data— (объект) Данные для отправки в качестве объекта. -
Override— (bool) Следует лиOverrideсуществующие данные. Если true, любые данные, ранее добавленные с указанным дескриптором, заменяются. Если false и данные для этого дескриптора уже существуют, он ничего не делает.
Например:
|
1
2
3
4
5
6
7
8
|
wp.heartbeat.enqueue(
‘wptuts-plugin’,
{
‘foo’: ‘bar’,
‘wp’: ‘tuts’,
},
false
);
|
Примечание. Любые данные, отправленные с ударом, немедленно удаляются из очереди. Данные, поставленные в очередь после этой точки, отправляются со следующим тактом.
Чтобы проверить, есть ли у определенного дескриптора данные, ожидающие в очереди, или для извлечения этих данных, вы можете использовать wp.heartbeat.isQueued() . Эта функция принимает дескриптор в качестве единственного аргумента и возвращает либо null либо связанные данные, ожидающие в очереди.
Это полезно, например, если вы хотите добавить дополнительные аргументы к уже поставленным в очередь данным:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
// Data to add
var new_data = {
‘version’: ‘3.6’
};
if ( data = wp.heartbeat.isQueued( ‘wptuts-plugin’ ) ) {
// Data already exists — merge data with new data
new_data = jQuery.extend( data, new_data );
}
// Queue and over-ride existing data
wp.heartbeat.enqueue(
‘wptuts-plugin’,
new_data,
true
);
/*
wptuts-plugin now has the data and new_data associated with it:
{
‘foo’: ‘bar’,
‘wp’: ‘tuts’,
‘version’: ‘3.6’
};
*/
|
Совет: Вы должны указать « heartbeat » в качестве зависимости для любых файлов JavaScript, которые используют этот API. Мы рассмотрим это вместе с рабочим примером плагина в третьей части.
Отправка данных с сервера в браузер
При следующем «бите» вышеуказанные данные отправляются на сервер, когда эти данные принимаются на стороне сервера, запускаются три перехвата:
-
heartbeat_received— фильтрует ответ сервера на браузер. Он также передает данные, полученные из браузера, и идентификатор экрана администратора (или «front», если этот запрос от front-end). -
heartbeat_send— эта ловушка также фильтрует ответ сервера на браузер. Его единственное отличие от вышеуказанного фильтра состоит в том, что он не пропускает полученные данные. -
heartbeat_tick— это действие запускается непосредственно перед тем, как будет установлен ответ. Он передает массив ответов и идентификатор экрана в качестве аргументов.
Если текущий пользователь вышел из системы, то перехватывает:
-
heartbeat_nopriv_received -
heartbeat_nopriv_send -
heartbeat_nopriv_tick
срабатывает вместо. ( nopriv означает никаких привилегий )
По большей части вам, вероятно, понадобится только первый из этих фильтров: heartbeat_received / heartbeat_nopriv_received . Эти фильтры передают данные, полученные из браузера, и поэтому позволяют нам проверить, есть ли у нас какие-либо данные, связанные с нашим дескриптором, прежде чем включать наш ответ:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
|
function wptuts_respond_to_browser( $response, $data, $screen_id ) {
if ( isset( $data[‘wptuts-plugin’] ) ) {
// We have data with our handle!
// echo $data[‘wptuts-plugin’][‘foo’];
$response[‘wptuts-plugin’] = array(
‘hello’ => ‘world’
);
}
return $response;
}
// Logged in users:
add_filter( ‘heartbeat_received’, ‘wptuts_respond_to_browser’, 10, 3 );
// Logged out users
add_filter( ‘heartbeat_nopriv_received’, ‘wptuts_respond_to_browser’, 10, 3 );
|
Прислушиваясь к ответу «Удар»
Наконец, чтобы завершить цикл, мы можем прослушивать, когда браузер получает ответ от сервера. Когда это происходит, WordPress запускает тактовую метку события. Мы можем подключиться к этому с помощью нашего обратного вызова для обработки ответа:
|
01
02
03
04
05
06
07
08
09
10
|
jQuery(document).ready( function($) {
$(document).on( ‘heartbeat-tick.wptuts-plugin’, function( event, data ) {
if ( data.hasOwnProperty( ‘wptuts-plugin’ ) ) {
console.log( data[‘wptuts-plugin’] );
// Prints to the console { ‘hello’ : ‘world’ }
}
});
});
|
Примечание. Настоятельно рекомендуется использовать события в пространстве имен, то есть привязывать обратный вызов к heartbeat-tick.{unique namespace} как указано выше, а не просто к heartbeat-tick .
По сути, это то, как воспользоваться API Heartbeat. В следующей части серии мы рассмотрим способы манипулирования импульсом ритма. В заключительной части мы создадим рабочий пример плагина, который использует API.