Embedding the map viewer

Smplr.js makes a smplr object available on the global scope. One of the classes provided under this object is the Map class. It provides the API necessary to render the Smplrspace map viewer, a custom pre-configured Mapbox-based map which provide all the feature of Mapbox, plus Smplrspace specific features to render your spaces, add 3D cities based on OpenStreetMap data, add data layers, and more.

Constructor

To create a Map instance, initialise it as follow.

const map = new smplr.Map({
  clientToken: string
  containerId?: string
  container?: HTMLElement
  disableErrorReporting?: boolean
}) => Map

clientToken is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. More info.
containerId is the "id" of the html "div" container where smplr.js should render the viewer, something like "smplr-container" that can be found in your html. Only ids are supported, not classes.
container is an alternative to containerId that lets you provide the HTML element directly instead of an id.
disableErrorReporting - optional - can be set to "true" to disable the automated reporting of errors to our 3rd party error tracking tool, Sentry. We have discovered that Sentry's instrumentation could make it seem as if all network requests originated from smplr.js. Unfortunately, there is nothing simple we can do on our side to avoid that. If this is an issue for you, you can disable Sentry altogether. The tradeoff is that we will not automatically detect errors hapenning in your integration, and you may need to be more proactive to report them for us to roll out fixes.

Interactive map viewer session

Start the viewer

To initiate an interactive viewer session, use the following code.

map.startViewer({
  spaceIds?: string[]
  osmBuildings?: boolean
  hash?: boolean
  fitNewSpacesInScreen?: boolean
  loadingMessage?: string
  forceLoader?: boolean
  onReady?: () => void
  onError?: (errorMessage: string) => void
  onSpaceClick?: ({ space, levelIndex }: { space: object | undefined; levelIndex: number }) => void
  hideNavigationButtons?: boolean
  hideLevelPicker?: boolean
  hideControls?: boolean
  controlsPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right'
  legendPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
}) => Promise<void>

spaceIds - optional - lets you specify the Smplrspace ID ("spc_xxx") of the spaces to render on the map when initializing the viewer. You can also do that dynamically as described on the Building page.
osmBuildings - optional - lets you choose whether to render or not cities in 3D. City buildings data comes from OpenStreetMap and is automatically rendered in 3D. You can also do that dynamically as described in 3D cities. Default value: true.
hash - optional - lets you choose whether to automatically sync the map location to the hash fragment of the page's URL. This makes it for easy to share links to specific map locations. It relies on Mapbox's corresponding parameter. Default value: false.
fitNewSpacesInScreen - optional - lets you choose whether to automatically recenter the map to fit all the spaces when the spaces rendered on the map change. You can also center the map using fitAllSpacesInScreen. Default value: true.
loadingMessage - optional - lets you override the text displayed while the space is loading. This can be change dynamically as well, see UI controls. Default value: "Loading map".
forceLoader - optional - provides programmatic control to whether the loader should be displayed or not. By default we display it while loading the map and initial spaces provided by spaceIds, but you can control this if you load your own data as well. This can be change dynamically as well, see UI controls. Default value: false.
onReady - optional - is called once the viewer's initial render is done. You may alternatively use the promise returned by startViewer, which resolves when the viewer is ready.
onError - optional - is called if an error occur while starting the viewer. You may alternatively use the promise returned by startViewer to catch errors.
onSpaceClick - optional - is called when the user clicks a 3D space, and provide data about which space and which level where clicked.
hideNavigationButtons - optional - set this to true if you want the user to control the camera but want to remove the navigation buttons. Mouse, touch and keyboard inputs will work while the buttons are hidden. Default value: false
hideLevelPicker - optional - set this to true if you want to remove the level picker from the viewer. Levels can still be controlled programmatically, so you could use your own buttons or logic. Default value: false
hideControls - optional - set this to true if you want to remove all control buttons from the viewer. Default value: false
controlsPosition - optional - lets you choose where the control buttons are rendered. Default value: 'center-right'
legendPosition - optional - lets you choose where the legend (if any is configured in the data layers) would be rendered. Default value: 'top-left'

Calling startViewer returns a Promise (MDN docs) which resolves when the viewer is ready. This lets you use Promise.then().catch() or async/await with a try/catch block to react when the viewer is ready, or to handle errors that may occur. It is an alternative to providing onReady and onError callback methods. You may choose the option that suits the most your environment or coding style.

Stop the viewer

To stop the viewer, dispose of resources it allocated, and clear the container in which it is rendered back to its original state, call the following function.

map.remove() => void

Check if the viewer is ready

To check if the viewer has finished initializing and is ready for API methods to be called, you can do:

map.isViewerStarted() => boolean

Picking mode

In order to know where a user clicks or taps on the map, you can enable picking mode. For example, this is useful if you have an admin interface to position items or draw on the map. Enabling picking mode is done as follows.

// call this after `onReady` has fired
map.enablePickingMode({
  onPick: ({ 
    coordinates: {
      lng: number
      lat: number
    }
    event: MapMouseEvent
  }) => void
}) => void

onPick is called each time a click/tap event fires:
- The coordinates object provides the location that was picked. It should be stored in your database and reused anytime you need to display data at this location.
- The event value is the event object fired by Mapbox and is documented here.

Disabling picking mode is done as follow. For example, you would call disablePickingMode inside the onPick handler if you want to process a single pick event.

map.disablePickingMode() => void

You may refer to the Add data elements example to see picking mode in action and understand the API. The example uses the space viewer, but the concepts are the same.

Render buildings

See the dedicated functions you can call to render buildings on this page.

Data layers

The map viewer includes a full SDK to render data layers. Learn more on this page.

Control the map location

Focus on a specific space

You can change automatically "fly" the map to a specific space, by providing the space's identifier as follow:

map.flyToSpace(spaceId: string, options?: EasingOptions) => void

spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx".
options - are camera animation options as per Mapbox's documentation. Search flyTo on that page in case it doesn't navigate to it automatically.

Fit all spaces in screen

You can change automatically "fly" the map to an overview point, showing all rendered spaces, as follow:

map.fitAllSpacesInScreen() => void

In case their is a single space rendered, this method will be equivalent to calling flyToSpace on that space.

UI controls

Change the loading message

You can change the loading message any time as follow. This doesn't impact whether the loader is displayed or not.

map.updateLoadingMessage(message: string) => void

Control the loader

You can control whether the loader is displayed or not anytime with the following functions.

map.showLoader() => void
map.hideLoader() => void

Full Mapbox SDK

The Smplrspace map viewer is built on top of Mapbox GL JS. We provide a number of features dedicated to Smplrspace use-cases, but you can also build anything you want by accessing the full Mapbox SDK as below:

map.mapbox() => mapboxgl.Map | undefined

The methods below are Smplrspace improved alternatives to the Mapbox ones.

Changing the map style

Mapbox provides a setStyle method which works, but we recommend using ours instead so the Smplrspace managed elements automatically adapt to the new style. You should call it as below:

map.setStyle(style: string) => void

style is a mapbox style url like "mapbox://styles/mapbox/satellite-streets-v12"

and you can use the below to revert to the default Smplrspace style:

map.setDefaultStyle() => void

Constructor​

Interactive map viewer session​

Start the viewer​

Stop the viewer​

Check if the viewer is ready​

Picking mode​

Render buildings​

Data layers​

Control the map location​

Focus on a specific space​

Fit all spaces in screen​

UI controls​

Change the loading message​

Control the loader​

Full Mapbox SDK​

Changing the map style​