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.













