API Methods¶

The API object's methods are listed below in alphabetical order.

Colors¶

Some API methods take color parameters. You can specify a color these ways:

A numeric value as a JavaScript hexadecimal number in the range 0x000000 to 0xffffff
A CSS color as a JavaScript string in the range "#000000" to "#FFFFFF" (or "#ffffff")

changeMarkerShapeAppearance¶

The changeMarkerShapeAppearance method alters the normal or selected appearance of the shape of one or more markers. It ignores markers that do not have a shape. The method allows you to change the color and opacity of the shape’s line and interior fill color or change effects, but it cannot change the shape itself or the thickness of its line. The change stays in effect until you either call the method again with new parameters or call the restoreMarkerShapeAppearance method to restore the default appearance.

Use this method when you want to change the appearance of specific markers. To change the appearance of all markers that use a specific style, use the changeMarkerStyleAppearance method.

Signature¶

changeMarkerShapeAppearance
    (selected, hotspotIdList, lineColor, lineAlpha, fillColor, fillAlpha, effects, draw = true)

Example¶

api.changeMarkerShapeAppearance (true, "hotspot1, hotspot7, hotspot19", "#00CC00", 100, null, null,"blend");

Parameters¶

selected: Specifies whether the method should change the shape’s selected or normal appearance. The value true indicates the selected appearance. The value false indicates the normal appearance.
hotspotIdList: A comma-separated list of one or more hotspot Ids. The shape appearance of the marker for each hotspot identified in the list will be altered by the method call. You can also specify "*" to mean all hotspots on the map.
lineColor: The color to use for the shape’s line or null to keep the existing color.
lineAlpha: The opacity to use for the shape’s line or null to keep the existing opacity.
fillColor: The color to use for the shape’s interior or null to keep the existing color.
fillAlpha: The opacity to use for the shape’s interior or null to keep the existing opacity.
effects: The effects to use on the shape or null to keep the existing effects. For no effects, provide an empty string "".
draw: Specifies whether the marker should be drawn immediately to show its new appearance. The value defaults to true, but you can set it to false if you are updating many markers and, for performance reasons, want to delay drawing (by calling the drawAllMarkers method) until after the appearance of all markers has been updated.

changeMarkerStyleAppearance¶

The changeMarkerStyleAppearance method alters the normal or selected appearance of a marker style and thus changes the appearance of all markers that use that style. The method allows you to change the color and opacity of the style’s line and interior fill color or change effects.

The change stays in effect until you either call the method again with new parameters or call the restoreMarkerStyleAppearance method to restore the default appearance.

Calling this method does not make changes to the style in the Tour Builder. Use this method when you want to change the appearance of all markers that use a specific style. To change the appearance of specific markers, use the changeMarkerShapeAppearance method.

Signature¶

changeMarkerStyleAppearance(
   selected, styleId, lineColor, lineAlpha, fillColor, fillAlpha, effects, draw)

Example¶

api.changeMarkerStyleAppearance(true, 17304, 0x00CC00, null, 0xdd1d38, null, "");

Parameters¶

selected:: Specifies whether the method should change the style’s selected or normal appearance. The value true indicates the selected appearance. The value false indicates the normal appearance.
styleId: The Id number of the style to be changed. You can find a style’s Id at the top of the Edit Marker Style screen.
lineColor: The color to use for the shape’s line or null to keep the existing color.
lineAlpha: The opacity to use for the shape’s line or null to keep the existing opacity.
fillColor: The color to use for the shape’s interior or null to keep the existing color.
fillAlpha: The opacity to use for the shape’s interior or null to keep the existing opacity.
effects: The effects to use on the shape or null to keep the existing effects. For no effects, provide an empty string "".
draw: Specifies whether the marker should be drawn immediately to show its new appearance. The value defaults to true, but you can set it to false if you are updating many markers and, for performance reasons, want to delay drawing (by calling the drawAllMarkers method) until after the appearance of all markers has been updated.

closePopup¶

The closePopup method closes a pinned popup as though you had clicked its close X. If there is no pinned popup, this method has no effect.

Signature¶

closePopup()

Example¶

api.closePopup();

disableMarkerDrawing¶

The disableMarkerDrawing method disables or enables the drawing of markers to improve the performance of maps that have a lot of markers and that use the JavaScript API to dynamically change or restore the appearance and/or styling of several markers at the same time.

