UnitMap

The central class of the API — it is used to create a unitmap instance on a page and manipulate it.

// Initialize a `unitmap` instance on the `<div id="map">` element of the page:
var map = unitmap("map", "YOUR_API_KEY");

// Or you may pass an element reference directly:
var mapElement = document.getElementByid("map");
var map = unitmap(mapElement, "YOUR_API_KEY");

Creation

Options

UnitMap.load(mapId, [callback])

Loads a unit map by a given ID.

// Load the unit map with an ID of `1`:
map.load("1", function () {
  console.log("Map ready.");
});

// You can also listen for the `ready` event along with / instead of
// the load() callback:
map.on("ready", function (map) {
  console.log("Map ready (event).");
});

Arguments

UnitMap.units()

Returns a UnitSelection instance containing all Unit instances.

// Get a unit selection instance from the map:
var units = map.units();

// Color units with the ID's of `1`, `2`, and `3`. Review
// the UnitSelection documentation for further explanation:
units.find(["1", "2", "3"]).color("#000");

UnitMap.levels()

Returns a LevelSelection instance containing all Level instances.

🚧

Deprecated. Use floors() instead. The Levels API (levels(), Level, and LevelSelection) is deprecated in favor of the Floors API (floors(), Floor, and FloorSelection). This method is only available when the useFloors option is false; when useFloors is set (the default), it throws an error.

// Get a level selection instance from the map:
var levels = map.levels();

// Hide all levels with a `floor` tag except levels with a value of `1`:
levels.has({floor: true}).show().expect({floor: "1"}).hide();

UnitMap.floors()

Returns a FloorSelection instance containing all Floor instances.

📘

This method is only available when the useFloors option is true (the default). When useFloors is false, it throws an error — use levels() instead.

// Get a floor selection instance from the map:
var floors = map.floors();

// Show the floor with a `label` of `Floor 1`:
floors.where({ label: "Floor 1" }).show();

UnitMap.floor()

Returns the currently displayed Floor.

// Get the label of the currently displayed floor:
console.log(map.floor().label);

Returns

A new Floor instance.

UnitMap.nav()

Returns a Nav instance used to generate and render turn-by-turn directions. Can only be called the map has loaded.

map.on("ready", function () {
  var nav = map.nav();
});

Returns

A new Nav instance.

UnitMap.translate([point])

Performs a 2D transform to the given position if provided. Otherwise returns the current position value.

Arguments

Returns

Either an [x, y] coordinates Array of the current position or the object chain.

UnitMap.scale([scale])

Performs a 2D transform scaling to the given value when provided. Otherwise returns the current scale value.

// Set the scale to a factor of 1, representing the maps intrinsic size:
map.scale(1);

// Set the scale to a factor of 0.5, representing half of the maps intrinsic size:
map.scale(0.5);

// Set the scale to a factor of 2, representing double the maps intrinic size:
map.scale(2);

// Console log the map's current scale value.
console.log(map.scale());

Arguments

Returns

Either the current scale value or the object chain.

UnitMap.minScale([minScale])

Sets the minimum scale factor to the given value when provided. Otherwise returns the current minimum scale factor value.

Arguments

Returns

Either the current minimum scale factor value or the object chain.

UnitMap.maxScale([maxScale])

Sets the maximum scale factor to the given value when provided. Otherwise returns the current maximum scale factor value.

Arguments

Returns

Either the current minimum scale factor value or the object chain.

UnitMap.zoom([factor])

Increase or decrease the zoom level by a given factor.

Arguments

Returns

The object chain

UnitMap.zoomTo(point, [factor])

Increase or decrease the zoom level by a given factor while Interpolating a 2D translation of the map to a given position.

Arguments

UnitMap.fitBounds(bounds, [options])

Pan and zoom the map so the given bounding box fits within the viewport.

// Fit the map to a trip generated by the navigation API:
map.nav().directions(waypoints, function (error, trip) {
  map.fitBounds(trip.bounds(), { animate: true, duration: 500, padding: 100 });
});

Arguments

Returns

The object chain.

UnitMap.panTo(point)

Interpolates a 2D translation of the map to a given position.

Arguments

Returns

The object chain.

UnitMap.panZoom([enabled])

Determines if pan and zoom gestures are enabled.

Arguments

Returns

The object chain.

UnitMap.autoScale(autoScale)

Sets the auto-scaling strategy the Unit Map will employ. Supported values are width, geo, clientRect, and none

Returns

The object chain.

UnitMap.toLocal(point)

Translate the given position from the viewport (screen space) into map space.

var mapElement = document.getElementById("map");

// Output the [x, y] of the current mouse position to the console.

mapElement.addEventListener("mousemove", function(event) {
var point = map.toLocal([event.clientX, event.clientY]);
console.log(point);
});

Arguments

Returns

An [x, y] coordinates Array.

UnitMap.fromLocal(point)

Translate the given position from map space into screen space.

// Output the top left position of the unit map in screen space.

var point = map.fromLocal([0, 0]);

Arguments

Returns

An [x, y] coordinates Array.

Events

UnitMap.on(event, callback, [context])

Binds a given callback function to a given event. The callback will be invoked in the given context whenever the event is triggered. Reference the above Events section for support events.

// Create a named function to handle the event.
// These are commonly referred to as handler or listener functions.

function handleUnitClick (unit) {
console.log('Unit Clicked:', unit.id);
}

// Bind the handler function to the `unit:click` event:
map.on('unit:click', handleUnitClick);

Arguments

UnitMap.off([event], [callback], [context])

Remove a previously-bound callback function. If no context is specified, all versions of the callback with different contexts will be removed. If no callback is specified, all callbacks for the event will be removed. If no event is specified, callbacks for all events will be removed.

// Create a named function to handle the event.
// These are commonly referred to as handler or listener functions.

function handleUnitClick (unit) {
console.log("Unit Clicked:", unit.id);
}

// Bind the handler function to the `unit:click` event:
map.on("unit:click", handleUnitClick);

// Unbind the handler function from the `unit:click` event:
map.off("unit:click", handleUnitClick);

Arguments