@mapsindoors/built-in-map-edits

The @mapsindoors/built-in-map-edits package provides a robust API for developers to build custom map management tools. Directly access and modify MapsIndoors data within your applications. Streamline workflows and enhance user experiences.

Reference documentation can be found here: https://app.mapsindoors.com/mapsindoors/js/bime/latest/

Install

You can add the @mapsindoors/built-in-map-edits package to your project using npm or yarn:

NPM https://npmjs.org/:

npm install @mapsindoors/built-in-map-edits

Yarn https://yarnpkg.com/:

yarn add @mapsindoors/built-in-map-edits

Usage

Obtaining an Access Token

To interact with the MapsIndoors API, you need an access token. This example demonstrates how to obtain an access token using the OAuth Resource Owner Password Credentials Grant flow. This should only be used for development or testing purposes.

Warning: Do not use this method in production! Never hardcode your MapsIndoors username and password directly into your client-side code. This example is for development/testing purposes only. Use a secure backend service to handle authentication.

const response = await fetch('https://auth.mapsindoors.com/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
        'grant_type': 'password',
        'client_id': 'client',
        'username': '<YOUR_USERNAME>', // Replace <YOUR_USERNAME> with your MapsIndoors username.
        'password': '<YOUR_PASSWORD>' // Replace <YOUR_PASSWORD> with your MapsIndoors password.
    })
});

if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
}

const data = await response.json();
const accessToken = data.access_token;

List Available Solutions

In MapsIndoors, a Solution is the starting point for working with your organization's MapsIndoors data. Before opening a specific solution by its ID, you might need to find out which solutions are available.

You can retrieve a list of available MapsIndoors solutions that the access token grants access to using the getAvailableSolutions() method:

import { MapsIndoorsEditor } from '@mapsindoors/built-in-map-edits';

MapsIndoorsEditor.accessToken = accessToken;

const availableSolutions = await MapsIndoorsEditor.getAvailableSolutions();

for (const { name, id } of availableSolutions) {
    console.log(`Solution: ${name} - (${id})`);
}

Note: The MapsIndoorsEditor.accessToken must be set before any authenticated API calls are made with MapsIndoorsEditor.

Obtaining a SolutionManager

To interact with the data (like Locations and Types) within a specific MapsIndoors Solution, you first need a SolutionManager instance. This object provides the methods for accessing and modifying data.

There are two primary ways to obtain a SolutionManager:

1. Open by Solution ID: Use this method if you know the ID of the MapsIndoors Solution you want to edit.

2. Connect to an SDK Instance: Use this method if you are integrating the editor with an existing MapsIndoors Web SDK map display.

Choose one of the following methods based on your use case:

Note: Both examples are a continuation of the example found in Obtaining an Access Token

Method 1: Opening a Solution by ID (open)

If you have the ID of the specific MapsIndoors solution you want to manage (perhaps obtained using getAvailableSolutions() above), you can use the MapsIndoorsEditor.open() method.

import { MapsIndoorsEditor } from '@mapsindoors/built-in-map-edits';

MapsIndoorsEditor.accessToken = accessToken;

const solutionIdToOpen = 'YOUR_SOLUTION_ID';

try {
    const solutionManager = await MapsIndoorsEditor.open(solutionIdToOpen);
    console.log(`Successfully opened solution: ${solutionManager.solutionId}`);
    // Now you can use solutionManager to interact with the solution's data.
} catch (error) {
    // Handle errors (e.g., invalid token, invalid ID, network issues)
    console.error(`Failed to open solution ${solutionIdToOpen}:`, error);
}

Replace 'YOUR_SOLUTION_ID' with your desired solution ID.

This method returns a SolutionManager promise, which resolves once the necessary solution configuration is loaded.

Method 2: Connecting to an Existing SDK Instance (connect)

If you are integrating these editing capabilities into an application that already uses the MapsIndoors Web SDK (v4.39.1 or later), you can use the MapsIndoorsEditor.connect() method. This approach leverages the existing SDK instance, automatically determining the correct solutionId.

This is particularly useful for building interactive editing tools where changes can be visualized directly on the map provided by the SDK.

Note: In this example it is assumed that mapsIndoorsInstance is a reference to an existing MapsIndoors SDK instance.

import { MapsIndoorsEditor } from '@mapsindoors/built-in-map-edits';

MapsIndoorsEditor.accessToken = accessToken;

try {
    // Pass your existing MapsIndoors SDK instance to connect
    const solutionManager = await MapsIndoorsEditor.connect(mapsIndoorsInstance);
    console.log(`Successfully connected to SDK solution: ${solutionManager.solutionId}`);
    // Now you can use solutionManager to interact with the solution's data.
} catch (error) {
    // Handle errors (e.g., invalid token, invalid ID, network issues)
    console.error('Failed to connect to MapsIndoors SDK instance:', error);
}