Normally, when you call changeMarkerShapeAppearance, changeMarkerStyleAppearance, restoreMarkerShapeAppearance, or restoreMarkerStyleAppearance, the changed marker gets redrawn immediately which can, in turn, cause other markers on the map to be redrawn. In some cases, this can take several seconds, especially if the markers use the Blend Effect. To improve performance in this situation, you can first call disableMarkerDrawing to disable drawing, and then, after all the calls to change the appearance of markers have been made, call it again to enable drawing.

As an alternative to using this method, when you call the methods that change a marker's appearance, you can set their draw parameter to false. After all the calls are made, you can then call drawAllMarkers.

Signature¶

disableMarkerDrawing(disable)

Example¶

api.disableMarkerDrawing(true);

Parameters¶

disable: A value of true or false to indicate whether marker drawing should be disabled (true) or enabled (false).

drawAllMarkers¶

The drawAllMarkers forces drawing of all the markers on the map. You only need to use this method if you have been calling the changeMarkerShapeAppearance, changeMarkerStyleAppearance, restoreMarkerShapeAppearance, or restoreMarkerStyleAppearance methods with the draw parameter passed as false.

Signature¶

drawAllMarkers()

Example¶

api.drawAllMarkers();

drawRoute¶

The drawRoute method draws a line through a set of hotspot markers. The route is drawn through the center point of each marker. For detailed information about drawing routes, see the section in this guide on Drawing Routes.

Signature¶

drawRoute(hotspotId, route, lineWidth, lineColor, lineApha, effects);

Examples¶

api.drawRoute("Route", "H1,H2,H3", 3, 0x00CC00, 50, "Shadow");
api.drawRoute("Route", "R1", 3, 0x00CC00, 50, "Shadow");

Parameters¶

hotspotId: A hotspot Id that identifies the route hotspot to use to draw the route. The Is Route option for the hotspot must be checked on the Advanced Hotspot Options screen. If the marker was previously used to draw a different route, the call will erase the prior route before drawing the new route.
route: The route parameter must be one of the following:

The name of a route that was imported into MapsAlive from an Excel file. The name must be enclosed in quotes.
A comma-separated list of two or more hotspot Ids enclosed in quotes. The center point of the marker for each hotspot identified in the list will be used as a waypoint along the route.

To create a gap in the route, use a semicolon instead of a comma. The semicolon tells the route drawing logic to “pick up the pen” after drawing to the waypoint that precedes the semicolon and to put it down again at the waypoint following the semicolon.
lineWidth: Optional. The width of the route’s line in pixels. Default is 3.
lineColor: Optional. The color to use for the line. Default is 0xff0000 (red);
lineAlpha: Optional. The opacity to use for the line. Default is 100.
effects: Optional. The effects to use on the line. The default is no effects which you can also specify using an empty string "".

drawRoutes¶

The drawRoutes method draws multiple routes. For detailed information about drawing routes, see the section in this guide on Drawing Routes.

Note that unlike the drawRoute method described above, the drawRoutes method does not require use of a route hotspot.

Signature¶

drawRoutes(routes);

Example¶

const route1 = {id:"firstRoute"};
const route2 = {id:"secondRoute"};
const routes = [route1, route2];
api.drawRoutes(routes);

Parameters¶

routes: The routes parameter is an array of objects that define the routes to be drawn. Each object must have a routeId property to specify the route definition. Each object can also have any of these optional properties: lineWidth, lineColor, lineAlpha, and effects. See the description of the drawRoute method for an explanation of the properties.; If there is no definition for the route identified by routeId, the object will be ignored. You can determine if a route is defined using the routeIsDefined method.

getElementByUniqueId¶

The getElementByUniqueId method returns the element object for a tour element. If there is no element corresponding to the Id parameter, the method returns null.

Use this method instead of document.getElementById for tour elements because MapsAlive generates unique element Ids for every element.

Signature¶

getElementByUniqueId(id);

Example¶

let element = api.getElementByUniqueId("CustomHtmlAbsolute");

Parameters¶

id: The ID of the element to locate, but without the ma prefix. For example, to get the maCustomHtmlAbsolute element, specify CustomHtmlAbsolute as the ID.

getHotspotIdsForCategory¶

The getHotspotIdsForCategory method returns Ids for all hotspots, or a list of the hotspot Ids that belong to one or more categories.

If you specify more than one category, the method can return either the union (logical OR) or the intersection (logical AND) of the hotspots that belong to those categories. In other words, you can request that it return all hotspot Ids that have any of the categories, or have it return only the Ids of hotspots that have all of the categories.

Signature¶

getHotspotIdsForCategory(categoryCodeList, and = false);

Example¶

