Embedding Tours in a Web Page¶

An embedded tour integrates seamlessly with the content of a web page. Visitors to your website can use the tour without having to leave the page. If you like, you can also provide a link so that they can run the tour standalone.

This section explains how you embed tours, and includes additional information you should know depending on how many and what kinds of tours you want to embed in the same web page. The choices are to embed:

The examples below show how an interactive map is embedded in this user guide web page with just two lines of HTML.

This map uses popups that appear over both the map and the web page.

The embed code for the tour above is shown below.

<script type="module" id="ma-83670" src="https://tour.mapsalive.com/83670/mapsalive-module.js"></script>
<div class="ma-83670" data-flex-height="250"></div>

Add section on controlling the height of an embedded tour

To prevent the embedded tour's height from changing to accommodate varying heights of hotspot content (media and text), put a max-height style on the tour's <div>. Note that max-height will appear in the code snippet if the tour's constraint height checkbox is checked on the Advanced Tour Layout screen.

If a tour is embedded in an HTML page where one of the tour's parent elements has its height style set (as opposed to max-height) then the max-height of the tour must be set to an equal or smaller height to prevent the tour from overflowing the container. This is necessary because the tour can detect and honor a parent container's max-height, but not its height.

Embed Code¶

You need just two lines of HTML to embed a tour. The code is shown below where ##### is the tour number.

How to get the embed code for a specific tour

View the tour on the Tour Preview screen
Click the Show Code Snippets link in the screen header
Copy the two lines of bolded HTML from section 5 of the snippets

How to embed a tour if my website software won't let me insert embed code

Most website builders will let you add your own HTML and CSS, but some won't let you insert <script> tags. In that case, you can embed with an iframe.

The minimal code needed to embed a tour is shown below where ##### represents a tour number.

<script type="module" id="ma-#####" src="https://tour.mapsalive.com/#####/mapsalive-module.js"></script>
<div class="ma-#####"></div>

The tour number appears 3 times in the embed code. If you copy/paste the embed code for one tour and then edit the copy to use for a different tour, be sure to change the tour number in all 3 places.

You can specify tour settings on the <div> tag to alter how the tour will look and behave when it runs. For instance, the embed code for the first example on this page uses the data-flex-height setting to limit the map's height to 250px.

How embed code works¶

The tour specifier ma-##### in the <script> tag id and in the <div> tag class are what tie the two tags together. If they don't match, an embedding error will display and the tour won't run.

The two tags do not need to be together. You can put the <script> tag with your other <script> tags if you like.

`<script>` tag¶

The <script> tag loads the mapsalive-module.js JavaScript file which, in turn, loads all the other JavaScript modules that the tour needs.

When embedding the same tour multiple times on a web page, only include the tag <script> once, otherwise, you'll get an embedding error because every id used on a web page must be unique.

`<div>` tag¶

Place the <div> tag at the location within the containing web page where you want the tour to appear. When a tour loads, it inserts all of its HTML into this <div> tag.

Where to insert the embed code within a web page¶

To embed a tour into a web page, paste the embed code at the location where you want the tour to appear on the page.

Below, a tour is embedded in the right column of a two-column layout. The left column of text occupies 60% of the width and the tour occupies the rest. The tour also has padding and a border. As you make the browser narrower or wider, both columns adjust to maintain their percentage widths.

The tour below is embedded in a two-column layout within this user guide page.

Quis laboriosam. Incidunt quia but magnam. Molestiae sit, aspernatur ab. Dolorem exercitation for quae for dolore. Ea exercitation nor non or labore so numquam laborum. Dolor. Vel ut or duis and eius ullam and autem. Ullamco cupidatat amet fugit. Dolorem. Qui. Quia molestiae, rem, but iure. Iste veniam cillum ex and sed or odit aliquid. Consequuntur consequatur quis and dolor non or eum but est. Nemo dicta. Eaque.

Lorem quaerat so sint so aspernatur nor ut sint. Consectetur magna or veritatis id cupidatat eum dicta. Est consequatur but exercitation omnis. Error esse. Labore quis voluptas suscipit id so numquam quam. Irure consectetur nor perspiciatis. Eius aliquip esse pariatur sit. Deserunt lorem but non nor fugit excepteur nor amet. Excepteur in. Velitesse quae beatae and veritatis and labore mollit.

