How to build custom Genesis child themes extensions utilizing modern Heartbeat API schemas

Leveraging WordPress Heartbeat API for Real-time Genesis Child Theme Extensions

The WordPress Heartbeat API, while often associated with autosave and post locking, offers a robust mechanism for real-time communication between the browser and the server. This can be powerfully leveraged to build dynamic, responsive features within Genesis child themes, extending their functionality beyond static content. This guide focuses on constructing custom Heartbeat API extensions, demonstrating how to send and receive data to enhance user experience and administrative workflows.

Understanding the Heartbeat API Flow

The Heartbeat API operates on a recurring AJAX request initiated by WordPress in the browser. This request, typically sent every 15-60 seconds (configurable), allows plugins and themes to hook into the process, sending data to the server and receiving instructions or data back. The core of this interaction is the `heartbeat_send` filter, which allows us to modify the data payload before it’s sent and process incoming data.

Registering a Custom Heartbeat Endpoint

To implement custom Heartbeat functionality, we first need to register a callback function that will handle the incoming data and prepare the outgoing data. This is achieved using the `heartbeat_settings` filter. This filter allows us to define the frequency of Heartbeat requests and, more importantly, to specify our custom data handler.

Place the following PHP code within your Genesis child theme’s `functions.php` file or a custom plugin:

/**
 * Register custom Heartbeat settings.
 *
 * @param array $settings Heartbeat settings.
 * @return array Modified Heartbeat settings.
 */
function my_genesis_child_heartbeat_settings( $settings ) {
    // Set the interval to 30 seconds. Default is 15-60 seconds.
    $settings['interval'] = 30;
    return $settings;
}
add_filter( 'heartbeat_settings', 'my_genesis_child_heartbeat_settings' );

/**
 * Handle Heartbeat data.
 *
 * @param array $response Heartbeat response data.
 * @param array $data Incoming data from the client.
 * @return array Modified Heartbeat response data.
 */
function my_genesis_child_heartbeat_data( $response, $data ) {
    // Check if our custom data is present.
    if ( isset( $data['my_custom_action'] ) ) {
        // Process the custom action.
        $action_result = my_genesis_child_process_custom_action( $data['my_custom_action'] );

        // Add our custom data to the response.
        $response['my_custom_response'] = $action_result;
    }

    // You can also send data back to the client without a specific client-initiated action.
    // For example, to update a status periodically.
    $response['current_server_time'] = current_time( 'mysql' );

    return $response;
}
add_filter( 'heartbeat_send', 'my_genesis_child_heartbeat_data', 10, 2 );

/**
 * A placeholder function to simulate processing custom data.
 *
 * @param mixed $input The data received from the client.
 * @return string The result of the processing.
 */
function my_genesis_child_process_custom_action( $input ) {
    // In a real-world scenario, this would involve database operations,
    // external API calls, or complex logic.
    return 'Processed: ' . sanitize_text_field( $input );
}

In this example:

• my_genesis_child_heartbeat_settings: This function modifies the default Heartbeat settings, setting the request interval to 30 seconds.
• my_genesis_child_heartbeat_data: This is our primary handler. It receives the incoming data payload ($data) and prepares the response payload ($response).
• We check for a specific key, 'my_custom_action', in the incoming data. If present, we call a hypothetical processing function.
• The result of the processing is added to the $response array under the key 'my_custom_response'.
• We also demonstrate sending back server-generated data ('current_server_time') with every Heartbeat request.
• my_genesis_child_process_custom_action: A placeholder for your actual logic.

Sending Data from the Client-Side (JavaScript)

To trigger our custom Heartbeat logic, we need to send data from the client-side. WordPress provides a JavaScript API for interacting with the Heartbeat. We’ll enqueue a custom JavaScript file and use the wp.heartbeat.connect() method.

First, enqueue your JavaScript file in your Genesis child theme’s functions.php:

/**
 * Enqueue custom Heartbeat JavaScript.
 */