let all = api.getHotspotIdsForCategory("", true);
let housesOrCondos = api.getHotspotIdsForCategory("house, condo", false);
let housesAndPriceIsOverTenMillion = api.getHotspotIdsForCategory("house, overTenMillion", true);

Parameters¶

categoryCodeList: A comma-separated list of one or more category codes, or an empty string.; To get Ids for every hotspot on the map, specify an empty string for categoryCodeList and true for the and parameter.
and: If omitted or false, the method returns Ids for all hotspots that belong to any of the categories in categoryCodeList. For example, any hotspot that belongs to either the home or condo category. If true, only returns Ids for hotspots that belong to every category in categoryCodeList. For example, only hotspots that belong to both the home category and the overTenMillion category.

getQueryStringArg¶

The getQueryStringArg method returns the value of a browser query string parameter. If the parameter specified by the arg parameter is not on the query string, the method returns an empty string.

Signature¶

getQueryStringArg(arg);

Example¶

let zipcode = api.getQueryStringArg("zip");

Parameters¶

arg: The name of an argument on the browser query string.

goToPage¶

The goToPage method changes the tour's current page to the one indicated by the pageSpecifier parameter.

Signature¶

goToPage(pageSpecifier);

Example¶

api.goToPage(2);
api.goToPage("first-floor");

Parameters¶

pageSpecifier: The page number, or the page Id, of the page to go to.; Page number: To determine the page number for a map, gallery, or data sheet in a tour, see the Pages in this Tour section on the Tour Manager screen.; Page Id: If the page is a map, the page Id comes from the Map Id field on the Advanced Map Options screen. If the page is a gallery, the page Id comes from the Gallery Id field on the Advanced Gallery Options screen. If the page is a data sheet, the page Id comes from the Data Sheet Id field on the Advanced Data Sheet Options screen.

liveData.flushCache¶

The flushCache method flushes the cached data for either a single hotspot or for every hotspot that gets its content from LiveData. Use this method to cause the hotspot cache period to expire so that the next time the mouse moves over a hotspot, new data will be requested from the server. This works even if the cache period is set to zero.

The flushCache method is useful if your map has options that allow different kinds of data to be returned for the same hotspot. For example, on a weather map, mousing over a hotspot might return the forecast showing temperatures in Fahrenheit. Since weather doesn’t change frequently, you might use a long cache period. However, if you provide an option that allows the temperature to be shown in Celsius and the user chooses the option, you could call this method to flush the Fahrenheit data so that the server will get called to retrieve Celsius data the next time the mouse moves over a hotspot.

Learn about Live Data.

Signature¶

liveData.flushCache(hotspotId = 0)

Example¶

api.flushLiveDataCache();

Parameters¶

hotspotId: A hotspot Id that identifies the hotspot that will have its cache flushed. If omitted or 0, the cache for all hotspots will be flushed.

liveData.fulfillRequest¶

The fulfillRequest method lets you provide your own text in response to a call to requestHotspot instead of requesting the text from a server and waiting for a response. The effect of using fulfillRequest is equivalent to using requestHotspot to request text from a server that responded instantaneously.

Create a sample that uses fulfillRequest

Learn about Live Data.

Signature¶

liveData.fulfillRequest(hotspotId, text, cachePeriod);

Example¶

api.liveData.fulfillRequest("H7", "Hello", 0);

Parameters¶

hotspotId: The hotspot Id associated with the request.
text: The text to be used as the hotspot's text content.
cachePeriod: Same as the cachePeriod parameter for the liveData.requestHotspot method.

liveData.requestData¶

The requestData method requests data from a server.

Learn about using this method to make a Live Data data request.

Signature¶

liveData.requestData(responseType, requestId, url, parameterList)

Example¶

let url = "https://myserver.com/livedata/demo.php";
api.liveData.requestData("json", "temperature", url, "unit", "celcius")

Parameters¶

responseType: The format of the data to be returned in the response. The value must be one of the following strings: "html", "json" or "xml". The response type tells MapsAlive how it should interpret the data that comes back from the server.
requestId: A quoted string that you provide to identify the request so that you’ll know what the data is when your server sends it back to your map. The requestId can be anything you like and if you don’t have a use for it, just pass "" (an empty string).
url: The url specifies how to call your server script that returns Live Data. If the web page that is making this call is on the same server as the script, the url can be a relative reference, that is, it does not need to specify the full path to the script. For example, it could be just getEmployee.phpinstead of https://www.myserver.com/getEmployee.php.
parameterList: The parameterList is a variable-length list of zero or more name/value pairs separated by commas. They are used to tell your server script what data is being requested.

