Introduction

MetaLocator provides a built-in mechanism for passing UI events from the embedded locator (iframe) to your website. This allows you to trigger custom functionality - such as analytics tracking, UI updates, or integrations - based on user activity inside MetaLocator.

Overview

When users interact with MetaLocator (e.g., performing a search, clicking a result, or submitting a form), MetaLocator can be configured to send a message to the host page using a standard event:

ml-iframe-message
​

Your website can listen for this event and respond with custom logic.

Sending Events from MetaLocator

Inside MetaLocator, events are sent to the parent page using:

sendParentIFRAMEMessage('ml-iframe-message', payload);

Payload Flexibility

The payload can be any value or object. There is no required structure.

For example:

sendParentIFRAMEMessage('ml-iframe-message', {  
    eventName: 'location_click',  
    dataLayerTuple: {  
        event: 'location_click',  
        locationId: 123  
    }  
});

or
​

sendParentIFRAMEMessage('ml-iframe-message', 'simple-string');

or
​

sendParentIFRAMEMessage('ml-iframe-message', {  
    action: 'search',  
    query: 'Miami',  
    resultsCount: 12  
});

As shown above, there are no requirements for the message's object composition.

This can be integrated directly into a Field Template as shown below:
​

<a href="javascript:void(0);" onclick="sendParentIFRAMEMessage('ml-iframe-message', {messageName: 'ml-test', messageValue: 'i-am-a-custom-value',amount:30.99});">Click here</a>

This can also be called using custom JavaScript in Advanced > Custom Head Tag as follows:
​

<script>  
// send an event to the host page with custom data attributes   
jqLocator(document).ready(function(){

// for any link with an attribute called "data-custom-attribute" send all of its custom data attributes to the host page.  
    jqLocator('a[data-custom-attribute]').on('click',function(e){  
       sendParentIFRAMEMessage('ml-iframe-message', jqLocator(this).data());     
    });  
});

</script>

In the above case, the results card markup can include custom data attributes by modifying the Field Template to include them as shown below:

<a href="javascript:void(0);" data-custom-message-name="clicked dealer {{name}} with id: {{id}}" data-custom-message-name="{{favoritecolor}}" data-custom-message-amount="{{anothercustomfield}}">Click here</a>

Listening for Events on Your Website

To respond to MetaLocator events, add an event listener on your page:

document.body.addEventListener('ml-iframe-message', function (e) {  
    const payload = e.detail;

console.log('MetaLocator Event:', payload);

// Example: Custom logic  
    if (payload?.eventName === 'location_click') {  
        // Your custom behavior here  
    }  
});

Troubleshooting

This integration strategy requires the client host page use the standard, supported MetaLocator Installation methods.

Updated on: 12/11/2026