Widgets: The Complete Developer Reference

Havenlytics widgets are classic WP_Widget classes that render property-related content in the single-property sidebar — featured listings, the assigned agent, a mortgage calculator, related properties, and an agent listings carousel. This reference documents every widget in Havenlytics 3.3.1, its class and id_base, its options, and exactly what it renders, plus how widgets are registered and how to place one into the plugin’s sidebar programmatically.

Note: Havenlytics ships no Gutenberg blocks. There is no register_block_type() call and no src/blocks/ directory anywhere in the plugin. Every widget documented here is a classic WP_Widget. If you need block-editor content, embed a Havenlytics shortcode in a Custom HTML or shortcode block.

How widgets are registered

Widget registration is owned by Register_Widgets (includes/Database/Custom_Widgets/Register_Widgets.php), which is instantiated by the Database service (includes/Database/Database.php:157). On construction it boots WidgetEditorCompat::boot() and hooks the WordPress widgets_init action to its register_widgets() method.

register_widgets() does two things:

• Registers a dedicated sidebar, hvnly_single_property_sidebar_widgets_area — labelled Havenlytics – Single Property Sidebar — which is where every Havenlytics widget is designed to live.
• Registers each widget class with WordPress via register_widget().

All Havenlytics widgets share two traits: the widget wrapper classname is prefixed hvnly-property-single__widget, and each declares customize_selective_refresh => true so the Customizer can refresh a single widget without reloading the whole preview.

Important: Every Havenlytics widget renders output only on single-property views — its widget() method short-circuits unless is_singular( 'hvnly_property' ) is true. Placing one of these widgets in a generic sidebar that shows on other page types will produce no output there.

The block inserter (legacy widgets screen) groups these widgets under a category with slug havenlytics and title HAVENLYTICS.

The widgets

Featured Properties

Class: Hvnly_Featured_Properties_Widget · id_base: hvnly_featured_properties · file under includes/Database/Custom_Widgets/All_Widgets/.

Renders a grid of properties flagged featured (meta key _hvnly_property_featured = 1).

Property Agent

Class: Hvnly_Property_Agent_Widget · id_base: hvnly_property_agent.

Renders the agent(s) assigned to the current property plus an inquiry form, delegated to PropertyAgentWidgetRenderer.

Mortgage Calculator

Class: Hvnly_Mortgage_Calculator_Widget · id_base: hvnly_mortgage_calculator.

Renders an interactive mortgage calculator seeded with the current property’s price, resolved through Hvnly_Price_Resolver.

Related Properties

Class: Hvnly_Related_Properties_Widget · id_base: hvnly_related_properties.

Renders properties related to the current one by location and/or type.

Agent Listings Carousel

Class: Hvnly_Agent_Listings_Carousel_Widget · id_base: hvnly_agent_listings_carousel.

Renders a carousel of a given agent’s listings, delegated to AgentListingsCarouselWidgetRenderer.

Legacy widget shim

Hvnly_Legacy_Preserved_Widget is a compatibility shim. Its static register_base( $id_base, $title ) method preserves any hvnly_* widget base that appears in a site’s sidebars_widgets option but is no longer registered as a real widget class — this stops WordPress from silently dropping saved widget instances after a plugin update. It special-cases the hvnly_agent base. Two helpers support the widget layer: WidgetInstanceHelpers.php and WidgetEditorCompat.php.

Note: You should not register widgets against the legacy shim yourself. It exists to keep old saved instances alive, not as an extension point for new widgets — extend WP_Widget directly instead.

Registering a widget into the Havenlytics sidebar

You can build your own WP_Widget and register it on widgets_init, then place it in the plugin’s single-property sidebar hvnly_single_property_sidebar_widgets_area. Follow the same single-property guard the built-in widgets use so it only renders where it makes sense.

<?php
/**
 * A custom Havenlytics-compatible sidebar widget.
 * Renders only on single hvnly_property views, matching the
 * behaviour of the built-in Havenlytics widgets.
 */
class My_Property_Note_Widget extends WP_Widget {

    public function __construct() {
        parent::__construct(
            'my_property_note',            // id_base
            'My Property Note',            // name
            array(
                'classname'                   => 'hvnly-property-single__widget my-property-note',
                'description'                 => 'A note shown on single property pages.',
                'customize_selective_refresh' => true,
            )
        );
    }

    public function widget( $args, $instance ) {
        // Match Havenlytics: only render on single property views.
        if ( ! is_singular( 'hvnly_property' ) ) {
            return;
        }

        echo $args['before_widget'];
        if ( ! empty( $instance['title'] ) ) {
            echo $args['before_title'] . esc_html( $instance['title'] ) . $args['after_title'];
        }
        echo '<p>' . esc_html( get_the_title() ) . '</p>';
        echo $args['after_widget'];
    }

    public function form( $instance ) {
        $title = isset( $instance['title'] ) ? $instance['title'] : '';
        printf(
            '<p><label>Title <input class="widefat" name="%s" value="%s" /></label></p>',
            esc_attr( $this->get_field_name( 'title' ) ),
            esc_attr( $title )
        );
    }

    public function update( $new_instance, $old_instance ) {
        $instance          = array();
        $instance['title'] = sanitize_text_field( $new_instance['title'] );
        return $instance;
    }
}

// Register the widget with WordPress.
add_action( 'widgets_init', function () {
    register_widget( 'My_Property_Note_Widget' );
} );

Once registered, drag the widget into the Havenlytics – Single Property Sidebar area on the Widgets screen, or assign it programmatically to hvnly_single_property_sidebar_widgets_area.

Best practices

• Always guard custom sidebar widgets with is_singular( 'hvnly_property' ) if they depend on property context, exactly as the built-in widgets do.
• Prefix your widget wrapper class with hvnly-property-single__widget so it inherits Havenlytics sidebar styling.
• Set customize_selective_refresh => true to support live Customizer previews.
• Escape all output (esc_html, esc_attr, esc_url) and sanitize saved values in update().

Common mistakes

• Looking for Gutenberg blocks. There are none. Use shortcodes inside blocks for the block editor.
• Placing Havenlytics widgets in a global sidebar. They render only on single-property pages, so they will appear empty elsewhere.
• Extending Hvnly_Legacy_Preserved_Widget. It is a preservation shim, not an extension base — extend WP_Widget.
• Forgetting the widgets_init hook. register_widget() must run on widgets_init.