liveData.requestHotspot¶

The requestHotspot method requests HTML from a server for a specific hotspot.

Learn about using this method to make a Live Data hotspot request.

Signature¶

liveData.requestHotspot(responseType, cachePeriod, url, parameterList)

Example¶

let url = "https://myserver.com/livedata/demo.php";
api.liveData.requestHotspot("xml", 60, url, "employeeCity", cityName)

Parameters¶

responseType: The format of the data to be returned in the response. The value must be one of the following strings: "html", "json" or "xml". The response type tells MapsAlive how it should interpret the data that comes back from the server.
cachePeriod: The cache period is the number of seconds that must elapse between Live Data calls to your server for any given hotspot in a tour. The minimum number of seconds you can specify is 1 second. Specify a value of 1 or greater for data that could change on your server while someone is viewing your tour. Specify zero for data that rarely or never changes such as employee information. Zero tells MapsAlive to only call your server once during the time someone is using a map (if they leave the map and come back, the server will be called again).; When your tour requests data from your server, the tour keeps a copy of the data in its cache. If the elapsed time between two requests for the same hotspot is less than or equal to the value of cachePeriod, or if cachePeriod is set to zero, the tour will display the cached data for that hotspot instead of calling the server. Otherwise, the tour will make a new call to the server to get data. You can force the cache period for all hotspots on a map to expire immediately by calling the livedData.flushCache method.
url: The url specifies how to call your server script that returns Live Data. If the web page that is making this call is on the same server as the script, the url can be a relative reference, that is, it does not need to specify the full path to the script. For example, it could be just getEmployee.phpinstead of https://www.myserver.com/getEmployee.php.
parameterList: The parameterList is a variable-length list of zero or more name/value pairs separated by commas. They are used to tell your server script what data is being requested.

liveData.setCustomError¶

The setCustomError method lets you customize the appearance of Live Data errors.

Learn about Live Data.

Signature¶

liveData.setCustomError(message, color, backgroundColor, showDetails);

Example¶

api.liveData.setCustomError("My custom message", `"black"`, `"#FAFAD2"`, true);

Parameters¶

message: Plain text or HTML that will be displayed at the top of the error.
color: The color parameter lets you set the error’s text color. You can specify a color name such as "blue" or a hex value like "#0000ff".
backgroundColor: The backgroundColor parameter lets you set the error’s background color. You can specify a color name such as "blue" or a hex value like "#0000ff".
showDetails: By default, the error shows detailed information about what went wrong. If you don’t want your users to see this information, pass false as the showDetails parameter. To show the details, pass true. Even if you don’t want users to see details, you might want to show them while developing your Live Data tour to help you quickly identify the cause of errors.

mapIsTouchDevice¶

The mapIsTouchDevice method returns true if the map is being displayed on a device that has a touch screen such as a phone or tablet. It also returns true for a laptop that has a touch screen but also has a mouse. It returns false otherwise.

Signature¶

mapIsTouchDevice()

Example¶

const isTouchDevice = api.mapIsTouchDevice();

media.getAudio¶

The getAudio method returns an HTMLAudioElement object. That object inherits from the HTMLMediaElement interface which has many useful properties and methods. The example below shows how it can be used to add an event listener to the audio object.

Signature¶

media.getAudio()

Example¶

// Listen for when the sound ends, and when it does, call a function named soundStoppedPlaying.
let audio = api.media.getAudio();
audio.addEventListener("ended", soundStoppedPlaying);

function soundStoppedPlaying() {
    // Do something when the music stops.
}

media.pauseAudio¶

The pauseAudio method pauses the playing of a sound that is currently playing. You can resume play at the point that play was paused by calling playOrResumeAudio, or you can start playing the sound again from the beginning by calling playAudio.

Signature¶

media.pauseAudio()

Example¶

api.media.pauseAudio();

media.playAudio¶

The playAudio method plays an audio file that is in MP3, WAV, or OGG format if supported by the browser. If the sound identified by the url parameter is currently playing when this method is called, play will start over at the beginning. See also pauseAudio and playOrResumeAudio.

A browser will only allow sounds to play when there has been some direct user interaction with the page involving a click or touch. For example, if a hotspot plays a sound on mouseover, it won't work when the page first loads, but will work if you clicked on another hotspot first, or if you have clicked on a menu item to get to that page. As such, don't expect to have sounds play automatically, or only in response to a mouseover.

Signature¶

media.playAudio(url, toggle = true);

Example¶

api.media.playAudio("http://www.mydomain.com/mysounds/OhCanada.mp3");

