Getting Started
To work with the Plans JavaScript SDK, you require a viewer token. Viewer tokens are designed to control what information a user can access. They are associated with a specific resource, and give the user access to only that resource, or all of its children as well. The Locatrix resource hierarchy is made up of Clients, Campuses, Buildings and Floors. If the viewer token is for a campus, the user can use this token to access all available floor plans within this campus, as well as the site plan. A floor viewer token, on the other hand, only allows access to one specific floor plan.
The following examples show how to use a viewer token to retrieve site information and floor plans, then display a plan to your website.
Starter Template
Ensure the Plans JavaScript SDK is loaded in your page before attempting to access any of the locatrix.plans API.
<!DOCTYPE html>
<html>
<head>
<title>SDK Sample</title>
<script src="https://api.locatrix.com/plans-javascript/v1/sdk.js"></script>
</head>
<body>
<script>
// you can now access the SDK using `locatrix.plans`
</script>
</body>
</html>
Listing All Available Resources
The resource code that has been used to generate a viewer token will limit the level of access. If you want to know the site information that a viewer token has access to, you can get the full list using the locatrix.plans.loadHierarchy API. Please check the Hierarchy docs for more information.
locatrix.plans.loadHierarchy(VIEWER_TOKEN).then(function (hierarchy) {
console.log(hierarchy)
})
If you have a viewer token for a building, loading the hierarchy will show basic information about the building’s client and campus, the building itself, all of its floors and all floor plan codes. The response structure when loading the hierarchy using a building viewer token is shown below. The result does not include the site plan (the campus’ planCode is null) or other buildings in this campus.
{
"clients": [
{
"code": "clnt_xxx01",
"name": "Client name",
"campuses": [
{
"code": "camp_xxx01",
"name": "Campus name",
"address": "address",
"postCode": "4000",
"planCode": null,
"buildings": [
{
"code": "bld_xxx01",
"name": "Building name",
"address": "address",
"postCode": "4000",
"floors": [
{
"code": "flr_xxx01",
"name": "Floor name 01",
"planCode": "pln_xxx001"
},
{
"code": "flr_xxx02",
"name": "Floor name 02",
"planCode": "pln_xxx002"
}
]
}
]
}
]
}
]
}
Using the Viewer
Viewer objects are used for rendering and interacting with plans. During instantiation, you must specify a <div> element to use as the viewer area. Then you can use viewer.loadPlan to display the plan in the viewer area using a valid plan code from the previous step.
<!DOCTYPE html>
<html>
<head>
<title>SDK Sample</title>
<script src="https://api.locatrix.com/plans-javascript/v1/sdk.js"></script>
</head>
<body>
<div id="viewer" style="width: 100%; height: 550px; border: 1px solid black;"></div>
<script>
const VIEWER_TOKEN = ''
var viewer = new locatrix.plans.Viewer(document.querySelector('#viewer'))
viewer.loadPlan(VIEWER_TOKEN, { planCode: 'pln_xxx001', enableAllIcons: true, useNaturalRotation: true, stabilizeIconsWhilePanning: false, enableWorldPaths: true })
</script>
</body>
</html>
Displaying a Random Floor Plan
This example shows a simple way to handle requests. Once viewer.loadPlan is completed, the plan will be displayed in the destination area.
...
<script>
function randomItem (items) {
return items[Math.floor(Math.random() * items.length)]
}
function loadRandomFloorPlan () {
locatrix.plans.loadHierarchy(VIEWER_TOKEN).then(function (hierarchy) {
let planCodes = []
for (const client of hierarchy.clients) {
for (const campus of client.campuses) {
for (const building of campus.buildings) {
for (const floor of building.floors) {
if (floor.planCode != null) {
planCodes.push({
floorPlanCode: floor.planCode,
sitePlanCode: campus.planCode
})
}
}
}
}
}
if (planCodes.length > 0) {
const planCode = randomItem(planCodes)
viewer.loadPlan(VIEWER_TOKEN, { planCode: planCode.floorPlanCode })
} else {
throw new Error('No floor plans found')
}
})
}
const VIEWER_TOKEN = ''
var viewer = new locatrix.plans.Viewer(document.querySelector('#viewer'))
loadRandomFloorPlan()
</script>
Using Viewer Widgets
Widgets are on-screen components, such as a mini map or north indicator, that are rendered within the Viewer to provide additional information or enhanced interactivity. The most important widget is the status indicator, which allows you to notify users of the current status using pre-defined styles. For example, you may want to show the user a loading spinner while loading the hierarchy data:
function loadRandomFloorPlan () {
// display spinner on viewer area
viewer.widgets.statusIndicator.setAppearance('spinner', 'Loading hierarchy...')
viewer.widgets.statusIndicator.setEnabled(true)
locatrix.plans.loadHierarchy(VIEWER_TOKEN).then(function (hierarchy) {
viewer.widgets.statusIndicator.reset()
viewer.widgets.statusIndicator.setEnabled(false)
...
}).catch(function (error) {
viewer.widgets.statusIndicator.setAppearance('error', error.message)
viewer.widgets.statusIndicator.setEnabled(true)
})
}
Displaying Another Plan
If you want to display the site plan along with the floor plan, simply create another Viewer and bind it to a different <div>:
...
<div id="viewer" style="width: 100%; height: 550px; border: 1px solid black;"></div>
<div id="siteviewer" style="width: 300px; height: 300px; display: inline-block; border: 1px solid black; vertical-align: top;"></div>
<script>
function loadRandomFloorPlan () {
...
viewer.loadPlan(VIEWER_TOKEN, { planCode: planCode.floorPlanCode })
siteviewer.loadPlan(VIEWER_TOKEN, { planCode: planCode.sitePlanCode })
...
}
var viewer = new locatrix.plans.Viewer(document.querySelector('#viewer'))
var siteviewer = new locatrix.plans.Viewer(document.querySelector('#siteviewer'))
loadRandomFloorPlan()
</script>
...
Full Example Code
Here is the completed example for you to play around with. The current SDK script points to the live environment with a sample viewer token.