${event.name}
`);
}
```
### Options
The `EventsManager` constructor accepts an optional `options` parameter. The following options are available:
```ts
/**
* Options for the {@link EventsManager}.
*/
export type EventsManagerOptions = Partial<{
/**
* The fields to fetch for each event.
*
* @default fields id, name, type, startDate, endDate, externalId, description, location, image, video
*/
fields: string[];
/**
* Whether to include past or expired events.
*
* @default false
*/
includeExpired: boolean;
}>;
```
### Methods
The `EventsManager` class provides the following methods:
```ts
class EventsManager {
/**
* Whether load() has been called and successfully completed.
*/
get ready(): boolean;
/**
* All current and future events that have been loaded. Will be empty if load() has not been called.
*/
get events(): EventMetaData[];
/**
* Load all the events for the map.
*/
async load(): void;
/**
* Get an event by ID.
*/
getById(id: string): EventMetaData | undefined;
/**
* Get an array of events attached to an EnterpriseLocation.
*/
getByLocationId(locationId: string): EventMetaData[];
/**
* Clean up the EventsManager instance.
*/
destroy(): void;
}
```
### Getting Started
# Getting Started
>
>
This getting started guide demonstrates how to start a project using Mappedin JS. Following this guide results in a working demo with a map that you can interact with (zoom, pan, rotate etc).
> Mappedin JS v6 is available as @mappedin/mappedin-js in NPM.
## Video Walkthrough
## Coding with AI
Mappedin JS provides an llms-mappedin-js.txt file that can be used to help with coding when using Large Language Models (LLMs).
## Local Development
For local development, start a project using Vite. Refer to the Vite Getting Started guide for setup details. Guides are written in TypeScript (JavaScript), as the SDK is written in Typescript and uses comprehensive types.
### 1. Create a Project
> Note that Mappedin JS version 6 is currently in an beta state. Therefore you must append @beta when adding the Mappedin package. Failing to do so will add the current production release of version 5, which does not support maps in the Free, Plus, Advanced or Pro tiers.
Run these shell commands to set up a new project and install Mappedin JS.
```bash
yarn create vite mappedin-quickstart
cd mappedin-quickstart
yarn add @mappedin/mappedin-js@beta
```
### 2. Update index.html, main.ts
Modify & update the contents of `index.html` and `main.ts` to match the following.
```html title=index.html
${space.name}
`, {
interactive: true,
});
}
});
```
After enabling interactivity, click events on the marker can be captured using Mapview.on('click'). The TEvents object passed into the `on` method contains an array of markers that were clicked.
The following code sample captures the click event and checks if the user clicked on a marker. If they did, it logs the id of the marker that was clicked and removes it from the map.
```ts
// Act on the click event to log the id of the marker that was clicked and then remove it.
mapView.on('click', async (e) => {
if (e.markers.length > 0) {
console.log('Clicked on marker: ' + e.markers[0].id);
mapView.Markers.remove(e.markers[0]);
}
});
```
## Handling Click and Hover Events
Mappedin JS enables capturing and responding to click and hover events through its event handling system. After enabling interactivity, click or hover events on the space can be captured using MapView.on('click') or MapView.on('hover').
The TEvents `click` and `hover` events pass TClickPayload that contains the objects the user clicked or hovered on. It allows developers to obtain information about user interactions with various elements on the map, such as:
1. **blueDot**: A boolean value indicating if the user clicked on the blue dot.
2. **coordinate** - A Coordinate object that contains the latitude and longitude of the point where the user clicked.
3. **facades** - An array of Facade objects that were clicked.
4. **floors** - An array of Floor objects. If the map contains multiple floors, floors under the click point are included.
5. **labels** - An array of Label objects that were clicked.
6. **markers** - An array of Marker objects that were clicked.
7. **models** - An array of Model objects that were clicked.
8. **objects** - An array of MapObject objects that were clicked.
9. **paths** - An array of Path objects that were clicked.
10. **pointerEvent** - A PointerEvent object that contains the pointer event data.
11. **shapes** - An array of Shape objects that were clicked.
12. **spaces** - An array of Space objects that were clicked.
Use `Mapview.on('click')` or `Mapview.on('hover')` to capture click or hover events as shown below.
```ts
mapView.on('click', async (e) => {
// The user clicked!
});
mapView.on('hover', async (e) => {
// The user hovered!
});
```
The following code sample captures the click event and checks if the user clicked on a space. If they did, it creates a label with the space name. If the click was not on a space, it creates a label with the latitude and longitude the user clicked on.
```ts
// Act on the click event to create a label with the space name that was clicked.
// If the space has no name, use the coordinate.
mapView.on('click', async (e) => {
if (e.spaces[0].name) {
mapView.Labels.add(e.coordinate, e.spaces[0].name);
} else {
mapView.Labels.add(e.coordinate, 'Clicked: Lat: ' + e.coordinate.latitude + ' Lon: ' + e.coordinate.longitude);
}
});
```
The next CodeSanbox uses interactive markers and the `click` event. When a marker is clicked, it is removed.
### Labels
# Labels
>
>
Labels display text and images anchored to specific points on a map. They rotate, show, or hide based on priority and zoom level, providing information about location names, points of interest, and more.
Effective labels help apps convey additional information, such as room names, points of interest, main entrances, or other useful contextual details.
!Mappedin JS v6 Labels
> Note that the MapView class implements the Labels interface and exposes it as MapView.Labels. Use MapView.Labels to utilize Labels' methods.
## Video Walkthrough
## Displaying All Labels
To display all labels that have been added to the source map, use the all() method of the Labels interface. The following code sample demonstrates use of the `all()` method:
```ts
// Add all the labels to the map.
mapView.Labels.all();
```
```tsx
// https://docs.mappedin.com/react/v6/latest/classes/default.Labels.html#all
// https://docs.mappedin.com/react/v6/latest/functions/Label.html
// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);
// Add labels for all spaces
return (
<>
{spaces.map(space => (
))}
);
```
The opposite of the `all()` method is the removeAll() method, which removes all labels from the map.
```ts // Remove all the labels from the map. mapView.Labels.removeAll();
```
This is a Marker!
');
```
```tsx
// https://docs.mappedin.com/react/v6/latest/functions/Marker.html
// Get all spaces with names
const spaces = mapData.getByType('space').filter(space => space.name);
// Create markers for all spaces with its space name and make them interactive
return (
<>
{spaces.map(space => (
Marker Rank: ${RANKS[rank]}
{marker.text}
Rank: {marker.rank}
Enabled Marker!
"
);
} else {
// get current state of marker
const markerState = mapView.getState(marker);
console.log("Current Marker State:", markerState);
// toggle enabled state
const newState = !markerState.enabled;
mapView.updateState(marker, { enabled: newState });
console.log(`Marker is now ${newState ? "enabled" : "disabled"}`);
}
});
```
```tsx
// https://docs.mappedin.com/react/v6/latest/types/default.TAddMarkerOptions.html
const [isEnabled, setIsEnabled] = useState(true);
const space = mapData?.getByType("space")[14];
useEvent("click", (event) => {
setIsEnabled(!isEnabled);
});
return (
Click to enable/disable marker
Primary: ${space.name}
`,
{ interactive: true, enabled: true }
)
);
// add & store secondary markers with references
const secondaryMarkers = mapData
.getByType("space")
.filter((space) => space.name !== "")
.slice(40, 60)
.map(async (space) => {
const marker = await mapView.Markers.add(
space,
`Secondary: ${space.name}
`,
{ interactive: true }
);
marker.markerInstance = markerObject; // store reference
mapView.updateState(marker, { enabled: false }); // init hide secondary markers
});
// update marker visibility based on zoom level
mapView.on("camera-change", (transform) => {
if (transform.zoomLevel < 19) {
secondaryMarkers.forEach((marker) => {
if (marker.markerInstance) {
mapView.updateState(marker.markerInstance, { enabled: false });
}
});
} else {
secondaryMarkers.forEach((marker) => {
mapView.updateState(marker.markerInstance, { enabled: true });
});
}
});
```
```tsx
// https://docs.mappedin.com/react/v6/latest/types/default.TAddMarkerOptions.html
const spaces = mapData.getByType('space')
const [secondaryMarkers, setSecondaryMarkers] = useState(
spaces.slice(5).map(space => ({
target: space,
text: space.name,
enabled: false
}))
);
useEvent('camera-change', (transform) => {
setSecondaryMarkers(markers =>
markers.map(marker => ({
...marker,
enabled: transform.zoomLevel >= 20
}))
);
});
return (
<>
{/* primary markers - always visible */}
{spaces.slice(0, 5).map(space => (
Loading...
;
}
if (error) {
return {error.message}
;
}
return mapData ? (
Loading...
;
}
if (error) {
return {error.message}
;
}
return mapData ? (
{space.name}
Animated Marker
Dynamic Marker
Departure
');
return marker;
},
destination: (instruction: TDirectionInstruction) => {
const marker = mapView.Markers.add(instruction.coordinate, 'Destination
');
return marker;
},
connection: (instruction: TDirectionInstruction) => {
const marker = mapView.Markers.add(instruction.coordinate, 'Connection
');
return marker;
},
},
};
mapView.Navigation.draw(directions, navigationOptions);
```
## Navigating From a Click Event
A navigation start or end point may originate from a user clicking on the map. It is possible to create a start and or end point using the click event and accessing its TEvents payload. The code shown below uses the click position as a starting point to create directions. `nearRadius` and `farRadius` are described in the Path Styles section later in this guide.
```ts
mapView.on('click', async event => {
const clickedLocation = event.coordinate;
const destination = mapData.getByType('space').find(s => s.name === 'Gymnasium');
// If the destination is found, navigate to it.
if (destination) {
//Ensure that directions could be generated (user clicked on a navigable space).
const directions = mapData.getDirections(clickedLocation, destination);
if (directions) {
// Navigate from the clicked location to the gymnasium.
mapView.Navigation.draw(directions, {
pathOptions: {
nearRadius: 1,
farRadius: 1,
},
});
}
}
});
```
## Multi-Floor Wayfinding
Using Navigation, no additional work is needed to provide wayfinding between floors. Whenever a user needs to switch a floor, an interactive tooltip with an icon indicating the type of Connection (such as an elevator or stairs) will be drawn. By clicking or tapping the tooltip, the map view switches to the destination floor.
The following CodeSandbox gives an example of multi floor navigation.
## Multi-Destination Wayfinding
Multi-segment directions are directions that include multiple legs. They can be created by passing an array of destinations to MapData.getDirectionsMultiDestination().
```ts
// Pass an array of destinations to create multi-segment directions.
const directions = mapData.getDirectionsMultiDestination(departure, destinations);
```
The following CodeSandbox demonstrates how to create multi-segment directions and draw them using Navigation.
## Wayfinding Using Accessible Routes
When requesting directions, it is important to consider the needs of the user. Users with mobility restrictions may require a route that avoids stairs and escalators and instead uses ramps or elevators.
The getDirections method accepts TGetDirectionsOptions, which allows specifying whether an accessible route should be returned. By default, the shortest available route is chosen. The following code demonstrates how to request directions that make use of accessible routes.
```ts
const directions = await mapData.getDirections(space1, space2, { accessible: true });
```
## Drawing a Path
While Navigation provides a complete start and end navigation illustration, it may be desired to draw just the path. This can be done using `Paths`.
> Note that the **MapView** class implements the **Paths** interface and exposes it as **MapView.Paths**. Use **MapView.Paths** to utilize **Paths** methods.
Paths can be drawn from one coordinate to another using Paths.add(). If using just two coordinates, the path will be drawn straight between the two points. This may work for some scenarios, but in most cases an app will need to show the user their walking path, going through doors and avoiding walls and other objects. Such a path of coordinates can be created by calling the MapData.getDirections() method, passing in a start and end TNavigationTarget. Note that a Space requires an entrance to be used as a target.
The width of the path is set using the `nearRadius` and `farRadius` parameters. These values are in meters. `nearRadius` is the path width used at the lowest zoom level closest to the ground and `farRadius` is used at the highest zoom level. Additional path styles are outlined later in this guide in the Path Styles section.
```ts
// Get the directions between two spaces.
const directions = mapData.getDirections(startSpace, endSpace);
// Draw a path using the directions' coordinates array to show the route.
path = mapView.Paths.add(directions.coordinates, {
nearRadius: 0.5,
farRadius: 0.5,
});
```
The following CodeSandbox draws a path from one location to another. Click on a room to set the departure point, then click another room to set the destination. When a path is shown, clicking anywhere will remove it.
## Removing Paths
There are two methods that can be used to remove paths. Paths.remove() accepts a path to remove and is used to remove a single path. To remove all paths, Paths.removeAll() can be used.
```ts
// Remove a single path.
mapView.Paths.remove(path);
```
```ts
// Remove all paths
mapView.Paths.removeAll();
```
## Path Styles
Mappedin JS offers many options to customise how paths appear to the user. Path animations, color, width and many more options can be set using TAddPathOptions.
## Dynamic Routing
When generating directions, Mappedin JS provides the most direct route possible between the origin and destination. There can be scenarios when this is not desired, such as when there there is an obstruction like a spill that requires cleaning or where maintenance crews are active.
The MapData.getDirections() method accepts a `zones` parameter that denotes areas that could be avoided. Zones are defined using TDirectionZone and contain a `cost`, `floor` and `geometry`.
`cost` represents the additional cost for navigation through the zone and can range from from 0 to Infinity. A cost of 0 will make the zone free to navigate through. A zone cost of Infinity will block passage through the zone. Multiple zones occupying the same location they are added together, along with the cost from the map. The SDK may route directions through a zone if all other routes have a higher cost.
`floor` represents the floor for the zone. If not specified the zone blocks all floors.
`geometry` is held within a Feature that contains a MultiPolygon or Polygon.
The following CodeSandbox demonstrates the use of zones to alter directions. Left click to add a zone with a cost of 10. Right click to add a zone with a cost of Infinity. Middle click to clear all zones. Try stacking multiple zones on top of each other and observe how the lowest cost route is used.
## Turn-by-Turn Directions
Turn-by-Turn directions are a set of text instructions describing the route the user needs to take. An example is "Turn right and go 10 meters". These could be shown to the user in a list to give them an overview with all steps they need to take, or the current instruction could be displayed along with a map showing the next leg of their journey.
The code sample assembles these actions together and:
- Gets directions between the start and end TNavigationTarget.
- Draws a path using the directions' coordinates.
- Creates a Marker with textual turn-by-turn instructions for each leg in the journey. Refer to the Marker Guide for more information on using Markers.
```ts
// Get directions from the first space to the second space.
const directions = mapData.getDirections(firstSpace, secondSpace);
// Add a path from the first space to the second space.
mapView.Paths.add(directions.coordinates);
// Add markers for each direction instruction.
directions.instructions.forEach((instruction: TDirectionInstruction) => {
const markerTemplate = `
${instruction.action.type} ${instruction.action.bearing ?? ''} in ${Math.round( instruction.distance )} meters.