Parameters¶

url: The url of an audio file that is located on the internet.
toggle: A value of true or false to indicate whether calls to this method should toggle between playing and stopping play (when set to true) or to always start play from the beginning (when set to false).

media.playOrResumeAudio¶

The playOrResumeAudio method will resume play of a sound identified by the url parameter that was paused by calling pauseAudio, or play a sound that is not already playing starting at the beginning. See also playAudio and pauseAudio.

Signature¶

media.playOrResumeAudio(url, toggle = true)

Example¶

api.media.playOrResumeAudio "http://www.mydomain.com/mysounds/OhCanada.mp3");

Parameters¶

url: The url of an audio file that is located on the internet.
toggle: A value of true or false to indicate whether calls to this method should toggle between playing and pausing (when set to true) or to always play or resume play (when set to false).

media.stopAudio¶

The stopAudio method stops play of a sound. Once stopped, play cannot be resumed except to play again from the beginning. See also pauseAudio.

Signature¶

media.stopAudio()

Example¶

api.media.stopAudio();

positionMapToShowMarker¶

The positionMapToShowMarker method pans the map if necessary to ensure that the specified hotspot’s marker can be seen. This method only has an effect if the map is zoomed-in and positioned in such a way that the specified marker is outside the part of the map that is visible.

If a popup is open and this method causes the map to pan, the popup will close, the same as it would if you dragged the map with your mouse or if you clicked the pan controls on the map.

If the mouse is over a marker when this method is called, a mouseout event will usually occur because the marker’s position will probably change as a result of the map panning. Because of this, use of this method in the JavaScript for a hotspot’s Click Action, Mouseover Action, or Mouseout Action can produce unpredictable behavior.

This method has no effect if the map is not zoomable.

Signature¶

positionMapToShowMarker(hotspotId)

Example¶

api.positionMapToShowMarker("h1")

Parameters¶

hotspotId: A hotspot Id for the marker that is to be made visible.

reportErrors¶

The reportErrors method causes JavaScript errors to be reported when a tour is running outside of Tour Preview. Normally, errors are only reported while in Tour Preview so that only you will see them, but not users of the tour. You can use this method while developing a tour, especially one that uses the API, to see JavaScript errors that occur whether or not in Tour Preview. When the tour is working correctly, you can remove the call to this function, or call it passing false.

Signature¶

reportErrors(report)

Example¶

function onEventTourLoaded(event) {
   event.api.reportErrors(true);
}

Parameters¶

report: Specifies whether errors should be reported outside of Tour Preview.

restoreMarkerShapeAppearance¶

The restoreMarkerShapeAppearance method restores the normal or selected appearance of the shape of one or more markers to the appearance you defined in the MapsAlive Tour Builder. Use this method if you have changed the appearance using the changeMarkerShapeAppearance method and want to put it back the way it was originally.

Signature¶

restoreShapeAppearance(selected, hotspotIdList, draw = true)

Example¶

api.restoreMarkerShapeAppearance(true, "hotspot1, hotspot7, hotspot19");

Parameters¶

selected: Specifies whether the method should restore the shape’s selected or normal appearance. The value true indicates the selected appearance. The value false indicates the normal appearance.
hotspotIdList: A comma-separated list of one or more hotspot Ids. The shape appearance of the marker for each hotspot identified in the list will be altered by the method call. You can also specify "*" to mean all hotspots on the map.
draw: Specifies whether the marker should be drawn immediately to show its new appearance. The value defaults to true, but you can set it to false if you are updating many markers and, for performance reasons, want to delay drawing (by calling the drawAllMarkers method) until after the appearance of all markers has been updated.

restoreMarkerStyleAppearance¶

The restoreMarkerStyleAppearance method restores the normal or selected appearance of a marker style to the appearance you defined in the MapsAlive Tour Builder. Use this method if you have temporarily changed the appearance using the changeMarkerStyleAppearance method and want to put it back the way it was originally.

Signature¶

restoreMarkerStyleAppearance(selected, styleId, draw = true);

Example¶

api.restoreMarkerStyleAppearance(true, styleId);

Parameters¶

selected: Specifies whether the method should restore the shape’s selected or normal appearance. The value true indicates the selected appearance. The value false indicates the normal appearance.
styleId: The Id number of the style to be restored. You can find a style’s Id at the top of the Edit Marker Style screen.
draw: Specifies whether the marker should be drawn immediately to show its new appearance. The value defaults to true, but you can set it to false if you are updating many markers and, for performance reasons, want to delay drawing (by calling the drawAllMarkers method) until after the appearance of all markers has been updated.