function my_genesis_child_enqueue_heartbeat_script() {
    wp_enqueue_script(
        'my-genesis-child-heartbeat',
        get_stylesheet_directory_uri() . '/js/heartbeat-custom.js',
        array( 'jquery', 'heartbeat' ), // Dependencies: jQuery and WordPress Heartbeat script
        filemtime( get_stylesheet_directory() . '/js/heartbeat-custom.js' ),
        true // Load in footer
    );
}
add_action( 'admin_enqueue_scripts', 'my_genesis_child_enqueue_heartbeat_script' );
add_action( 'wp_enqueue_scripts', 'my_genesis_child_enqueue_heartbeat_script' ); // For front-end

Next, create the JavaScript file (e.g., /js/heartbeat-custom.js) within your child theme directory:

jQuery(document).ready(function($) {

    // Ensure the heartbeat is enabled.
    if ( wp.heartbeat ) {

        // Send custom data when Heartbeat is about to send.
        $(document).on('heartbeat-send', function(e, data) {
            // Add our custom data to the payload.
            data.my_custom_action = 'perform_update'; // This key matches our PHP handler.
            console.log('Heartbeat sending custom data:', data);
        });

        // Receive and process data from Heartbeat.
        $(document).on('heartbeat-tick', function(e, data) {
            console.log('Heartbeat tick received data:', data);

            // Check for our custom response.
            if ( data.my_custom_response ) {
                console.log('Custom response received:', data.my_custom_response);
                // Example: Update a status indicator on the page.
                // $('#my-status-indicator').text(data.my_custom_response);
            }

            // Check for server-generated data.
            if ( data.current_server_time ) {
                console.log('Server time:', data.current_server_time);
                // Example: Update a "last updated" timestamp.
                // $('#last-updated-time').text(data.current_server_time);
            }
        });

        // Handle Heartbeat errors.
        $(document).on('heartbeat-error', function(e, error) {
            console.error('Heartbeat error:', error);
        });

        // You can also manually trigger a Heartbeat connection if needed,
        // but it's usually handled automatically.
        // wp.heartbeat.connect();
    }
});

Explanation of the JavaScript:

• $(document).on('heartbeat-send', ...)`: This event fires just before the Heartbeat AJAX request is sent. We add our custom data (my_custom_action: 'perform_update') to the data object.
• $(document).on('heartbeat-tick', ...)`: This event fires when a response is received from the server. We can access the data sent back by the server (e.g., data.my_custom_response, data.current_server_time) and update the UI accordingly.
• $(document).on('heartbeat-error', ...)`: For handling any network or server-side errors during the Heartbeat communication.

/**
 * Conditionally disable Heartbeat on the front-end for non-logged-in users.
 *
 * @param array $settings Heartbeat settings.
 * @return array Modified Heartbeat settings.
 */
function my_genesis_child_conditional_heartbeat_settings( $settings ) {
    // Disable Heartbeat on the front-end if user is not logged in.
    if ( ! is_user_logged_in() && ! is_admin() ) {
        $settings['interval'] = false; // Setting interval to false effectively disables it.
    }
    return $settings;
}
add_filter( 'heartbeat_settings', 'my_genesis_child_conditional_heartbeat_settings' );

/**
 * Handle Heartbeat data, filtering based on admin screen.
 *
 * @param array $response Heartbeat response data.
 * @param array $data Incoming data from the client.
 * @return array Modified Heartbeat response data.
 */
function my_genesis_child_conditional_heartbeat_data( $response, $data ) {
    // Only process custom actions on post edit screens.
    if ( isset( $data['my_custom_action'] ) && 'post' === get_current_screen()->base ) {
        $response['my_custom_response'] = my_genesis_child_process_custom_action( $data['my_custom_action'] );
    }

    // Add server time only on dashboard.
    if ( 'dashboard' === get_current_screen()->id ) {
        $response['current_server_time'] = current_time( 'mysql' );
    }

    return $response;
}
add_filter( 'heartbeat_send', 'my_genesis_child_conditional_heartbeat_data', 10, 2 );