> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.metalocator.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Triggering host page JavaScript events

# 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](https://support.metalocator.com/en/articles/3817982-field-templates) 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](https://support.metalocator.com/en/articles/8053557-installation-methods).