routeIsDefined¶

The routeIsDefined method returns true or false to indicate if the route identified by the routeId argument is defined.

Signature¶

routeIsDefined(routeId)

Example¶

if (!api.routeIsDefined(routeId))
    alert("No route is defined for route " + routeId);

Parameters¶

routeId: The name of an imported route definition.

runSlideShow¶

The runSlideShow method starts or stops running a slide show. The method takes an interval parameter to specify how long each slide should display in milliseconds. There are 1,000 milliseconds in 1 second, so for example, specify 1500 if you want each slide to display for 1 ½ seconds.

Signature¶

runSlideShow(interval)

Example¶

api.runSlideShow(1500);

Parameters¶

interval: The number of milliseconds that each slide should display. Specify zero to stop the slide show.

setHotspotHtml¶

The setHotspotHtml method replaces a hotspot's text content with the value supplied in the html parameter.

Signature¶

setHotspotHtml(hotspotId, html)

Example¶

api.setHotspotHtml("H1", "Hello");
api.setHotspotHtml("H2", "<div>Hello</div>");

Parameters¶

hotspotId: A hotspot Id that identifies the hotspot to operate on.
html: A string containing the HTML to be set.

setHotspotUsesLiveData¶

The setHotspotUsesLiveData method sets one or more hotspots to be Live Data hotspots.

Signature¶

setHotspotUsesLiveData(hotspotIdList, uses)

Example¶

api.setHotspotUsesLiveData("h1, h7", true);

api.setHotspotUsesLiveData("*", true);

Parameters¶

hotspotIdList: A comma-separated list of one or more hotspot Ids.
uses: Specifies whether the hotspots in the list should use Live Data.

setHotspotTitle¶

The setHotspotTitle method replaces a hotspot's title with the value supplied in the title parameter.

Signature¶

setHotspotTitle(hotspotId, title)

Example¶

api.setHotspotTitle("H1", "New Title");

Parameters¶

hotspotId: A hotspot Id that identifies the hotspot to operate on.
title: A string containing the title to be set.

setMapPan¶

The setMapPan method pans the map left, right, up, down, or at an angle. The map must be zoomable and at least partially zoomed in for the method to have an effect. If the map cannot be panned as much as requested, it will pan to an edge.

Signature¶

setMapPan(panX, panY)

Example¶

api.setMapPan (panX, panY);

Parameters¶

panX: A distance in pixels to pan the map left or right. A positive value pans right and a negative value pans left.
panY: A distance in pixels to pan the map up or down. A positive value pans down and a negative value pans up.

setMapZoomInOut¶

The setMapZoomInOut method zooms the map in or out by a percentage. The map zoom level will not change if you attempt to zoom in when the map is zoomed in all the way or if you attempt to zoom out when the map is zoomed out all the way. If a popup is open when this method is called and the method causes the map zoom level to change, the popup will close, the same as it would if you clicked the zoom controls on the map.

If the mouse is over a marker when this method is called, a mouseout event will usually occur because the marker’s position will probably change as a result of zooming. Because of this, use of this method in the JavaScript for a hotspot’s Click Action, Mouseover Action, or Mouseout Action can produce unpredictable behavior. This method has no effect if the map is not zoomable.

Signature¶

setMapZoomInOut(delta)

Example¶

api.setMapZoomInOut(15);    // Zoom in 15%
mapsAlive.setMapZoomInOut(-10);     // Zoom out 10%

Parameters¶

delta: An integer that specifies the amount to zoom in or out. A positive value means zoom in. A negative value means zoom out.

setMapZoomLevel¶

The setMapZoomLevel method sets the map’s zoom level to a percentage that you specify. If the map is already set to the specified level, the method has no effect.

If a popup is open when this method is called and the method causes the map zoom level to change, the popup will close, the same as it would if you clicked the zoom controls on the map.

If the mouse is over a marker when this method is called, a mouseout event will usually occur because the marker’s position will probably change as a result of zooming. Because of this, use of this method in the JavaScript for a hotspot’s Click Action, Mouseover Action, or Mouseout Action can produce unpredictable behavior.

This method has no effect if the map is not zoomable.

Signature¶

setMapZoomLevel(level)

Example¶

api.setMapZoomLevel(75);    // Zoom the map to 75%

Parameters¶

level: An integer that specifies the desired zoom level percentage. If the value is larger than 100, the map will be zoomed to 100%. If the value is less than the map’s minimum zoom level, the map will be zoomed to its minimum level.

