Skip to content

API Callback Functions

Callback functions are JavaScript functions which you code that are called by the API object when a specific event occurs. They allow your code to listen for events.

When the API object calls a callback function, it passes a single parameter which is an Event object. The Event object provides the callback function with information about the event.

Callback function names

A callback function name begins with onEvent and ends with the name of the event. For example: 

function onEventPageLoaded() {
   ...
}
Use the naming convention above when you code callback functions in the JavaScript field of a tour's Custom HTML. See the following section for the naming convention to use for callback functions in external JavaScript.

When a tour loads, MapsAlive inserts the JavaScript from the Custom HTML screen into the DOM, but first, it appends the tour number to each callback function name. It does this to disambiguate the callback functions for one tour from those of another tour that might be embedded in the same web page. This renaming is necessary because all the functions share the same namespace and therefore the name of each function must be unique.

Callback function naming convention for external JavaScript

When you code callback functions in external JavaScript, that is, JavaScript contained in the web page itself or in an external JavaScript file, you can append the tour number yourself, preceded by an underscore. The example below shows the callback function for the PageLoaded event for tour 12345. If you don't append the tour number, MapsAlive will call a function, if one exists, that does not have the tour number appended. Do not use this convention when coding JavaScript on the Custom HTML screen. If you do, your function won't get called.

<script type="text/javascript">
   function onEventPageLoaded_12345 {
      ...
   }
</script>

The callback functions are listed below in alphabetical order.

onEventDirectoryEntryClicked

If your JavaScript has this function, it will get called whenever a hotspot title is clicked in the directory.

Examples

function onEventDirectoryEntryClicked(event) { ... }

onEventHotspotChanged

If your JavaScript has this function, it will get called whenever the current hotspot changes. The value of event.hotspot.id is the hotspot Id.

The current hotspot usually changes when the user moves their mouse over its marker. It can also change when the hotspot is clicked or selected from the directory. Use this function if you need to perform an action every time the current hotspot changes.

To get additional information about the hotspot, use the API’s currentHotspot property.

If the value of event.hotspot.id is zero, no hotspot is selected. This happens when popups are being used and the mouse moves off of a hotspot. It also happens when a pinned popup is closed.

Examples

function onEventHotspotChanged(event) { ... }

onEventLiveDataResponse

If your JavaScript has this function, it will get called when the data for a prior Live Data request has arrived.

The event parameter contains information about the response. For example, the value of event.hotspot.id is the hotspot Id for which the data was requested. See the Event object for a description of the event.response properties.

Examples

function onEventLiveDataResponse(event) { ... }

onEventPageLoaded

If your JavaScript has this function, it will get called when a page containing a map, gallery, or data sheet has loaded and is ready to communicate with. The value of event.page.id is the Id of the map, gallery, or data sheet.

Normally a page loads so quickly that you don’t need to code this function; however, if your map has a large number of hotspots, you may need to wait for the map to finish loading before you begin using other API methods. Attempts to communicate with the map via the API before the map has loaded will have no effect and may trigger a JavaScript error.

Examples

function onEventPageLoaded(event) { ... }

onEventPageLoading

If your JavaScript has this function, it will get called when a page containing a map, gallery, or data sheet has started loading, but is not yet loaded and ready to use. The value of event.page.id is the Id of the map, gallery, or data sheet.

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

Examples

function onEventPageLoading(event) {
   let url = `https://myserver.com/service.php`;
   event.api.liveData.requestData("json", "", url, "map", event.page.id);
   event.api.waitingForLiveData(true);
}

onEventPopupClosed

If your JavaScript has this function, it will get called whenever a pinned popup is closed. The value of event.hotspot.id is the hotspot Id.

A pinned popup closes when you click its X or its pin icon, when the map is panned or zoomed, and when the directory is displayed. If a pinned popup is showing and you click on another marker that displays a pinned popup, the popup’s content changes, but the popup does not close and this function is not called (the onEventHotspotChanged callback function will be called).

To get additional information about the hotspot, use the API’s currentHotspot property.

Examples

function onEventPopupClosed(event) { ... }

onEventRequestLiveData

If your JavaScript has this function, it will get called when you tap or mouse over the marker that has a Live Data hotspot and does not specify a request function.

The event parameter contains information about the request. For example, the value of event.hotspot.id is the Id of the hotspot for which content is to be requested.

Examples

function onEventRequestHotspot(event) {
   let url = "https://livedata.mapsalive.com/php/demo/service.php";
   event.api.liveData.requestHotspot("json", 1, url, 'type', `hotspot-json`);
}

onEventTourLoaded

If your JavaScript has this function, it will get called when the tour has loaded and is ready to communicate with using the API. The Event object contains properties that specify which tour instance loaded.

You should wait until this event has occurred before making calls to the API object.

Examples

function onEventTourLoaded(event) { ... }

The onEventTourLoaded function is called near the end of the following runtime startup sequence:

  • The tour's runtime system is initialized
  • The tour's JavaScript from the Custom HTML screen is processed to append _##### to the end of each callback function (where ##### is the tour number)
  • The JavaScript is inserted into the DOM and interpreted
  • onEventTourLoaded is called
  • onEventPageLoading is called
  • onEventPageLoaded is called