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.