The web page HTML and CSS for the two-column example above appear below.

HTMLCSS

<div class="wrapper">
    <div class="left-column">
        <p>Quis laboriosam. Incidunt quia but magnam. Molestiae sit, aspernatur ab. Dolorem exercitation for quae for dolore. Ea exercitation nor non or labore so numquam laborum. Dolor. Vel ut or duis and eius ullam and autem. Ullamco cupidatat amet fugit. Dolorem. Qui. Quia molestiae, rem, but iure. Iste veniam cillum ex and sed or odit aliquid. Consequuntur consequatur quis and dolor non or eum but est. Nemo dicta. Eaque.</p>
        <p>Lorem quaerat so sint so aspernatur nor ut sint. Consectetur magna or veritatis id cupidatat eum dicta. Est consequatur but exercitation omnis. Error esse. Labore quis voluptas suscipit id so numquam quam. Irure consectetur nor perspiciatis. Eius aliquip esse pariatur sit. Deserunt lorem but non nor fugit excepteur nor amet. Excepteur in. Velitesse quae beatae and veritatis and labore mollit.</p>
    </div>
    <div class="right-column">
        <script type="module" id="ma-83670" src="https://mapsalive.com/samples/83670/mapsalive-module.js"></script>
        <div class="ma-83670" data-flex-height=350></div>
    </div>
</div>

.wrapper {
    display: flex;
    height: 400px;
    padding: 12px;
    background-color: #ddd;
}
.left-column {
    width: 58%;
    margin-right: 2%;
    overflow-y: auto;
    text-align: justify;
    font-size: .90em;
    font-style: italic;
    padding: 8px;
}
.right-column {
    width: 40%;
    padding: 12px;
    border: solid 1px black;
    background-color: #fff;
    box-sizing: content-box;
}

About the HTML and CSS above

The embed code <div> tags uses the data-flex-height tour setting to limit the map height to 350px which is 50 less than the wrapper height of 400px. The value of 50 comes from the fact that the wrapper class has 24px of top + bottom padding, and the right-column class also has 24px of top + bottom padding, plus 2px of top + bottom border, for a total of 50px.

The right-column class sets box-sizing: content-box so that the tour can accurately detect the dimensions of its container <div> which is smaller on the inside than the outside because of its border padding.

Troubleshooting¶

This section discusses problems that can occur when embedding tours in a web page, and how you can resolve them.

An alert pops up reporting an embedding error when the web page loads¶

For an explanation of the error and how to fix it, see the Embedding Errors section.

The tour does not display and there is no error¶

There are certain kinds of embedding errors that MapsAlive cannot detect because the nature of the problem is not one that the tour logic can detect.

As an example of this type of error is if you specify http for the <script> tag's src when https is required (or vice-versa). For security reasons, the browser may silently prevent the tour from loading without telling you, though the error may be reported in the browser's Developer Console.

Another example is when you copy/paste/edit embed code for multiple tours and make the kinds of typos that cause the browser to ignore the embed code altogether.

If you can't see what the problem is, remove all the embed code and then add it back in for just one tour at a time. If the first tour works, add the code for the next. Then, if the first tour stops working, or the second won't load, the problem is most likely in the code you last added.

The tour does not look and/or behave the same when embedded as when run standalone¶

This kind of problem is almost always caused by a conflict between the tour and the containing web page's CSS, HTML, or JavaScript. Most often, the conflict is caused by the web page CSS. For example, if the web page CSS follows a bad practice of blindly styling all <img> tags (as opposed to only styling its own <img> tags) to have a left margin, then images in the tour will inherit that left margin which will cause images (including control buttons) in the tour to be misaligned.

If the tour works okay when run standalone, but exhibits problems when embedded, the first thing you need to do is determine what is causing the problem so that you'll know what needs to be done to correct it. Experienced web developers can figure out what's wrong by using the browser's Developer Tools. With those tools, you can use a process of elimination whereby you keep disabling parts of web page until the problem goes away. For example, if you see CSS that is styling all <img> tags you can disable that style to determine if doing so corrects the problems with the tour. Then you can correct the web page CSS.