Locator app integration

This guide explains how to embed Mapviewer Locator applications in your website using HTML iframes.

Basic Embedding

The simplest way to embed a locator app is using an iframe pointing to the locator URL:

<iframe 
  class="fullBleed" 
  src="https://app.mapviewer.eu/nl/locator/<appname>" 
  width="100%" 
  height="600"
></iframe>

Replace <appname> with your actual locator application name.

Improved Responsive Embedding

For better mobile and responsive behavior, use CSS to maintain aspect ratio and prevent scroll issues:

Option 1: Aspect Ratio Container (Recommended)

<div class="locator-container" style="position: relative; width: 100%; padding-bottom: 75%;">
  <iframe 
    src="https://app.mapviewer.eu/nl/locator/<appname>" 
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    allowfullscreen
    loading="lazy"
  ></iframe>
</div>

The padding-bottom: 75% creates a 4:3 aspect ratio. Adjust based on your needs:

• 56.25% for 16:9
• 75% for 4:3
• 100% for 1:1 (square)

Option 2: CSS Grid Approach

<style>
  .locator-embed {
    width: 100%;
    aspect-ratio: 16/9;
    max-width: 1200px;
    margin: 0 auto;
  }
  .locator-embed iframe {
    width: 100%;
    height: 100%;
    border: none;
  }
</style>

<div class="locator-embed">
  <iframe 
    src="https://app.mapviewer.eu/nl/locator/<appname>" 
    allowfullscreen
    loading="lazy"
  ></iframe>
</div>

URL Parameters

Customize locator behavior through URL parameters:

Parameter	Type	Description	Example
center	coordinates	Initial map center (lng,lat)	center=4.9,52.37
zoom	number	Initial zoom level	zoom=14
filter	string	Pre-select filter type	filter=<TYPE>
lang	string	Language override	lang=en
theme	string	UI theme (light/dark)	theme=dark

Example with Parameters

<iframe 
  src="https://app.mapviewer.eu/nl/locator/<appname>?center=4.9,52.37&zoom=14&filter=<TYPE>"
  width="100%" 
  height="600"
  style="border: none;"
></iframe>

Best Practices

1. Always Use loading="lazy"

Improves page load performance:

<iframe loading="lazy" ...></iframe>

2. Set Explicit Dimensions

Always specify both width and height to prevent layout shifts.

3. Remove Default Border

<iframe style="border: none;" ...></iframe>

4. Enable Fullscreen

<iframe allowfullscreen ...></iframe>

5. Security

Add security attributes:

<iframe 
  src="..."
  sandbox="allow-same-origin allow-scripts allow-popups allow-forms"
  referrerpolicy="strict-origin-when-cross-origin"
></iframe>

Note: Test sandbox restrictions as they may block functionality.

Cross-Origin Communication

For advanced integration:

Parent to Iframe

const iframe = document.querySelector('iframe');
iframe.contentWindow.postMessage({
  type: 'locator:flyTo',
  payload: { lng: 4.9, lat: 52.37, zoom: 16 }
}, 'https://app.mapviewer.eu');

Iframe to Parent

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.mapviewer.eu') return;
  if (event.data.type === 'locator:featureSelected') {
    console.log('Feature selected:', event.data.payload);
  }
});

Message Types

Parent to Locator

Type	Payload	Description
locator:flyTo	{ lng: number, lat: number, zoom: number }	Fly to coordinates
locator:setFilter	{ filter: string }	Set active filter
locator:search	{ query: string }	Trigger search
locator:clearSelection	-	Clear selected feature

Locator to Parent

Type	Payload	Description
locator:featureSelected	{ feature: object }	A feature was selected
locator:boundsChanged	{ bounds: array, zoom: number }	Map viewport changed
locator:filterChanged	{ filter: string }	Active filter changed
locator:loaded	-	Locator app fully loaded

Complete Example

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <style>
    .locator-wrapper {
      position: relative;
      width: 100%;
      max-width: 1400px;
      margin: 2rem auto;
      border-radius: 12px;
      overflow: hidden;
      box-shadow: 0 4px 20px rgba(0,0,0,0.15);
    }
    .locator-wrapper .aspect-ratio {
      position: relative;
      width: 100%;
      padding-bottom: 65%;
    }
    .locator-wrapper iframe {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      border: none;
      background: #f5f5f5;
    }
  </style>
</head>
<body>
  <h1>Store Locator</h1>
  
  <div class="locator-wrapper">
    <div class="aspect-ratio">
      <iframe 
        src="https://app.mapviewer.eu/nl/locator/<appname>?center=4.9,52.37&zoom=14"
        allowfullscreen
        loading="lazy"
      ></iframe>
    </div>
  </div>
  
  <p><a href="https://app.mapviewer.eu/nl/locator/<appname>">Open in full screen</a></p>
  
  <script>
    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://app.mapviewer.eu') return;
      if (event.data.type === 'locator:featureSelected') {
        console.log('Selected:', event.data.payload);
      }
    });
  </script>
</body>
</html>

Troubleshooting

Iframe Not Loading

• Verify app name in URL
• Check third-party cookies
• Ensure domain is whitelisted

Iframe Appears Blank

• Check browser console
• Verify CORS headers
• Test with simpler iframe

Mobile Issues

• Test on actual devices
• Verify viewport meta tag
• Add -webkit-overflow-scrolling: touch for iOS

Communication Not Working

• Verify event.origin matches exactly
• Wait for iframe to load before sending messages
• Check for security errors

Customization

Theme

<iframe 
  src="https://app.mapviewer.eu/nl/locator/<appname>?theme=custom"
  style="--primary-color: #ff0000; --background: #ffffff;"
></iframe>

Language

<iframe 
  src="https://app.mapviewer.eu/nl/locator/<appname>?lang=en"
></iframe>

Supported: nl, en, de, fr

Performance

1. Lazy Loading: loading="lazy"
2. Preconnect: <link rel="preconnect" href="https://app.mapviewer.eu" />
3. DNS Prefetch: <link rel="dns-prefetch" href="https://app.mapviewer.eu" />

Accessibility

<iframe 
  src="..."
  title="Store Locator - Find our locations"
  aria-label="Interactive map showing store locations"
></iframe>

SEO

1. Add text link: <a href="https://app.mapviewer.eu/nl/locator/<appname>">View Locator</a>
2. Include structured data:

   {
     "@context": "https://schema.org",
     "@type": "WebApplication",
     "name": "Store Locator",
     "url": "https://yourwebsite.com/locations",
     "applicationCategory": "MapsApplication"
   }

Browser Support

Browser	Support
Chrome	Full
Firefox	Full
Safari	Full
Edge	Full
IE 11	Partial