The minimum supported MapsIndoors SDK version is v4.39.1. For more information about the MapsIndoors SDK, see the MapsIndoors SDK documentation.

Like open(), this method also returns a SolutionManager promise.

Important: You only need to use either open() or connect() to get your SolutionManager. The subsequent examples in this README assume you have obtained a solutionManager variable using one of these two methods.

List Available Location Types

The SolutionManager.locationTypes property provides a list of Location Types configured within the current solution. This list can be used for populating a select list or dropdown menu in your application's user interface. This allows users to easily select valid location types when creating or modifying locations, improving the user experience. The names are displayed in the solution's default language.

const locationTypes = solutionManager.locationTypes;

for(const [key, type] of locationTypes) {
    // Find the translation object that matches the solution's default language
    const translation = type.translations.find(translation => translation.language === solutionManager.defaultLanguage);

    console.log(`Location Type: ${key} - ${translation?.name}`);
}

Update a Location's Type

Change the type of an existing Location using a location type key obtained from the SolutionManager.locationTypes list.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

await locationEditor
    .setType('LOCATION_TYPE_KEY')
    .save();

Remember to replace 'LOCATION_ID' and 'LOCATION_TYPE_KEY' with your actual values.

Update a Location's Name and Description

Set localized names and descriptions for a specific location across all available languages.

const availableLanguages = solutionManager.availableLanguages;
const locationEditor = await solutionManager.getLocation('LOCATION_ID');

for(const language of availableLanguages) {
    locationEditor
        .setName(language, 'LANGUAGE_SPECIFIC_NAME')
        .setDescription(language, 'LANGUAGE_SPECIFIC_DESCRIPTION');
}

await locationEditor.save();

Remember to replace 'LOCATION_ID', 'LANGUAGE_SPECIFIC_NAME', and 'LANGUAGE_SPECIFIC_DESCRIPTION' with your actual values.

Update a Location's ExternalID

Set or update the external ID for a specific location, typically used to link MapsIndoors locations with external systems or identifiers.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

let externalId = locationEditor.getExternalId();

locationEditor.setExternalId('NEW_EXTERNAL_ID')

await locationEditor.save();

Remember to replace 'LOCATION_ID', and 'NEW_EXTERNAL_ID' with your actual values.

Note:

• locationEditor.getExternalId() returns null if no external ID is set.
• locationEditor.setExternalId() with no argument or with null will reset the external ID to null.
• Only string values are accepted for setExternalId. Passing a non-string value will throw an error.

Creating a new Location

You can create a new Location by calling solutionManager.createLocation() with the required data. This method returns a LocationEditor instance, which you can further modify and then save.

// Example: Creating a new Location
const newLocationData = {
    geometry: {
        type: 'Point',
        coordinates: [longitude, latitude] // Replace longitude, latitude with actual coordinates
    },
    floor: mapsIndoorsInstance.getFloor(), // Get the current floor index from MapsIndoors, if available, else set it to the desired floor index.
    type: 'LOCATION_TYPE_KEY', // Replace LOCATION_TYPE_KEY with a valid type key from solutionManager.locationTypes
};

const locationEditor = await solutionManager.createLocation(newLocationData);

// Set the name and description
locationEditor
    .setName('en', 'Parking')
    .setDescription('en', 'Parking area for visitors');

// Save the new Location to persist it
await locationEditor.save();

console.log('Location created with ID:', locationEditor.id);

• You can use solutionManager.locationTypes to get valid type keys.
• The translations array should include at least one language with a name.

Deleting a Location

To delete a location, simply call the delete() method on the LocationEditor.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');
if(confirm('Are you sure you want to delete this Location? This action is permanent.')) {
    try {
        await locationEditor.delete();
        console.log('Location deleted successfully.');
    } catch (error) {
        console.error('Error deleting location:', error);
        alert('Failed to delete location. Please try again.');
    }
}

Note: Deleting a Location is a permanent operation and cannot be undone.
It is the responsibility of the implementing developer to put appropriate safeguards in place—such as confirmation dialogs, permission checks, or undo mechanisms—to prevent accidental or unauthorized deletion of Locations.
Always ensure that users are clearly informed and have explicitly confirmed their intent before performing a delete operation.

Retrieving a LocationEditor on Click

Here is an example demonstrating how to set up an event listener for click events on the map. It leverages the native Mapbox click event to provide the click's geographic coordinates, enabling the creation of new Locations at that position. It also allows you to query Mapbox to determine if an existing MapsIndoors Location was clicked, which can then be used to retrieve a LocationEditor for that selected Location.

