WordPress 3.6 – HeartBeat API

Od czasu aktualizacji WordPressa do wersji 3.6 minęło już trochę czasu. Sporo już o niej napisano, o nowym odtwarzaczu multimediów, o nowej domyślnej skórce itd. Wielu skupiało się na efektach wizualnych jakie wprowadził ze sobą „Oscar”, ja natomiast chciałbym zająć się częścią przeznaczą dla developerów. Dziś opiszę Heartbeat API, dzięki któremu działa m.in. blokowanie postów edytowanych już przez kogoś innego, lub informowanie użytkownika o wygaśnięciu jego sesji logowania.

Czym jest HertBeat API?

Heartbeat API umożliwia ciągłą komunikację przeglądarki z serwerem. Komunikacja ta polega na cyklicznym wysyłaniu danych do serwera, który w reakcji na to odsyła dane wykorzystywane przez przeglądarkę. Proces ten jest powtarzany regularnie, przypominając bicie ludzkiego serca, dzięki czemu zresztą zawdzięcza swoją nazwę. Wszystko to odbywa się w tle, nie wpływając tym samym na pracę użytkownika. Ważny jest też fakt, że HeartBeat API startuje automatycznie po załadowaniu strony, ale z serwerem komunikuje się tylko wtedy gdy posiada jakieś dane do wysłania.

Komunikacja przeglądarka -> serwer

Do komunikowania się przeglądarki z serwerem wykorzystywana jest, napisana w JavaScripcie biblioteka heartbeat. Oznacza to, że każdy utworzony skrypt do poprawnego działania wymaga by wcześniej został załadowany plik heartbeat.js.

wp_enqueue_script(
 'heartbeat_example',
 get_template_directory_uri() .'/heartbeat_example.js',
 array( 'heartbeat'),
 '1.0.0',
 true
);

Aby wysłać jakieś dane do serwera musimy je najpierw dodać do kolejki dzięki metodzie wp.heartbeat.enqueue(), która przyjmuje 3 parametry:

  • handle – (string) identyfikator wysyłanych na serwer danych. Powinien być unikatowy.
  • data – (object) dane wysyłane do serwera
  • override – (bool) jeżli true to wcześniejsze dane przypisane do identyfikatora zostaną nadpisane

Przykład użycia:

wp.heartbeat.enqueue('sign_in', {
    'name': 'chemikpil'
}, false};

Dodane do kolejki dane, oczekują na wysłanie do serwera, co następuje co 15 sekund, po czym są z niej usuwane. Aby sprawdzić czy nastąpiło już wysłanie, możemy skorzystać z metody wp.heartbeat.isQueued(handle), która zwraca null lub przypisane do identyfikatora informacje.

Komunikacja serwer -> przeglądarka

Po odebraniu danych przez serwer, są one ponownie zwracane do przeglądarki. Podczas tego procesu uruchamiane są dwa pomocne hooki, dzięki którym mamy możliwość wpływać na informacje wracające do przeglądarki.

  • heartbeat_received – filtr pozwalający na modyfikowanie zwracanej odpowiedzi. Dodatkowo przekazywane są również dane przesłane przez przeglądarkę oraz screen_id, lub front jeżeli użytkownik nie jest zalogowany.
  • heartbeat_send – filtr działa podobnie do powyższego, z ta różnicą, że nie są przekazywane dane z przeglądarki.

Powyższe filtry działają dla użytkowników zalogowanych i posiadają swoje odpowiedniki dla przypadków, kiedy dany użytkownik nie jest zalogowany:

  • heartbeat_nopriv_received
  • heartbeat_nopriv_send

Przykład użycia:

function admin_sign_in($response, $data, $screen_id) {
    if (isset($data['sign-in'])) {
        $response['sign-in'] = array(
            'message' => 'admin is here!'
        );
    }
    return $response;
}

add_filter('heartbeat_received','admin_sign_in',10,3);
add_filter('heartbeat_nopriv_received','admin_sign_in',10,3);

Nasłuchiwanie danych

Na koniec pozostaje nam już tylko odebrać dane po stronie przeglądarki. Robimy to poprzez nasłuchiwanie eventu heartbeat-tick.

document.addEventListener('heartbeat-tick.sign-in', 
    function (event, data) {
        if (data.hasOwnProperty('sign-in')) {
            console.log(data['sign-in']);
        }
    },
false);

Konfiguracja

Po za wysyłaniem i odbieranie danych mamy możliwość również konfigurowania samego działania Heartbeat API.

Zmiana pulsu

function heartbeat_api_settings( $settings ) {
    $settings['interval'] = 60;
    return $settings;
}
add_filter( 'heartbeat_settings', 'heartbeat_api_settings' );

Powyżej zmieniliśmy domyślny interwał $settings['interval'], który przyjmuje wartość pomiędzy 15 a 60 sekund. Przypomnijmy ponownie, że domyślny puls wynosi 15 sekund.

Puls możemy również zmienić po stronie JS przy pomocy metody

wp.heartbeat.interval(interval);

z tym że tutaj możemy użyć tylko trzech wartości, które są stringami

  • fast – puls co 5 sekund przy czym tylko na maximum 2,5 minuty, po czym wraca do domyślnego ustawienia
  • standard – puls co 15 sekund
  • slow – puls co 60 sekund

Wyłączenie autostartu

Kolejna zmiana to wyłączenie autostartu:

function heartbeat_api_settings( $settings ) {
    $settings['autostart'] = false;
    return $settings;
}
add_filter( 'heartbeat_settings', 'heartbeat_api_settings' );

Po tej zmianie możemy go ponownie włączyć z poziomu JavaScriptu przy pomocy metody:

wp.heartbeat.start();

Można go również z poziomu JS wyłączyć:

wp.heartbeat.stop();

Podsumowanie

To by było na tyle jeżeli chodzi o HeartBeat API. Jak widać jest to całkiem fajna opcja, dająca autorom pluginów jeszcze większe pole manewrów niż dotychczas. Wystarczy tak naprawdę poznanie kilku JavaScriptowych funkcji oraz filtrów od strony PHP. Nie jest to oczywiście jedyna zmiana, która pojawiła się wraz z „Oscarem”, ale o tym w kolejnych wpisach.