SDK for PHP - Widget Implementation Reference

This comprehensive reference guide provides code examples and implementation details for all Buying Buddy widgets when using the SDK for PHP.

Prerequisites

Before implementing widgets, ensure you have:

Completed SDK Overview & Setup
Configured your JavaScript plugin with seo : "true"
Added the SDK to your pages

Widget Implementation Pattern

All widgets follow this consistent pattern when using the SDK:

1. PHP Widget Setup

<?php
$widgetParams = array( 
    "filter" => "your_filter_here",
    // Additional parameters as needed
);
$widgetObj = $mbbObj->getWidget("WidgetName", $widgetParams);
?>

2. HTML Widget Display

<bb-widget data-type='WidgetName' data-filter='your_filter_here'>
    <?php echo $widgetObj->html?>
</bb-widget>

Important: Display widgets should always include a filter in the DIV, even if you're filtering in PHP. This ensures proper widget functionality.

Display Widgets

Featured List Widget

Displays property listings in a list format with SEO-friendly links.

<?php
$widgetParams = array( 
    "filter" => "mls_id:ca64+city:DENVER,AURORA",
    "limit" => 20,           // Default: 30
    "order" => "create_dt desc", // Default: create_dt desc
    "page" => 1              // Default: page 1
);
$listObj = $mbbObj->getWidget("MBBv3_FeaturedList", $widgetParams);
?>

<bb-widget data-type='FeaturedList' data-filter='mls_id:ca64+city:DENVER,AURORA'>
    <?php echo $listObj->html?>
</bb-widget>

Featured Gallery Widget

Displays property listings in a gallery/grid format with SEO-friendly links.

<?php
$widgetParams = array( 
    "filter" => "mls_id:ca64+price_min:500000+price_max:555000+city:DENVER",
    "limit" => 20,           // Default: 30
    "order" => "price desc", // Default: create_dt desc
    "page" => 1              // Default: page 1
);
$galleryObj = $mbbObj->getWidget("MBBv3_FeaturedGallery", $widgetParams);
?>

<bb-widget data-type="FeaturedGallery" filter="mls_id:ca64+price_min:500000+price_max:555000+city:DENVER">
    <?php echo $galleryObj->html?>
</bb-widget>

Interactive Widgets

Interactive Map Widget

Displays properties on an interactive map.

<?php
$widgetParams = array( 
    "filter" => "mls_id:ca64+price_min:500000+price_max:555000"
);
$mapObj = $mbbObj->getWidget("MBBv3_InteractiveMap", $widgetParams);
?>

<div id="MBBv3_InteractiveMap" filter="mls_id:ca64+price_min:500000+price_max:555000" style="height:600px;">
    <?php echo $mapObj->html?>
</div>

Search Results Widget

Displays search results with filtering capabilities.

<?php
$resultsObj = $mbbObj->getWidget("MBBv3_ListingResults", array("filter" => "login-panel:false"));
?>

<div id="MBBv3_ListingResults" filter="login-panel:false">
    <?php echo $resultsObj->html?>
</div>

Custom Search Links

For pages with URL parameters:

<?php
$resultsObj = $mbbObj->getWidget("MBBv3_ListingResults", array("filter" => $_GET["filter"]));
?>
<div id="MBBv3_ListingResults" filter="<?php echo $_GET["filter"]; ?>">
    <?php echo $resultsObj->html?>
</div>

Property Details Widget

Displays detailed information for a single property with SEO optimization.

<?php
// Using SEO-friendly URL (recommended)
$propertyObj = $mbbObj->getWidget("MBBv3_SearchDetails", array("property_id" => $mbbObj->getPropertyIdFromURL()));

// Or using query parameter
// $propertyObj = $mbbObj->getWidget("MBBv3_SearchDetails", array("property_id" => $_GET["property_id"]));
?>

<div id="MBBv3_SearchDetails">
    <?php echo $propertyObj->html?>
</div>

SEO Variables for Property Details

<head>
    <title><?php echo $propertyObj->title?></title>
    <meta name="description" content="<?php echo $propertyObj->meta_description?>">
    <meta name="keywords" content="<?php echo $propertyObj->meta_keywords?>">
    <?php echo $propertyObj->og_tags?>
</head>
<body>
    <h1><?php echo $propertyObj->h1?></h1>
    <div id="MBBv3_SearchDetails">
        <?php echo $propertyObj->html?>
    </div>
