Web Map Template
Get started quickly with a MapsIndoors powered template web app.
Getting Started
We recommend using the latest LTS version of Node.js.
Using a terminal/shell in the project folder, run the following commands:
- Clone the repository to your development environment:
- You can use both the
SSH
orHTTPS
to clone the repository, depending on which one you are more familiar with.
git clone https://github.com/MapsPeople/web-ui.git
- Inside the project folder root, install all dependencies and build with Lerna:
cd web-ui && npm install && npx lerna run build
- Move to the
packages/map-template
directory and run the app:
cd packages/map-template && npm run start
Now open the app served on http://localhost:3000/.
Add Google Maps API Keys or Mapbox Access Tokens
Rename .env.example
, to .env
and add either of the keys (or both) to that file, and the maps will load properly.
Configuration
Working on Components used in Map Template
To have any Stencil component changes reflected in this project, you must run npx lerna run build
from the root folder. There are no watch scripts yet.
Supported properties on the MapsIndoors Map component
The MapsIndoors Map component supports a list of props (see the list below) that can be configured in the App.jsx
file.
When loading the MapsIndoors Map component for the first time, the map will respect the default values set for the apiKey
, venue
, logo
and primaryColor
props, which can be found in the MapsIndoorsMap.jsx
file under the defaultProps
object.
Note that when using the React component, the properties should conform to JSX prop naming, eg. api-key
becomes apiKey
.
Attribute | React prop name | Type | Description |
---|---|---|---|
api-key | apiKey | string | The MapsIndoors Solution you want to load. Takes both API key as string and "App alias". |
gm-api-key | gmApiKey | string | Your Google Maps API key. |
mapbox-access-token | mapboxAccessToken | string | Your Mapbox Access Token. Setting it will load a Mapbox map. If you set both a Mapbox Access Token and Google Maps API key, the Mapbox Access Token takes precedence. |
venue | venue | string | The Venue to load from your MapsIndoors Solution. |
location-id | locationId | string | Set a MapsIndoors Location ID to show it on the map and its details in the sheet. |
primary-color | primaryColor | string | The primary color to use throughout the app. |
logo | logo | string | The logo to show during initial load. |
app-user-roles | appUserRoles | array | A list of App User Roles to apply when loading data. Used like so: appUserRoles={["App User Role"]} |
directions-from | directionsFrom | string | Set a MapsIndoors Location ID to be used as origin to instantly show directions. |
directions-to | directionsTo | string | Set a MapsIndoors Location ID to be used as destination to instantly show directions. |
external-IDs | etxternalIDs | array | Array of external IDs which filters the map and shows a list of locations. Because of the way browsers work, you can not use External IDs with the , , & , # and + , character in them, as they are interpreted by the browser in a particular way. |
tile-style | tileStyle | string | Name of Tile Style to display on the map. |
start-zoom-level | startZoomLevel | number | The initial zoom level of the map. |
supports-url-parameters | supportsUrlParameters | bool | Indicates if the Map Template supports URL parameters. |
gm-map-id | gmMapId | string | The Google Maps Map ID associated with a specific map style or feature. |
Deploying Map Template to a cloud storage provider
We often use Google Cloud Storage (GCS) for deploying small useful apps for demo purposes. This guide refers to GCS, but many of the steps are identical for AWS, Azure Blob, and the like.
Running the regular build command (npm run build
), it's assumed that all links refer to the root of a domain. When you deploy to a storage bucket, you need to build the app with the bucket name preprended to all links. Vite has a build option to take care of this:
npx vite build --base=/YOUR_BUCKET_NAME
At this point you can upload the files manually to your bucket, or use the helpful CLI gsutil
for the purpose. This command uploads the complete build
folder, and prevents the files from being cached:
gsutil -m -h "Cache-Control:public, max-age=0, no-store, no-cache" cp -r build gs://YOUR_BUCKET_NAME
Web Component: Installation and usage
Using NPM
Install the package:
npm install @mapsindoors/map-template
In your script:
import MapsIndoorsMap from '@mapsindoors/map-template@stable/dist/mapsindoors-webcomponent.es.js';
window.customElements.define('mapsindoors-map', MapsIndoorsMap);
In your styles make sure to give it a size. For example:
mapsindoors-map {
display: block;
width: 100vw;
height: 100vh;
}
Make sure the MapsIndoors JavaScript SDK is loaded by having this somewhere in your HTML:
<script src="https://app.mapsindoors.com/mapsindoors/js/sdk/4.21.5/mapsindoors-4.21.5.js.gz"></script>
Use the Web Component in your HTML:
<mapsindoors-map></mapsindoors-map>
Add attributes to the Web Component as needed (see supported properties below).
Note! The external-IDs
and app-user-roles
expect an array, which in a Web Component is handled differently (see example below).
In your script, define the array of external IDs that you want to be shown on the Map Template. Then get a hold of the mapsIndoorsMapElement
using the document.querySelector()
method. When you have the mapsIndoorsMapElement
, assign its prop externalIDs
the array of External IDs that you defined at the beginning.
const externalIDsArray = ["externalID-1", "externalID-2"]
const mapsIndoorsMapElement = document.querySelector('mapsindoors-map')
mapsIndoorsMapElement.externalIDs = externalIDsArray;
Use query parameters to configure the Web Component by setting the supports-url-parameters
attribute to true
.
Using just the browser
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MapsIndoors Map Template</title>
<script src="https://app.mapsindoors.com/mapsindoors/js/sdk/4.21.5/mapsindoors-4.21.5.js.gz"></script>
<script type="module">
import MapsindoorsMap from 'https://www.unpkg.com/@mapsindoors/map-template@stable/dist/mapsindoors-webcomponent.es.js';
window.customElements.define('mapsindoors-map', MapsindoorsMap)
</script>
<style>
body {
margin: 0;
}
mapsindoors-map {
display: block;
width: 100vw;
height: 100vh;
}
</style>
</head>
<body>
<mapsindoors-map></mapsindoors-map>
</body>
</html>
Add attributes to the Web Component as needed (see supported properties above).
Use query parameters to configure the Web Component by setting the supports-url-parameters
attribute to true
.
React component: Installation and usage
Using NPM
Install the package:
npm install @mapsindoors/map-template
Make sure the MapsIndoors JavaScript SDK is loaded by having this somewhere in your HTML:
<script src="https://app.mapsindoors.com/mapsindoors/js/sdk/4.21.5/mapsindoors-4.21.5.js.gz"></script>
Use the MapsIndoorsMap
component in a React component:
import MapsIndoorsMap from '@mapsindoors/map-template@stable/dist/mapsindoors-react.es.js';
// Somewhere in your JSX:
<div style={{
display: 'block',
width: '100vw',
height: '100vh'
}}>
<MapsIndoorsMap></MapsIndoorsMap>
</div>
Add properties to the MapsIndoorsMap component as needed (see list above).
Use query parameters to configure the MapsIndoorsMap component by setting the supportsUrlParameters
prop to true
.
Query Parameters
The Map Template supports using query parameters for all the properties provided by the MapsIndoorsMap component if the supportsUrlParameters
property is set to true.
In addition, the Web component and the React component also support using the URL parameters if the supports-url-parameters
attribute or the supportsUrlParameters
prop is set to true
.
The supported query parameters are the following:
apiKey
- Used like thisapiKey=yourApiKey
. If no apiKey is provided, the app will default to3ddemo
.venue
- Used like thisvenue=yourVenueName
- the Venue property is case sensitive. If no venue is provided, the app will select the first venue from the solution in alphabetical order.locationId
- Used like thislocationId=yourLocationId
primaryColor
- Used like thisprimaryColor=000000
. Note! You need to provide a hex color value, without the#
, due to the hashtag being a reserved symbol that has a predefined purpose in a query string. If no primary color is provided, the app will default to the MapsPeople brand color.logo
- Used like thislogo=https://images.g2crowd.com/uploads/product/image/social_landscape/social_landscape_7a75ff13f42605422950b411ab7e03b5/mapspeople.png
. Use an image address to provide a different logo on the loading screen. If no logo is provided, the app will default to the MapsPeople icon.appUserRoles
- Used like thisappUserRoles=visitor,staff,security
- the App User Roles are case sensitive. Note! You need to provide a list of comma separated values, without any spaces between the comma and the value. This will further be converted into an array of appUserRoles.directionsFrom
- Used like thisdirectionsFrom=yourOriginLocationId
when having a location ID, or like thisdirectionsFrom=USER_POSITION
when having the user location. Using thedirectionsFrom
property in the URL followed by the selection of a destination location in the search view results in the wayfinding having both the origin and the destination prefilled.directionsTo
- Used like thisdirectionsTo=yourDestinationLocationId
when having a location ID, or like thisdirectionsTo=USER_POSITION
when having the user location.externalIDs
- Used like thisexternalIDs=0.0.1,0.0.2,0.0.3
. Note! You need to provide a list of comma separated values, without any spaces between the comma and the value. This will further be converted into an array of external IDs. Because of the way browsers work, you cannot use External IDs with the,
,&
,#
and+
, character in them, as they are interpreted by the browser in a particular way.tileStyle
- Used like thistileStyle=yourTileStyleName
. If no tile style is provided, the app will show the default tile style.mapboxAccessToken
- Used like thismapboxAccessToken=yourMapboxAccessToken
. If no mapboxAccessToken is provided, the app will default to the access token in the .env file. If both the mapboxAccessToken and the gmApiKey are present, the app will load a Mapbox map.gmApiKey
- Used like thisgmApiKey=yourGmApiKey
. If no gmApiKey is provided, the app will default to the access token in the.env
file. If both the mapboxAccessToken and the gmApiKey are present, the app will load a Mapbox map.startZoomLevel
- Used like thisstartZoomLevel=22
.gmMapId
- Used like thisgmMapId=yourGmMapId
.
Note! All the query parameters need to be separated with the &
symbol, without any spaces in between.
Note! When using parameters such as directionsTo
, directionsFrom
, locationId
, externalIDs
, and tileStyle
make sure you are using the correct apiKey
parameter to which they belong.
Note! When using the gmMapId
property, you need to use it together with the gmApiKey
that it is associated with.
Example of URL:
https://domain.com/?apiKey=yourApiKey&venue=yourVenueName&locationId=yourLocationId&primaryColor=000000&logo=https://images.g2crowd.com/uploads/product/image/social_landscape/social_landscape_7a75ff13f42605422950b411ab7e03b5/mapspeople.png&appUserRoles=visitor,staff,security
Important! Not all the query parameters can be used together, as they serve their own purpose which in some cases overlaps with other query parameters. Example of cases that DON’T work together:
locationId
+ startZoomLevel
→ the startZoomLevel
has priority over the locationId
locationId
+ externalIDs
→ the locationId
has priority over the externalIDs
directionsTo
+ directionsFrom
+ locationId
→ the directionsTo
+ directionsFrom
have priority over the locationId
directionsTo
+ directionsFrom
+ externalIDs → the directionsTo
+ directionsFrom
have priority over the externalIDs