Skip to content

Embedding Instances of the Same Tour

You can embed two or more tours that have the same tour number into a web page.

One reason for embedding the same tour more than once is two show different pages of the same tour so that a visitor to the web page can see both at the same time. The example below is a two-page restaurant menu tour that has separate breakfast and lunch pages.

Touch or mouse-over a thumbnail to see a larger photo

The embed code below shows how the two pages of the tour above can be embedded. The code uses the data-page tour setting to control which page to show for each instance.

<script type="module" id="ma-83663" src="https://tour.mapsalive.com/83663/mapsalive-module.js"></script>
<div class="ma-83663" data-page="breakfast"></div>
<div class="ma-83663" data-page="lunch"></div>

A second reason for embedding the same tour more than once is when you use the API to make one page of a tour display different content depending on the tour settings you use when you embed the tour. You can see an example in the Live Data section of this user guide where two instances of a one-page USA map tour display the current temperature or current humidity for each of the 50 states.

A third reason for embedding the same tour more than once is when you want different pages of the same tour to interact with each other as demonstrated by the example below.

Click or touch a region on the USA map to see its detailed regional map in the same tour

The locator map tour above contains five map pages: one for the USA map, and four more for the regional maps. When you choose a region on the USA map, the first tour instance tells the second tour instance to display that region map. Conversely, if you use the right tour's nav button to view a different region, the second tour instance tells the first tour instance to select that region on the USA map. How this works will be explained later in a code walkthrough.

How to hide the nav button on one instance of a tour, but not the other

To dynamically hide the nav button, use the CSS below, specifying the number of the page to hide. 

.maPage-1 .maNavButton {
    display: none;
}

Instance Identifier

When embedding multiple instances of a tour that uses the API, you can specify a unique instance identifier in each tour's embed code. The restaurant menu example at the top of this page does not specify an instance identifier because it does not use the API. However, the locator map example above does specify an instance identifier because of the way it uses the API. This will become more clear shortly.

The instance identifier must be unique within a containing web page. This is necessary so that the MapsAlive method getApi can determine which instance to return.

Below is the embed code for the two tour instances of the locator map above.

<script type="module" id="ma-83662" src="https://tour.mapsalive.com/83662/mapsalive-module.js"></script>
<div class="ma-83662" data-instance="usa"></div>
<div class="ma-83662" data-instance="region" data-page="east"></div>

Each <div> tag in the code above uses the data-instance tour setting to specify a unique instance identifier. The instance identifiers are usa and region. You can use any tour or instance identifiers you like as long as they contain only letters, digits, hyphen, or underscore.

Note: The <script> tag is embedded only once for both tours as explained in the how embed code works section.

Using the API

When there are multiple instances of the same tour, each instance has its own API object. JavaScript you write to communicate with the API must specify which API object gets called, and which tour the API object calls back to. It’s like this because all of your JavaScript for all of your tours resides in the same JavaScript namespace within the web page. As such, you must code your JavaScript in a way that disambiguates calls and callbacks so that each tour instance calls to its API object and each API object makes callbacks to its tour instance.

You disambiguate calls to the API by directly calling a tour's API object rather than making calls using the MapsAlive.api calling convention which you can use when a web page contains only one tour. There are three ways to get the API object for a tour instance:

  • Call the getApi MapsAlive method
  • Get the API object from the Event object that is passed to callback functions
  • Get the API object from the Event object that is returned by the getEvent MapsAlive method.

All three methods used by the locator map tour's JavaScript are used in the code that is provided in the section below.

Code walkthrough

Below is the JavaScript for the locator map tour shown above. It comes from the JavaScript field of the tour's Custom HTML screen. The comments provide a walk-through that explains what the code does and why.

// The showRegion function is the click handler for the four region hotspots on the USA map and therefore,
// when it gets called, we know that the call came from the "Usa" instance of the tour. The click
// handler for each region is specified on the Hotspot Actions screen for each region as "showRegion();"
// Click handlers are coded by the user and so no event object gets passed to them.
//
function showRegion() {
   // Get the event object associated with the call to this click handler function.  
   let event = MapsAlive.getEvent();

   // Get the Id of the hotspot that was clicked. The hotspot Ids for the four
   // regions on the USA map are named "west", "mountain", "midwest", and "east".
   let hotspotId = event.hotspot.id;

   // Get the API object for the region instance of the tour.
   let apiForRegion = MapsAlive.getApi("region");

   // Make sure the region API object exists before using it. It will exist when both the "Usa" and
   // "Region" instances of the tour are embedded in a web page, but not in Tour Preview or when the
   // the tour is run standalone because, in those cases, there is only the default "Usa" instance.
   // Tell the "Region" instance to display the page for the clicked region. The maps Ids for the four
   // region maps are "west", "mountain", "midwest", and "east", same as the USA map's hotspot Ids.
   if (apiForRegion) 
      apiForRegion.goToPage(hotspotId);
 
   // Just for fun, blink the region that the user clicked on the USA map. The event object
   // contains the API object for the "Usa" instance, so use it to request blinking on the USA map.
   event.api.setMarkerBlink(hotspotId , 3);
}

// The onEventPageLoaded function gets called whenever one of the tour's five map pages displays.
// However, only honor the call when a region map loads and ignore it when the USA map loads.
// An event object is passed to the function because the function is called back from an API object.
// The callback will occur when the user selects a region name from the region map's nav menu.
//
function onEventPageLoaded(event) {
   // Ignore the call when the USA map loads.
   if (event.instance !== "region")
      return;

   // Get the API object for the "Usa" instance of the tour.
   let apiForUsa = MapsAlive.getApi("usa");

   // Tell the "Usa" instance to select its region marker that corresponds to the region page that just
   // loaded. Do this to a) show the region marker as selected and b) to visually keeps the instances in
   // sync. Since the region page Ids match the USA map hotspot Ids, pass the page Id as the hotspot Id.
   if (apiForUsa) {
      let hotspotId = event.page.id;
      apiForUsa.setMarkerSelected(hotspotId);
   }
}