setMarkerBlink¶

The setMarkerBlink method makes one or more markers blink a specified number of times. The method can also be used to make one or more markers stop blinking.

Signature¶

setMarkerBlink(hotspotIdList, blinkCount)

Example¶

api.setMarkerBlink("h1, h2", 10);

Parameters¶

hotspotIdList: A comma-separated list of one or more hotspot Ids. The marker for each hotspot identified in the list will start or stop blinking.
blinkCount: Specifies the number of times the markers should blink. The value zero indicates that blinking should stop.

setMarkerDisabled¶

The setMarkerDisabled method disables or enables one or more markers. When a marker is disabled, it is visible on the map but does not respond to mouse movements or clicks. When a marker is disabled, it’s as though it were just a graphic element of the map image.

Signature¶

setMarkerDisabled(hotspotIdList, disabled)

Example¶

api.setMarkerDisabled("hotspot1, hotspot7, hotspot19", true);

Parameters¶

hotspotIdList: A comma-separated list of one or more hotspot Ids. The marker for each hotspot identified in the list will be disabled or enabled.
disabled: Specifies whether the method should disable or enable markers. The value true indicates disabled. The value false indicates disabled.

setMarkerHidden¶

The setMarkerHidden method hides or shows one or more markers. When a marker is hidden it has no appearance and does not respond to mouse movements or clicks. When a marker is hidden, it’s as though it is not on the map.

Signature¶

setMarkerHidden(hotspotIdList, hidden)

Example¶

api.setMarkerHidden("hotspot1, hotspot7, hotspot19", false);

Parameters¶

hotspotIdList: A comma-separated list of one or more hotspot Ids. The marker for each hotspot identified in the list will become hidden or visible. You can also specify "*" to mean all hotspots on the map.
hidden: Specifies whether the method should make markers hidden or visible. The value true indicates hidden. The value false indicates visible.

setMarkerOnTop¶

The setMarkerOnTop method moves a marker on top of any other markers that it overlaps.

Signature¶

setMarkerOnTop(hotspotId)

Example¶

api.setMarkerOnTop("hotspot1");

Parameters¶

hotspotId: The hotspot Id for the marker that will appear on top of any adjacent markers.

setMarkerSelected¶

The setMarkerSelected method selects a marker and displays the content associated with it as though the user had selected it either by moving their mouse over the marker or clicking on the marker depending on the marker options. The marker changes to its selected appearance.

Use this method to display a hotspot programmatically without user intervention.

When this method is called, the currently selected marker is deselected and reverts to its normal appearance.

If the map uses popups, calling the method again using the same hotspotId hides the popup, but the marker remains selected and continues to display its selected appearance.

Notes:

The setMarkerSelected method has no effect if the hotspot’s “Show this hotspot when” marker option is set to “never.”
This method should not be called in the JavaScript for a hotspot’s Click Action, Mouseover Action, or Mouseout Action. Doing so will cause unpredictable results because calling the method will conflict with the behavior of those mouse actions with regard to what marker is supposed to be selected or deselected.
If the hotspot’s map uses popups and the Mouse Location option is checked (on the Popup > Popup Behavior screen), the content will display at the mouse location which might not be near the hotspot’s marker since this method is called programmatically. As such, the Mouse Location option should probably be turned off when using this method.

Signature¶

setMarkerSelected(hotspotId)

Example¶

api.setMarkerSelected("hotspot1");

Parameters¶

hotspotId: A hotspot Id for the marker that will become the selected marker and have its content displayed.

setMarkerStatic¶

The setMarkerStatic method sets one or more markers as static or not static. When a marker is static, it will not change appearance when the mouse is over it. It will however still respond to mouseover, mouseout, and click events by performing the action associated with those events. When a marker is static, it’s as though its normal and selected appearance are the same.

Signature¶

setMarkerStatic(hotspotIdList, static)

Example¶

api.setMarkerstatic("H1", true);

Parameters¶

hotspotIdList: A comma-separated list of one or more hotspot Ids. The marker for each hotspot identified in the list will be set to static or not static.
static: Specifies whether the method should make the markers static or not static. The value true indicates static. The value false indicates not static.

setTourSetting¶

The setTourSetting method lets you set advanced tour settings.

This method should be called from the onEventTourLoaded callback function. If you use an invalid setting name, an alert will report that the setting is not supported.

Signature¶

setTourSetting(name, value)

Example¶

function onEventTourLoaded(event) {
    event.api.setTourSetting("flex-height", 400);
    event.api.setTourSetting("mobile", "auto");
}

Parameters¶

