Tour Settings¶

You can specify tour settings that take effect when a tour starts running. The settings let you alter the tour's appearance or behavior without having to use the Tour Builder and without having to re-publish the tour.

There are three ways to specify settings:

In a tour's embed code
On the query string
Using the API's setTourSetting method

Examples of using all three ways are shown below.

Embed CodeQuery StringsetTourSetting()

Setting names used in embed code must be prefixed with data- and values should be enclosed in quotes.

<script type="module" id="ma-12345" src="https://tour.mapsalive.com/12345/mapsalive-module.js"></script>
<div class="ma-12345" data-instance="primary" data-mobile-mode="never" data-flex-height="200"></div>

https://tour.mapsalive.com/12345?instance=primary&mobile-mode=never&flex-height=200

The setTourSetting method should be called from within the onEventTourLoaded callback function.

function onEventTourLoaded(event) {
    event.api.setTourSetting("instance", "primary);
    event.api.setTourSetting("mobile-mode", "never"");
    event.api.setTourSetting("flex-height", 200);
}

Precedence Rules¶

If you specify the same setting in more than one way, the embed code setting will take precedence over the query string setting which will take precedence over a JavaScript setting. This way, you can set a tour's default settings in JavaScript, but override them with embed code or the query string.

Settings¶

The names and descriptions of supported settings are listed below.

Important: Setting names in embed code must be prefixed with data-. For example, use data-mobile-mode not mobile-mode.

flex-height

Sets the height in pixels of a Flex Map tour. When this setting is not specified, or is set to zero, a Flex Map tour uses all of the available height within the tour's container. See the description of the flex-min-width setting to see how it can affect flex-height.

flex-max-width

A positive number that specifies the maximum width in pixels for the Flex Map regardless of how much width is available within the tour's container.

If set to zero, the map's width will be the width of the browser regardless of the width of the tour's container element. Use this setting if you want the tour's width to span the entire browser from edge to edge. This setting will only produce the desired result if the container CSS allows it. For example, if a containing element has an overflow:hidden style, the left and/or right sides of the map may not be visible even if the tour is spanning the entire browser width. You may need to code additional CSS to make the edge-to-edge effect work.

flex-min-width

A positive number that specifies a width in pixels for a Flex Map. If the tour's container width is less than flex-min-width, the map's width will be scaled to fit, and if flex-height is also set, the map's height will also be scaled.

flex-width

A positive number that specifies a width in pixels for the Flex Map. If the tour's container width is less than this value, the map's width will be scaled to fit

instance

Specifies the tour's instance identifier.

Examples:

<div class="ma-12345" data-instance="Temperature"></div>

https://tour.mapsalive.com/12345?instance=Temperature

Using the JavaScript API's setTourSetting method to set the instance identifier has no effect. The identifier must be set either in the embed code or on the query string.

mobile-mode

Specifies whether the tour should run in mobile mode or desktop mode.

The default behavior is for a tour to only run in mobile mode when running standalone on a small device. Whether a mobile device is "small" is based on the value of the small-mobile setting. If the tour is embedded, the tour runs in desktop mode even on a small mobile device.

Allowable values are:

Value	Meaning
always	Always use mobile mode even on large mobile devices and desktop browsers.
never	Never use mobile mode even on small mobile devices (always use desktop mode).
auto	Automatically use mobile mode whenever the tour is running on a small mobile device, otherwise use desktop mode.
standalone	Only use mobile mode when the tour is running standalone on a small mobile device. This is the default behavior. When a tour is embedded in a web page, even if running on a small mobile device, this setting will use desktop mode because mobile mode is not always desirable for an embedded tour. If you want to use mobile mode for an embedded tour, use the `auto` setting.

The standalone mode applies to tours that are one of the following:

Run from https://tour.mapsalive.com or from the tour's folder when hosted on your own server.
Embedded in a containing web page directly within the <body> tag like the embed code in the code-snippets. If the embed code is within another tag, such as a <div>, that is within the <body> tag, the tour is not considered to be standalone.

page

The page number, or the page Id, of the first page to display when the tour first loads.

Normally you specify the first page by selecting its name from the Show First dropdown list on the Tour Manager screen, but you can use this setting to override that selection.

The page number for each page in a tour is shown on the Pages in this Tour section on the Tour Manager screen.

The page Id is one of the following:

Map Id field on the Advanced Map Options screen
Gallery Id field on the Advanced Gallery Options screen
Data Sheet Id field on the Advanced Data Sheet Options screen

Examples:

<div class="ma-12345" data-page="2"></div>
<div class="ma-12345" data-page="first-floor"></div>

https://tour.mapsalive.com/12345?page=2
https://tour.mapsalive.com/12345?page=first-floor

You cannot use the JavaScript API's setTourSetting method to set the first page, because a page is displayed before the tour's JavaScript is interpreted.

small-mobile

A positive number that specifies a screen height in pixels used to determine when a tour will deem a mobile devices as small and thus display using mobile mode instead of desktop mode. You can use the isSmallMobileDevice API property to check whether the tour is treating the device as small.

The height is the device height when in portrait orientation. If you don't specify this setting, or if you set it to auto, the value is set to 1000 which means mobile mode will be used on screens having a height of less than 1000 pixels.

Normally you don't need to specify this setting, because the default setting causes mobile mode to be used on phones, and desktop mode to be used on larger tablets. However, which mode is used for medium-sized tablets will vary depending on the tablet size, and so you can use this setting to control which mode gets used.

As an example, you might set the value to 800 if you want medium-sized tablets to use desktop mode, but still want to use mobile mode on phones that have a portrait orientation height of less than 800px.

Examples:

<div class="ma-12345" data-small-mobile="800"></div>

https://tour.mapsalive.com/12345?small-mobile=800

event.api.setTourSetting("small-mobile", 800);

stacked-layout

The default is 50 to indicate that a Classic tour with a tiled layout will switch to a stacked layout when the browser width is less than 50% of the tour's width setting. Set it to 0 if you don’t want the tour to ever switch to a stacked layout. Set it to a value <= 100 to specify the percentage browser width below which the tour should switch to a stacked layout.

Example:

// Switch to stacked layout when the tour's container is less then 70% of the tour's full width. 
function onEventPageLoaded(event) {
   event.api.setTourSetting("stacked-layout", 70);
}

Performance related settings

These settings can be set to true or false. An attempt to set a non-boolean value is ignored.

disable-blending

The default is true. Specify false to enable the blend mode effect on all markers while zooming or panning the map. Note that setting this option to false can cause the map to be sluggish when zooming or panning when the map has a large number of markers that use the Blend Effect which is very compute-intensive. When this option is set to true, markers that using blending will appear unblended only while panning or zooming. This option has no effect if disable-drawing is set to true.

Examples:

<div class="ma-12345" data-disable-blending="false"></div>

https://tour.mapsalive.com/12345?disable-blending=false

event.api.setTourSetting("disable-blending",false);

disable-drawing

The default is false. Specify true to disable drawing of markers while zooming or panning the map. Use this option only if the map is sluggish when zooming or panning and if disable-blending does not improve performance. When this option is set to true, all markers will disappear when you start zooming or panning the map, and then reappear when the zooming or panning stops.

disable-caching

The default is false. Specify true to disable marker caching. Only set this option if recommended by MapsAlive technical support.