New Post has been published on Mocco
New Post has been published on http://mocco.sk/heartbeat-api-using-heartbeat-in-a-plugin/
Heartbeat API: Using Heartbeat in a Plugin
In this tutorial weâre going to create a simple plugin which uses the Heartbeat API. Our plugin will alert logged in users, via a growl-like notification, whenever another user logs in or out of the site.
Since this tutorial is focussed on the Heartbeat API, I shall leave out details about creating the plugin header or file structure: the plugin is very simple, and you can examine the source code in full at this GitHub repository.
A user will be deemed âlogged inâ when they log in and have been active within the last 24 hours. If a user logs out or is not active for 24 hours, theyâll be considered to be offline. Weâll keep tabs on the userâs âonlineâ status and âlast activeâ timestamp to help determine whoâs currently online.
Logging-in and Logging-out
First weâll create a couple of functions hooked into wp_login and wp_logout hooks. These are triggered when a user logs in/out of WordPress. When a user logs in, weâll update their log in status (stored as user meta) to âtrueâ and update their last active timestamp.
function whoisonline_logged_in( $username, $user ) { update_user_meta( $user->ID, 'whoisonline_is_online', true ); update_user_meta( $user->ID, 'whoisonline_last_active', time() ); } add_action( 'wp_login', 'whoisonline_logged_in', 10, 2 );
Similarly, when a user logs out, weâll update their online status to false:
function whoisonline_logged_out() { $user_id = get_current_user_id(); update_user_meta( $user_id, 'whoisonline_is_online', false ); } add_action( 'wp_logout', 'whoisonline_logged_out' );
Whoâs Online?
Now letâs create a function which returns an array of usernames of active users, indexed by user ID. Weâll use the get_users() function to query all users who have been active in the last 24 hours (using the whoisonline_last_active meta key).
Weâll then discard any users who have logged out by checking the whoisonline_is_online user / meta data.
function who_is_online( $args = array() ) { // Get users active in last 24 hours $args = wp_parse_args( $args, array( 'meta_key' => 'whoisonline_last_active', 'meta_value' => time() - 24 * 60 * 60, 'meta_compare' => '>', 'count_total' => false, ) ); $users = get_users( $args ); // Initiate array $online_users = array(); foreach ( $users as $user ) { if ( ! get_user_meta( $user->ID, 'whoisonline_is_online', true ) ) continue; $online_users[$user->ID] = $user->user_login; } return $online_users; }
Preparing for the Heartbeat API
Before we deal with the client-side part of the Heaertbeat API, letâs deal with the serverâs response to a request for âwhoâs onlineâ. As was covered in part 1 of this series, weâll hook onto the filter heartbeat_received (we donât need to trigger this for logged out users so wonât use the heartbeat_nopriv_received filter).
First, weâll update the current userâs activity timestamp, and ensure their status is set to âonlineâ. Next weâll check that a request for âwhoâs onlineâ data has been made by looking for the who-is-online key (which weâll use later) in the received $data.
If it has, weâll respond with an array of logged in users of the form:
array( [User ID] => [User log in] )
As returned by who_is_online().
function whoisonline_check_who_is_online( $response, $data, $screen_id ) { // Update user's activity $user_id = get_current_user_id(); update_user_meta( $user_id, 'whoisonline_last_active', time() ); update_user_meta( $user_id, 'whoisonline_is_online', true ); // Check to see if "who's online?" has been requested if ( ! empty( $data['who-is-online'] ) ) { // Attach data to be sent $response['whoisonline'] = who_is_online(); } return $response; } add_filter( 'heartbeat_received', 'whoisonline_check_who_is_online', 10, 3 ); add_filter( 'heartbeat_received', 'whoisonline_check_who_is_online', 10, 3 );
Heartbeat API
Now create the JavaScript file who-is-online.js file in the root of your plugin folder. Below is the outline of the file.
First, we initiate our global variable whoisonline. whoisonline.online and whoisonline.onlinePrev are both âassociative arraysâ (strictly speaking, in terms of JavaScript, theyâre objects) of users logins, indexed by user ID â corresponding to those users who are âonlineâ at the current / previous beat. This is used to determine when a user has logged in or out.
We then initiate our request for data on whoâs online with wp.heartbeat.enqueue and listen for the response by binding a callback to the event heartbeat-tick.whoisonline. In that callback we check for data returned by the server, perform any necessary actions and then ensure our request for data is queued for the next beat.
// Inititate variables var whoisonline = { online: false, onlinePrev: false }; jQuery(document).ready(function() { //Set initial beat to fast - for demonstrative purposes only! wp.heartbeat.interval( 'fast' ); //Enqueue are data wp.heartbeat.enqueue( 'who-is-online', 'whoisonline', false ); jQuery(document).on( 'heartbeat-tick.whoisonline', function( event, data, textStatus, jqXHR ) { if ( data.hasOwnProperty( 'whoisonline' ) ) { // Perform actions with returned data } // In our example, we want to attach data for the next beat. // This might not be in the case in all applications: only queue data when you need to. wp.heartbeat.enqueue( 'who-is-online', 'whoisonline', false ); }); });
Now, letâs fill in the details of the logic inside our heartbeat-tick.whoisonline callback. Whenever data is received from the server we first check that it contains an array of logged in users (which would be given by the key âwhoisonlineâ), by checking data.hasOwnProperty( âwhoisonlineâ ). If soâŠ
Update whoisonline.onlinePrev to reflect who was online at the last beat, and whoisonline.online to reflect who is online at the current beat.
Check for user IDs that appear in whoisonline.online, but are not in whoisonline.onlinePrev. These users have just logged in.
Check for user IDs that appear in whoisonline.onlinePrev, but are not in whoisonline.online. These users have just logged out.
The finished JavaScript file then looks like:
var whoisonline = { online: false, onlinePrev: false }; jQuery(document).ready(function() { // Set initial beat to fast wp.heartbeat.interval( 'fast' ); // Enqueue are data wp.heartbeat.enqueue( 'who-is-online', 'whoisonline', false ); jQuery(document).on( 'heartbeat-tick.whoisonline', function( event, data, textStatus, jqXHR ) { if ( data.hasOwnProperty( 'whoisonline' ) ) { if ( whoisonline.online === false ) { //If just loaded, don't say anything... whoisonline.online = data.whoisonline; } whoisonline.onlinePrev = whoisonline.online || {}; for ( var id in whoisonline.onlinePrev ) { if ( ! whoisonline.online.hasOwnProperty( id ) ) { jQuery.noticeAdd( { text: whoisonline.onlinePrev[id] + " is now offline" } ); } } for ( var id in whoisonline.online ) { if ( ! whoisonline.onlinePrev.hasOwnProperty( id) ) { jQuery.noticeAdd( { text: whoisonline.online[id] + " is now online" } ); } } } wp.heartbeat.enqueue( 'who-is-online', 'whoisonline', false ); }); });
Loading Our Scripts and Styles
This plugin will make use of the jQuery Notice add-on by Tim Benniks â a lightweight growl-like notification plugin for jQuery. Simply download it, and extract to the root of your plugin (it should consist of only two files: jquery.notice.js and jquery.notice.css)
Now that the jQuery plugin has been added, the last piece of the puzzle is to enqueue the necessary scripts and styles. We want this plugin to function both on the front-end and admin side, so weâll use both the admin_enqueue_scripts and wp_enqueue_scripts hook, but we only want to load the script for logged in users.
function whoisonline_load_scripts() { /* Ony load scripts when you need to - in this case, everywhere if the user is logged in */ if ( is_user_logged_in() ) { wp_enqueue_script( 'whoisonline-jquery-notice', plugin_dir_url( __FILE__ ) . 'jquery.notice.js', array( 'jquery' ) ); wp_enqueue_style( 'whoisonline-jquery-notice', plugin_dir_url( __FILE__ ) . 'jquery.notice.css' ); wp_enqueue_script( 'whoisonline', plugin_dir_url( __FILE__ ) . 'who-is-online.js', array( 'heartbeat', 'whoisonline-jquery-notice' ) ); } } add_action( 'admin_enqueue_scripts', 'whoisonline_load_scripts' ); add_action( 'wp_enqueue_scripts', 'whoisonline_load_scripts' );
And thatâs the finished plugin.
You can see the code in full at this GitHub repository. Thereâs plenty of room for improvement here (for instance display a list of users, and when they were last active), but hopefully this relatively simple plugin has demonstrated how the Heartbeat API works.
Other parts in this series:The Heartbeat API: Changing the Pulse
Check out the original source here.