name: See the settings section of this user guide for the names and descriptions of settings supported by this method. Any setting listed there can be set using this method.
value: The value to set. Integer values, and the values true and false can be specified without quotes. Enclose string values in double or single quotes.

setTourTitle¶

The setTourTitle method changes the tour’s title text. The method has no effect if the tour's layout does not have a title bar. One way to use it is to dynamically update the title when the user mouses over or clicks a marker.

The tour's title text gets updated each time a new page displays. Therefore, if you want the title text to remain the same for every page, set the title in the onEventPageLoaded callback function.

Signature¶

onEventsetTourTitle(title)

Example¶

api.setTourTitle("Master Bedroom");

Parameters¶

title: A string that specifies the title text.

showHelpPanel¶

The showHelpPanel method displays the help panel for the page indicated by the pageSpecifier parameter. The page specifier can be a page number or a page Id. If no pageSpecifier parameter is passed, the method does nothing.

Signature¶

showHelpPanel(pageSpecifier)

Example¶

function onEventPageLoaded(event) {
    event.api.showHelpPanel(event.page.id);
}

showMarkerSelected¶

The showMarkerSelected method changes the marker’s appearance to either its normal or selected appearance without actually selecting the marker. To select the marker, use setMarkerSelected.

Use of this method can create unexpected behavior. For example, if you set all markers on a map to appear selected and the user then mouses over one of them, that marker becomes selected. If the map uses popups, when the user mouses off of the marker, it will become unselected and revert to its normal appearance. If the map uses a tiled layout, the marker will become unselected and revert to its normal appearance when the user mouses over and selects a different marker.

Signature¶

showMarkerSelected(selected, hotspotIdList)

Example¶

api.showMarkerSelected(true, "H2");

Parameters¶

selected: Specifies whether the method should set the marker’s selected or normal appearance. The value true indicates the selected appearance. The value false indicates the normal appearance.
hotspotIdList: A comma-separated list of one or more hotspot Ids. The marker for each hotspot identified in the list will have its appearance changed. You can also specify "*" to mean all hotspots on the map.

showNavPanel¶

The showNavPanel method works as a toggle to show or hide the navigation panel. When the panel is not showing, calling this method makes the panel visible. When the panel is showing, calling this method hides the panel.

Use this method when you are providing your own button or other mechanism for showing and hiding the nav panel instead of using the MapsAlive nav button.

During development and testing, you can leave the MapsAlive nav button visible to help you with accurate placement of your button. When everything is working correctly, you can hide the MapsAlive nav button by checking the Hide Nav Button checkbox on the Advanced Tour Layout screen.

Signature¶

showNavPanel()

Example¶

api.showNavPanel();

waitingForLiveData¶

The waitingForLiveData method lets your JavaScript pass true to tell MapsAlive that your code is waiting for a Live Data response and that MapsAlive should wait to finish loading the page until this method is called again with false, at which time, MapsAlive will call onEventPageLoaded.

This method is provided for tours that use the Live Data requestData method. It should be used in conjunction with the API's onEventPageLoading callback.

The need to call this method depends on what happens, and what's acceptable, if someone using your tour visits a hotspot before its Live Data content has loaded. If the data is not loaded, they may just see a tooltip or nothing at all which may be acceptable or it may be confusing. A notable case is a multi-page tour with a directory. The timing problem comes into play if while viewing one page the user opens the directory and selects a hotspot on another page. MapsAlive will try to immediately display the content for that hotspot even though the Live Data for the other page hasn't finished loading. In that case, the user will see the selected hotspot's marker blinking but no content. This situation can be remedied by using waitingForLiveData to prevent MapsAlive from displaying the hotspot's content until the Live Data has loaded.

If you call this method with false your logic must eventually call it again with true, otherwise, the page will never finish loading.

Signature¶

waitingForLiveData(waiting, message = "")

Example¶

function onEventPageLoading(event) {
   event.api.waitingForLiveData(true, "Getting the weather for all 50 states. Please wait.");
   let url = `https://myserver.com/service.php`;
   event.api.liveData.requestData("json", "", url, "map", event.page.id);
}

function onEventLiveDataResponse(event) {
    let response = event.response;

    // Do something with the response.

    // Determine if this is the last response.
    if (response.count === response.total)
        event.api.waitingForLiveData(false);
}

Parameters¶

waiting: A value of true or false to indicate whether your code is waiting for Live Data.
message: An optional message to display while the page is waiting. If you omit the parameter, MapsAlive displays a default message. The message parameter is ignored when the waiting parameter is false.