Map Views

Map view helpers let you capture and restore a map "snapshot" for users. A map view can include camera position, zoom, tilt, bearing, enabled layers, map filters, and basemap, depending on the options you choose.

Why you'd use these helpers

• Save named views users can quickly return to.
• Restore a known map state before a workflow starts.
• Persist personal defaults for repeatable day-to-day tasks.
• Capture only the parts of map state you care about (for example camera only, or full state).

Usage pattern

const control = globalThis.MaptaskrControlManager.getControl(controlId);

All examples below assume you already have a valid control reference.

Types

export interface CustomMapView {
	viewId?: string;
	viewName: string;
	isDefault?: boolean;
	options?: CustomCreateMapViewOptions;
}

export interface CustomCreateMapViewOptions {
	includePosition?: boolean; // default true
	includeZoom?: boolean; // default true
	includeTilt?: boolean; // default true
	includeBearing?: boolean; // default true
	includeLayers?: boolean; // default true
	includeMapFilters?: boolean; // default true
	includeBasemap?: boolean; // default true
}

API reference

getMapViews

List all map views visible to the current user in the current map context.

Parameters: None

Returns: CustomMapView[]

Usage:

const views = control.getMapViews();

views.forEach((view) => {
	console.log(`${view.viewName} (${view.viewId}) default=${Boolean(view.isDefault)}`);
});

---

addOrUpdateMapView

Create a new map view or update an existing one by ID.

When updating, the current map state is captured again using the supplied include options.

Parameter: customMapView (CustomMapView)

Field	Type	Required	Description
viewId	string	No	If provided and found, updates that view. If omitted/empty, creates a new view.
viewName	string	Yes	Display name for the view.
isDefault	boolean	No	Optional convenience flag for create/update flows. Prefer setDefaultMapView or clearDefaultMapView when only changing default assignment.
options	CustomCreateMapViewOptions	No	Controls which parts of state are captured. Omitted fields default to true.

Returns: Promise<CustomMapView>

Usage - create a full-state view:

const created = await control.addOrUpdateMapView({
	viewName: 'Dispatch Board - Full State',
	isDefault: false,
	options: {
		includePosition: true,
		includeZoom: true,
		includeTilt: true,
		includeBearing: true,
		includeLayers: true,
		includeMapFilters: true,
		includeBasemap: true,
	},
});

console.log('Created view:', created.viewId, created.viewName);

Usage - create a camera-only view:

const cameraView = await control.addOrUpdateMapView({
	viewName: 'Morning Standup Camera',
	options: {
		includePosition: true,
		includeZoom: true,
		includeTilt: false,
		includeBearing: false,
		includeLayers: false,
		includeMapFilters: false,
		includeBasemap: false,
	},
});

Usage - update an existing view:

const views = control.getMapViews();
const existing = views.find((v) => v.viewName === 'Dispatch Board - Full State');

if (existing?.viewId) {
	const updated = await control.addOrUpdateMapView({
		viewId: existing.viewId,
		viewName: 'Dispatch Board - Full State (Updated)',
		isDefault: existing.isDefault,
		options: existing.options,
	});

	console.log('Updated:', updated.viewId, 'default=', updated.isDefault);
}

note

• For create operations, the service generates and returns a safe viewId.
• Treat the returned viewId as the canonical ID for future updates, apply, and delete calls.
• Use setDefaultMapView and clearDefaultMapView to change default assignment without recapturing or altering saved view content.

---

deleteMapView

Delete a map view by ID.

If the ID does not exist, this is a no-op.

Parameters:

Field	Type	Required	Description
viewId	string	Yes	ID of the view to remove.

Returns: Promise<void>

Usage:

const views = control.getMapViews();
const temp = views.find((v) => v.viewName === 'Temporary View');

if (temp?.viewId) {
	await control.deleteMapView(temp.viewId);
	console.log('Deleted view:', temp.viewName);
}

---

getAppliedMapView

Return the view currently applied to the map, if any.

Parameters: None

Returns: CustomMapView | undefined

Usage:

const applied = control.getAppliedMapView();

if (!applied) {
	console.log('No map view is currently applied.');
} else {
	console.log('Applied view:', applied.viewName, applied.viewId);
}

---

applyMapView

Apply a saved map view by ID.

Depending on the view options captured, this may restore camera position, layers, filters, and basemap.

Parameters:

Field	Type	Required	Description
viewId	string	Yes	ID of the view to apply.

Returns: Promise<void>

Usage:

const views = control.getMapViews();
const defaultView = views.find((v) => v.isDefault);

if (defaultView?.viewId) {
	await control.applyMapView(defaultView.viewId);
	console.log('Applied default view:', defaultView.viewName);
}

---

setDefaultMapView

Set a specific saved view as the default without modifying any other part of that view.

Parameters:

Field	Type	Required	Description
viewId	string	Yes	ID of the view to set default.

Returns: Promise<void>

Usage:

const views = control.getMapViews();
const target = views.find((v) => v.viewName === 'My Workspace');

if (target?.viewId) {
	await control.setDefaultMapView(target.viewId);
	console.log('Default view set to:', target.viewName);
}

---

clearDefaultMapView

Clear the current default view assignment without changing any saved view content.

Parameters: None

Returns: Promise<void>

Usage:

await control.clearDefaultMapView();
console.log('Cleared default map view.');

Common workflows

Save or refresh "My workspace" view

const currentViews = control.getMapViews();
const existing = currentViews.find((v) => v.viewName === 'My Workspace');

const saved = await control.addOrUpdateMapView({
	viewId: existing?.viewId,
	viewName: 'My Workspace',
	options: {
		includePosition: true,
		includeZoom: true,
		includeTilt: true,
		includeBearing: true,
		includeLayers: true,
		includeMapFilters: true,
		includeBasemap: true,
	},
});

if (saved?.viewId) {
	await control.setDefaultMapView(saved.viewId);
}

console.log('Saved workspace view:', saved.viewId);

Apply view by name

async function applyViewByName(name: string) {
	const views = control.getMapViews();
	const match = views.find((v) => v.viewName === name);

	if (!match?.viewId) {
		console.warn(`Map view not found: ${name}`);
		return;
	}

	await control.applyMapView(match.viewId);
}

await applyViewByName('My Workspace');

Clear default view assignment

await control.clearDefaultMapView();
console.log('Cleared default map view assignment.');

Best practices

• Persist the returned viewId after create so you can safely update or apply later.
• Use setDefaultMapView and clearDefaultMapView when you only want to change default assignment.
• Use selective include flags for focused views (for example camera-only) to avoid unexpectedly changing layer/filter context.
• Wrap async calls in your own error handling when wiring into UI buttons or automation flows.
• Prefer stable naming conventions for views (for example team, role, or workflow specific prefixes).