This example assumes you have a working MapsIndoors Web SDK integration. If you're new to the SDK, please refer to the MapsIndoors Web SDK Tutorial for setup and basic usage instructions.

Set up a click event listener to retrieve a LocationEditor instance for the clicked location. This allows you to interact with the location programmatically.

Note: This example is a continuation of the example found in Method 2: Connecting to an Existing SDK Instance (connect)

const map = mapsIndoorsInstance.getMap(); // Get the Mapbox map instance from MapsIndoors SDK
let locationEditor = null; // Declare the locationEditor variable here to be accessible within the scope
const locationTypes = solutionManager.locationTypes; // Assuming this is where valid types come from

map.on('click', async (e) => {
    // Check for features at the clicked point.
    // The filter ensures that only clickable MapsIndoors features are considered,
    // excluding background elements like building outlines and floorplans.
    const features = e.target.queryRenderedFeatures(
        e.point,
        { filter: ['any',
            ['!=', ['get', 'clickable'], false],
            ['!', ['in', ['get', 'type'], ['literal', ['MI_BUILDING_OUTLINE', 'floorplan']]]]
        ] }
    ) ?? [];

    if (features.length === 0) {
        // If no features are found, create a new location at the clicked coordinates.
        const floor = mapsIndoorsInstance.getFloor();
        const type = locationTypes.get('Parking');
        locationEditor = await createLocation({lngLat: e.lngLat, type, floor });
        console.log('Created new location:', locationEditor);
    } else {
        // If features are found, get the first one (the clicked Location)
        // and load it into the editor using its originalId.
        const feature = features[0];
        locationEditor = await solutionManager.getLocation(feature.properties.originalId);
        console.log('Loaded existing location:', locationEditor);
    }
});

async function createLocation({lngLat, type, floor}) {
    return await solutionManager.createLocation({
        geometry: {
            type: 'Point',
            coordinates: [lngLat.lng, lngLat.lat]
        },
        floor,
        type
    });
}

Move a Location to Specific Coordinates

Move a location to a new latitude and longitude.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

locationEditor.moveTo({ lat: 55.6761, lng: 12.5683 });

await locationEditor.save();

Remember to replace 'LOCATION_ID' with your actual value.

Example: Interacting with a Single Location through the SDK

This example assumes you have a working MapsIndoors Web SDK integration. If you're new to the SDK, please refer to the MapsIndoors Web SDK Tutorial for setup and basic usage instructions.

This example demonstrates how to interact with a single location using the SolutionManager obtained from an existing SDK connection. It enables you to make a location draggable on the map, allowing for interactive movement.

Note: This example is a continuation of the example found in Retrieving a LocationEditor on Click

window.addEventListener('keydown', handleKeyDown);
window.addEventListener('keyup', handleKeyUp);

function handleKeyDown(e) {
    if(e.key !== 'd') {
        return;
    }
    
    if(!locationEditor) {
        return;
    }

    locationEditor.draggable = true;
}

function handleKeyUp(e) {
    if(e.key !== 'd') {
        return;
    }
    
    if(!locationEditor) {
        return;
    }
    
    locationEditor.draggable = false;
}

Remember to call await locationEditor.save(); to persist the changes.

Move a Location by Distance and Direction

Move a location a given distance (meters) in a specific direction (degrees), where the direction is measured clockwise from true north.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

// Move 10 meters in 45 degrees
locationEditor.move(10, 45); 

await locationEditor.save();

Remember to replace 'LOCATION_ID' with your actual value.

Rotate a Location

Rotate a location by a specified angle in degrees, measured clockwise from true north.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

locationEditor.rotate(90); // Rotate 90 degrees

await locationEditor.save();

Remember to replace 'LOCATION_ID' with your actual value.

Resetting Location Changes

The reset method in the LocationEditor class allows you to revert any changes made to a location back to its original state or the last saved state. This is useful when you want to discard any modifications and restore the location to its previous state, including its position and rotation.

To reset the changes made to a location, simply call the reset method on the LocationEditor instance. This will revert the location data to its original state and dispatch a change event to notify any listeners about the reset.

const locationEditor = await solutionManager.getLocation('LOCATION_ID');

// Set the name, description, position, and rotation for the location
locationEditor
    .setName('en', 'New Name')
    .setDescription('en', 'New Description')
    .moveTo({ lat: 55.6761, lng: 12.5683 })
    .rotate(90);

// Save the changes
await locationEditor.save();

// Make further changes
locationEditor
    .setName('en', 'Another Name')
    .setDescription('en', 'Another Description')
    .moveTo({ lat: 55.6762, lng: 12.5684 })
    .rotate(180);

// Reset the changes to the last saved state
locationEditor.reset();

Remember to replace 'LOCATION_ID' with your actual value.

License

MIT