Map Search Setup Non-WordPress

Embedding Map Search (SpatialMatch 2.0)

Our latest version of SpatialMatch dubbed version 2.0 is a responsive IDX map search product which can be installed through our WordPress line of products or manually installed on non-WordPress websites. If you're looking for instructions on how to use the new map search functionality with your WordPress website, please visit our SpatialMatch 2.0 setup page. To setup the map based IDX search on non-WordPress websites, please see the instructions below.

Non-WordPress Installation Guide

To install our map search plugin on your non-WordPress website you will need at least a basic understanding of HTML and Javascript. SpatialMatch 2.0 is a javascript application that can be embedded on any webpage of your real estate website. In the head of the document of the page you will need to initialize the application with the following code.

Code Breakdown

Page Setup

  1. Ensure that your HTML markup is standards compliant. You won't need much on the page besides the javascript used to initialize the app, an empty div (see below) and possibly a header and footer div for your site logo, main menu and copy right information.
  2. You'll want to make sure that you have an empty div on your page with a unique identifier (like an ID) that the application can use to embed itself on the page.
  3. Minimal CSS is recommended to ensure that the page is full window height and the div where you embed the app is also full width and height. We recommend the use of flexbox as it's browser support is now widespread and makes it easy to display the app full screen with a header and footer.

App Initialization

  1. In the footer of your page, load the SpatialMatch 2.0 bootstrap script
  2. The callback parameter in the above script line should match the function name you're going to create next.
  3. Create the callback function which will accept the application bootstrap (hj in the above code example). Inside of the callback function you can initialize the app with hj.init(); and pass in an object of options for the app.

Basic setup example: 

<!DOCTYPE html>
<html style="height: 100%">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <title>Map Search 2.0 - Home Junction</title>    
  </head>
  <body style="padding: 0; margin: 0; display: flex; flex-flow: column; height: 100%;">    
    <script type="text/javascript">
      function hj_search_load_callback(hj) {
        hj.init({          
          license: '---YOUR-HOME-JUNCTION-LICENSE-KEY---',          
          market: 'armls',  // <--- ENTER YOUR LICENSED MARKET HERE
          container: '#app',
          googleApiKey: '---YOUR-GOOGLE-MAPS-API-KEY---',        
          contactForm: {
            fields: {
              text: {
                text: "I'm interested in MLS# {id} at {address.deliveryLine}, {address.city} {address.zip}"
              }
            }
          }          
        });
      }
    </script>
    
    <div id="app"></div>
    
    <script async type="text/javascript" src="https://sm.homejunction.com/app/js/bootstrap.js?callback=hj_search_load_callback"></script>
  </body>
</html>

Versioning

The default URL https://sm.homejunction.com/app/js/bootstrap.js will always load the latest version of the application. In projects where you need to have full control over your updates, you can specify version you would like to load and update at your own discretion.

Full version manifest is available here: https://sm.homejunction.com/version_manifest.json

To load a specific version of the app you need to do 2 things:

1. Declare __PUBLIC_PATH__ global variable pointing to the versioned root URL (see version manifest): 

window.__PUBLIC_PATH__ = 'https://sm.homejunction.com/0.15/';

2. Use versioned URL to load the application: 

<script async type="text/javascript" src="https://sm.homejunction.com/0.15/app/js/bootstrap.js?callback=hj_search_load_callback"></script>

Application Options / Settings

When initializing the app you will need to pass options to set everything up for the app to function correctly. All options are outlined below but not all are required:

  • string: 'apiBaseURL' - Default: 'https://slipstream.homejunction.com/ws/'
  • string: 'license' - Home Junction license key
  • string: 'beforeDisclaimer' - html (deprecated, currently 'footer.beforeDisclaimer')
  • string: 'afterDisclaimer' - html (deprecated, currently 'footer.afterDisclaimer')
  • boolean: 'contactListingAgent' - Show listing agent on detail page
  • string: activeLayout - default active layout for mobile resolution, map or list, default: list
  • number: 'minZoom' - Min limit map zoom
  • string: 'cityGeoType' - Default: 'area/postal-city',
  • string: 'versionAPI' - API version
  • string: 'market' - Market id
  • string: 'container' - HTML selector for application rendering. Example #app
  • string: 'googleApiKey' - Google map API key
  • number: 'timeCorrection'
  • function: 'filtersCallback' - Filters sorting. Arguments (array filters, string listing_type), returned filters array
  • function: 'listingsTypeCallback' - Listing type sorting. Arguments (array ListingsType) returned ListingsType array
  • object: 'search' - Search default parameters.
  • string: pageDetailsPattern - Example: 'http://domain.com/{id}-{listingType}'
  • object: 'registration'
    • boolean: 'required' - Default false
    • number: 'listingViewCount' - Default -1,
  • object: authForm
    • object: fields:
      • name
        • required: false,
      • phone
        • required: false,
  • object: contactForm - or null for disabled contact form
    • string: selector - Css selector (optional); Example: '.custom-contact-form' if not empty app ignored fields and agent options
    • object: fields: - optional
      • name
        • required: false,
        • text: null
      • email
        • required: false,
        • text: null
      • text
        • required: false,
        • text: null
      • phone
        • required: false,
        • text: null
    • object: agent
    • name - optional
    • officeName - optional
    • officePhone - optional
    • photo - optional
  • object: footer - footer customization
    • string: copyright - html
    • string: beforeDisclaimer - html
    • string: afterDisclaimer - html
    • object: marketDisclaimer
    • object: copyright
      • string: before - html
      • string: after - html
    • object: disclaimer
      • string: before - html
      • string: after - html
    • object: eula
      • string: before - html
      • string: after - html
    • object: dmca
      • string: before - html
      • string: after - html
  • object: menu - optional (customer menu)
    • object: vertical
      • string: logo - optional (logo)
      • string: before - optional (html code before menu)
      • string: after - optional (html code after menu)
    • object: horizontal
      • string: logo - optional (logo)
      • string: before - optional (html code before menu)
      • string: after - optional (html code after menu)
    • array: items: - (menu items)
      • caption - item text
        • required: require,
      • href - optional
        • required: false,
        • string: null
      • children - optional (children items)
        • required: false,
        • array: []
      • icon - optional (item icon)
        • required: false,
        • string: null
  • object: palette - optional (color palette)
    • color: object
    • string: primary - optional (hex color)
    • string: secondary - optional (hex, rrggbbaa, rgb(a), hsl(a) or keyword color)
    • string: hover - optional (hex, rrggbbaa, rgb(a), hsl(a) or keyword color)
    • string: markerActive - optional (hex, rrggbbaa, rgb(a), hsl(a) or keyword color)
    • string: markerOther - optional (hex, rrggbbaa, rgb(a), hsl(a) or keyword color)
    • string: menu - optional (hex, rrggbbaa, rgb(a), hsl(a) or keyword color)

