Bring WordPress to Life with the Heartbeat API

A walkthrough of the Heartbeat API available in WordPress 3.6+, which allows developers to quickly add live-updates to WordPress’ panel or front-end using native AJAX APIs.

We’ll go through core’s current uses of HeartBeat, how it works, and how to use it in your own plugins to add dynamically updating content within the WordPress admin or front-end.

Presented at WordCamp Phoenix 2014 by Mike Schroder
Sample Code at: https://gist.github.com/getsource/6254495

Transcript

1. Bring WordPress to Life
   with the Heartbeat API
   WordCamp Phoenix 2014 Mike Schroder (DH-Shredder) @GetSource - http://www.getsource.net
2. Who Am I? • Mike Schroder, a.k.a DH-Shredder, a.k.a. @GetSource • Third Culture Kid, enjoy Coffee & Sailing • WordPress Core Rep and WP-CLI Contributor • Happy DreamHost Employee
3. WAT is Heartbeat?
   
4. Realtime* Bidirectional communication via AJAX.
   
5. Heartbeat is Polling.
   
6. 15-30 seconds by default. 120 seconds when inactive.
7. Suspend after 20 minutes inactive.
9. Born from need for 3.6+
   
14. How does it work?
    
15. EXPERIMENTAL WARNING!
    
16. JS Trigger Flow
    ! ! -> heartbeat-send
    -> heartbeat-tick
    -/> heartbeat-error
    ! ! (wp-includes/js/heartbeat.js)
    
17. PHP Filter/Action Flow
    ! ! -> heartbeat_received
    -> heartbeat_send
    -> heartbeat_tick (action)
    ! ! (wp-admin/includes/ajax-actions.php)
18. if ( ! empty( $_POST['data'] ) ) { $data = (array) $_POST['data']; $response = apply_filters( 'heartbeat_received', $response, $data, $screen_id ); } $response = apply_filters( 'heartbeat_send', $response, $screen_id ); ! // Allow the transport to be replaced with long-polling easily do_action( 'heartbeat_tick', $response, $screen_id ); // Send the current time according to the server $response['server_time'] = time(); wp_send_json($response); Direct from core.
19. Set Baseline Tick Rate
    ! ! Filter: heartbeat_settings
    $settings['interval']=<seconds>
    ! !
20. Temporarily Change
    Tick Rate
    ! wp.heartbeat.interval(<enum>)
    ! Values (change lasts for 2.5 minutes):
    5, 15, 30, or 60 (Seconds)
    
21. Now automatically runs on admin, even without data[]
    
22. Check User Status
    ! wp.heartbeat.hasFocus()
    
23. Check Connection Status
    ! wp.heartbeat.hasConnectionError()
    ! ! Related Triggers:
    heartbeat-connection-lost
    heartbeat-connection-restored
    
24. How can I use it?
    
25. <?php /* Plugin Name: Heartbeat Comment Update Description: Updates Comment Count on Dashboard with Heartbeat. Author: Andrew Ozz, Mike Schroder Version: 0.2 Author URI: http://www.getsource.net */ ! add_filter( 'heartbeat_received', 'wc_heartbeat_comment_count', 10, 3 ); function wc_heartbeat_comment_count( $response, $data, $screen_id ) { ! // ... ( Read Data, Edit Response )
    ! // Pass along filtered response. return $response;
    } Listen, then Return.
26. // Check if we are on the right screen and data is requested. if ( $screen_id == 'dashboard' && isset( $data['wc-comment-heartbeat'] ) ) { ! // Grab our data $num_comments = wp_count_comments(); ! // Add data in an unique array key -- prefix! $response['wc-comment-count'] = array( 'comment-count' => number_format_i18n($num_comments->total_comments), 'pending-count' => number_format_i18n($num_comments->moderated), 'comment-mod-count' => number_format_i18n($num_comments->moderated), 'spam-count' => number_format_i18n($num_comments->spam), 'trash-count' => number_format_i18n($num_comments->trash), ); }
    ! // Pass along filtered response return $response;
    } Retrieve Data
27. add_action( 'admin_enqueue_scripts', 'wc_heartbeat_comment_script_enqueue' ); function wc_heartbeat_comment_script_enqueue( $hook_suffix ) {
    ! // Load this script only in the dashboard. if ( 'index.php' != $hook_suffix ) return; ! // Make sure the JS part of the Heartbeat API is loaded. wp_enqueue_script( 'heartbeat' ); ! // Output the JavaScript we need. add_action( 'admin_print_footer_scripts', 'wc_heartbeat_comment_js', 20 );
    ! } Enqueue Script
28. function wc_heartbeat_comment_js() {
    ?> <script> jQuery(document).ready( function($) { ! // Request comment count, using prefixed custom event. $(document).on( 'heartbeat-send.wp-comment-count',
    function( e, data ) { ! // For one-time send, use:
    // wp.heartbeat.enqueue( 'item', 'value' ); data['wc-comment-heartbeat'] = 'count';
    ! // Speed up heartbeat for faster results. // Only has to be called every 2.5 minutes. window.wp.heartbeat.interval(15); ! // ... Request Data
29. // ...
    // Listen for the tick custom event. }).on( 'heartbeat-tick.wc-comment-count', function( e, data ) {
    ! // Double-check we have the data we're listening for if ( ! data['wc-comment-count'] ) return; ! // Replace all of the comment counts $.each( data['wc-comment-count'], function( key, value ) { var replaced = $( '.' + key ).html().replace(/(.*)\d+(.*)/g, "$1" + value + "$2"); $( '.' + key ).html( replaced ); }); ! // Initial connection to cement our new interval timing window.wp.heartbeat.connectNow();
    }); }); </script> <?php } Receive Data
30. This is just a start.
    
31. Resources! • core.trac.wordpress.org/browser/tags/3.8/src/wp-includes/js/heartbeat.js • gist.github.com/getsource/6254495 • pippinsplugins.com/using-the-wordpress-heartbeat-api/ • wp.tutsplus.com/tutorials/creative-coding/the-heartbeat-api-getting- started/ Mike Schroder (DH-Shredder) @GetSource - http://www.getsource.net