</body>

Form Widgets

<?php
$searchObj = $mbbObj->getWidget("MBBv3_SearchForm", array("filter" => "layout:horizontal"));
?>

<div id="MBBv3_SearchForm" filter="layout:horizontal">
    <?php echo $searchObj->html?>
</div>

<?php
$loginObj = $mbbObj->getWidget("MBBv3_LoginPanel", array("filter" => "layout:horizontal"));
?>

<div id="MBBv3_LoginPanel" filter="layout:horizontal">
    <?php echo $loginObj->html?>
</div>

Utility Widgets

Disclaimer Widget

<?php
$disclaimerObj = $mbbObj->getWidget("MBBv3_Disclaimer", array());
?>

<div id="MBBv3_Disclaimer">
    <?php echo $disclaimerObj->html?>
</div>

Form Field Definitions

When building custom forms, use these field definitions:

Field Properties

field_label: Display label for the form field
field_nm: Field name for form/query building
field_type: Data type (Number fields support "_min" and "_max")
like: {true|false} - If true, queries use LIKE matching
allow_multiple: {true|false} - Accepts comma-separated values
look_field: Uses lookup codes for values
_not suffix: Excludes specified values (e.g., city_not=denver)

Special Fields

shapesearch: Comma-separated lat/long coordinates
create_dt: Number of days on market
price_drop: Days since price dropped
listing_num: When specified, ignores all other fields

Examples

// Price range query
"price_min:500000+price_max:600000"

// Multiple cities
"city:DENVER,AURORA,LAKEWOOD"

// Exclude specific city
"city_not:DENVER"

// New listings (last 10 days)
"create_dt:10"

// Properties with features
"property_features:ac,deck"

Additional API Calls

Property Data Queries

Query by Array

<?php
$queryParams = array( 
    "mls_id" => "ca64",      // REQUIRED
    "price_min" => 500000,
    "price_max" => 555000,
    "city" => "DENVER,AURORA",
    "page" => 1,
    "sort" => "price-desc"
);
$resultArray = $mbbObj->getListingDataFromArray($queryParams);
?>

Query by Filter String

<?php
$filter = "mls_id:ca64+price_min:500000+price_max:555000+city:DENVER+sort:price+page:1";
$resultsFilter = $mbbObj->getListingDataFromFilter($filter);
?>

Single Property Information

<?php
$propertyInfo = $mbbObj->getProperty("ca64_110010319");
// Returns array with: price, property_type, city, etc.
?>

Form Field Data

<?php
// Get available form fields for MLS
$formFields = $mbbObj->getFormFieldList("ca64");

// Get all lookup fields
$allLookups = $mbbObj->getAllLookupFields("ca64");

// Get specific field lookup values
$fieldLookups = $mbbObj->getFieldLookupValues("ca64", "property_type");
// Returns: res => Residential, lnd => Land, etc.
?>

SEO-Friendly URL Implementation

City-Based Pages

Create multiple city pages with a single PHP file:

<?php
// Extract city from URL (e.g., /city/denver)
$city = "denver"; // Parse from $_SERVER['REQUEST_URI']
$filter = "mls_id:ca64+listing_status:active+city:{$city}+limit:10+order:create_dt desc";
$resultsObj = $mbbObj->getWidget("MBBv3_FeaturedGallery", array("filter" => $filter));
?>
<div id="MBBv3_FeaturedGallery" filter="<?php echo $filter; ?>">
    <?php echo $resultsObj->html?>
</div>

HTACCESS Example

RewriteEngine on
RewriteRule ^city/(.*)$ city.php?city=$1 [L]
RewriteRule ^property.*$ property.php [L]

Error Handling

Common Issues

SQL Error on Details Page: Normal when viewing details widget without a property ID
Domain Not Authorized: Check that your domain is properly configured in Buying Buddy account
Widget Not Displaying: Verify seo : "true" is set in JavaScript plugin

Best Practices

Always include filters in HTML divs for display widgets
Use consistent parameter naming across widgets
Implement proper error handling for API calls
Cache API responses when possible for better performance
Use SEO-friendly URLs for better search engine optimization

Next Steps

SEO Implementation: See our SEO Implementation Guide
Office Features: Implement OfficeRo s ter with SDK
Advanced Customization: Contact support for custom implementations

Updated on July 28, 2025

Tagged: PHP sdk

Was this article helpful?

Yes No