Handling Contact Form Submissions

When setting up your Spatial Match 2.0 application embed on your site, you will need to keep in mind that form submissions won't work out of the box. You will need to setup something for form submissions to be sent to an email service or another app for data collection. There are many services which can help with this process. One such service is Zapier which can accept the form submission and route it to many other services automatically. Below is an example of the javascript necessary to make this happen.

Example: contact form submission handler via Zapier 

hj.on('submit.contact_form', function(formData, listingObject)
{
    // Zapier web hook URL to send emails
    var zapierWebHook = '--ZAPIER-WEBHOOK-URL--',

    // Display thank you flash message upon successful form submission
    thankYouFlashMessage = function()
    {
        hj.notification.Add({
          title: "Thanks for contacting us!",
          msg: "We'll get back to you shortly.",
          position: "toast-bottom-right",
          timeout: 3000
        });
    },
    requestHeaders = {"Content-type" : 'application/x-www-form-urlencoded; charset=UTF-8'};

    // Post submitted web form data to Zapier
    ajaxPost(zapierWebHook, formData, thankYouFlashMessage, requestHeaders);
});

var ajaxPost = function(url, params, callback, headers)
{
    var http = new XMLHttpRequest();

    http.open("POST", url, true);

    if (typeof headers === 'object')
    {
        for(var i in headers)
        {
            if ((typeof i === 'string') && (typeof headers[i] === 'string'))
            {
                http.setRequestHeader(i, headers[i]);
            }
        }
    }
    else
    {
        http.setRequestHeader("Content-type", "application/json");
    }

    http.onreadystatechange = function()
    {
        if (http.readyState == 4 && http.status == 200)
        {
            if (typeof callback == "function")
            {
                callback(JSON.parse(http.responseText));
            }
        }
    };

    http.send(JSON.stringify(params));
};

The example above can be easily adopted to pass form submission data to any other underlying server side application (lets if you're embedding this app into a PHP website).

Events

The application comes with a set of supported events that you can use to provide more integration with other systems and/or your frontend. The events are listed below. Listen events  hj.on('event_name', callback)

  • ready - application ready
  • search.success - search success
  • listing.removed - user removed listings from saved/favorites
  • listing.saved - user saved listing to favorites
  • listing.viewed - user viewed listing details page
hj.on('search.success', function(response) {
    //TODO
})

Search Always

hj.on('search.always', function(response) {
    //TODO
}

On Search Failure

hj.on('search.fail', function(response) {
    //TODO
})

On Listing Type Change

hj.on('listing_type.change', function(listingsTypeName) {
    //TODO
})

On Map Viewport Change

hj.on('viewport.change', function(viewport) {
    //TODO
})

On User Login

hj.on('user.logged', function(user) {
    //TODO
})

On User Registration

hj.on('user.registration', function(user) {
    //TODO
})

On Contact Form Submission

hj.on('submit.contact_form', function(formData, listing) {
    //TODO
})

Notification

object hj.notification

The application utilizes notifications component that can be used via public API to display flash messages upon certain events.

For example, you can display a custom  Thank You! message upon contact form submission: 

hj.on('submit.contact_form', function(formData, listing)
{
    hj.notification.Add({
      title: "Thanks for contacting us!",
      msg: "We'll get back to you shortly.",
      position: "toast-bottom-right",
      timeout: 3000
    });
});

Notification Methods

Add(options)

Notification Options
javascript
{
    title: "Toast Title",
    msg: "Toast Msg", 
    position: Toast position string can be  'toast-top-right', 'toast-bottom-right', 'toast-bottom-left', 'toast-top-left', 'toast-top-full-width', 'toast-bottom-full-width', 'toast-top-center', 'toast-bottom-center' ; default toast-top-right
    type: Toast type can be : info,warning,error,success ; default success
    timeout: Toast Timeout for auto close can be integer ; default 5000
    closeOnHover: On mouse over stop timeout can be boolean; default true
    clickClose: On click toast close can be boolean; default false
    onCreated: On created toast event can be function
    onClicked: On clicked toast event can be function
    onClosed: On closed toast event can be function
    onMouseOver: On mouse over toast event can be function
    onMouseOut: On mouse over toast event can be function
}

Configuring Header, Menu & Footer

Custom Page Template (Header & Footer)

Still need help? Contact Us Contact Us