- 20.06.15
- 09:05
- 1743
- 0
Автор: Pippin Williamson.
Оригинал: Using the WordPress Heartbeat API.
Замечание: перевод вольный, некоторые высказывания заменены на более понятные (на мой взгляд), и добавлены примечания. Все примечания опираются на WP 4.2.2.
— Г.К.
В WordPress 3.6 был введён новый API, называемый «WordPress Heartbeat». На нём основано множество сделанных в этой версии изменений, включая более развитую систему отслеживания ревизий, улучшенное управление пользовательскими сессиями и многое другое. Я собираюсь показать краткий пример использования этого API.
Что такое Heartbeat API?
Heartbeat API очень точно назван (heartbeat — сердцебиение). Его можно сравнить с сердцем: точно как человеческое сердце, бьющееся и вызывающее пульсацию в сосудах, Heartbeat API издаёт «пульсации» (технически называемые «тиками» — tick), которые затем улавливаются и обрабатываются с целью периодического выполнения каких-либо действий.
Одной из положительных сторон Heartbeat API является то, что он почти полностью реализован на JavaScript — это позволяет действовать не только на стороне сервера, но и на просматриваемой пользователем странице. Например, используя Heartbeat API можно синхронизировать информацию, отображённую браузером, со значениями в базе данных, иногда меняющимися. Реализация подобных вещей состоит из двух частей:
- обработки события «send» — начала пульса — при которой отправляемая серверу информация снабжается к.-л. данными (возможно, прежде полученными из БД);
- обработки события «tick» — для получения данных и модификации отображаемой страницы (и/или других действий) силами JavaScript.
В качестве реального работающего примера можно привести плагин Easy Digital Downloads, где мы в реальном времени обновляем виджет админской консоли, отображающий информацию по продажам. После каждой новой сделки информация в БД меняется, а отображаемая в виджете статистика автоматически обновляется через некоторое время.
Примечание: интервал обновления варьируется от 15 до 120 сек., по умолчанию — 60.
Процесс обновления статистики выглядит примерно так:
- обработчик события
'heartbeat-send'
, возникающего при отправке «пульса», добавляет в отправляемые данные определённый ключ, заставляющий сервер включить в ответ информацию по продажам; - обработчик события
'heartbeat-tick'
, происходящего при получении от сервера ответного «пульса», разбирает полученные данные и, если запрошенная в п.1 информация имеется, переходит к п.3; - новые значения извлекаются из пришедших данных и вносятся в содержимое виджета статистики, включается индикация изменений.
Взглянем на реализующий эти пункты код.
Во-первых, мы должны подключить JS-скрипт с Heartbeat API:
1 2 3 4 5 6 7 8 |
<?php // загрузка JS-скрипта с Heartbeat API function edd_heartbeat_enqueue( $hook_suffix ) { // включаем в вывод страницы скрипт с браузерной частью Heartbeat API wp_enqueue_script( 'heartbeat' ); add_action( 'admin_print_footer_scripts', 'edd_heartbeat_footer_js', 20 ); } add_action( 'admin_enqueue_scripts', 'edd_heartbeat_enqueue' ); |
Функция выдачи нашего скрипта, использующего Heartbeat API, повешена на хук 'admin_print_footer_scripts'
— скрипт будет выведен в футере консоли администрирования. Происходит это следующим образом:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
<?php // Встраиваем наш скрипт в футер консоли администрирования WordPress function edd_heartbeat_footer_js() { global $pagenow; // только если находимся на самой консоли if( 'index.php' != $pagenow ) return; ?> <script> (function($){ // обрабатываем отправку пульса: $(document).on('heartbeat-send', function(e, data) { data['edd_heartbeat'] = 'dashboard_summary'; }); // ловим событие "heartbeat-tick" на элементе $(document): $(document).on( 'heartbeat-tick', function(e, data) { // продолжаем, только если ответ содержит требуемые данные if ( ! data['edd-payment-count'] ) return; // убедимся, что всё работает, заглянув в консоль console.log( data['edd-payment-count'] ); // обновим информацию по продажам и выделим её жирным шрифтом $('.edd_dashboard_widget .b.b-sales') .text( data['edd-payment-count'] ) .css( 'font-weight', 'bold' ); // удаляем выделение через 2 секунды setTimeout(function(){ $('.edd_dashboard_widget .b.b-sales') .css( 'font-weight', 'normal' ); }, 2000); }); }(jQuery)); </script> <?php } |
Почти вся «магия» происходит здесь. В строках 13-16 мы добавляем ключ 'edd_heartbeat'
и устанавливаем его значение в 'dashboard_summary'
, определяя тем самым данные, которые требуются нам от сервера (код формирования ответа сервера — чуть ниже).
Обработчик ответа сервера (тика) находится в строках 18-39. С каждым тиком приходит массив данных, в котором мы отыскиваем нужную нам информацию. В этом случае data['edd-payment-count']
просто содержит целое, являющееся общим количеством продаж в системе. Мы можем взять это целое и внести изменения в текст виджета. Для удобства добавлена смена стилей, заставляющая количество продаж «пульсировать» при каждом обновлении.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<?php // фильтр данных, отправляемых в ответ на heartbeat-tick function edd_heartbeat_received( $response, $data ) { // отправляем только запрашиваемые данные if( $data['edd_heartbeat'] == 'dashboard_summary' ) { // получаем счётчик платежей $payments = edd_count_payments(); // отправляем количество выполненных платежей $response['edd-payment-count'] = number_format_i18n( $payments->publish ); } return $response; } add_filter( 'heartbeat_received', 'edd_heartbeat_received', 10, 2 ); |
Заметьте, что первым делом проверяется ключ edd_heartbeat
, а данные дополняются при его значении 'dashboard_summary'
. Это обеспечивает отправку данных только при необходимости.
Внутри блока условия мы просто запрашиваем количество платежей, сделанных в магазине, и отправляем браузеру как часть ответа. Это те самые данные, с которыми работает приведённый выше JS-скрипт.
Вот и всё: это и есть WordPress Heartbeat API.
Пример плагина с тестом можно скачать здесь.
Примечание: чтобы посмотреть на работу плагина с тестом, следует прежде установить и активировать плагин Easy Digital Downloads (легко отыскивается по имени штатным установщиком плагинов /wp-admin/plugin-install.php
).
Ещё примечание: по умолчанию обновление происходит раз в минуту, поэтому ждать двухсекундного изменения жирности нулей продаж обременительно долго. Чтобы установить интервал в минимум — 15 секунд — следует добавить в тестовый плагин такой код:
1 2 3 4 5 |
function edd_heartbeat_settings( $settings ) { $settings['interval'] = 15; return $settings; } add_filter( 'heartbeat_settings', 'edd_heartbeat_settings' ); |