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

FactoryDescription
unitmap(<HTMLElement, String> id,
apiKey, [options] )
Instantiates a Unit Map object given
a div element (or its id), your API key
and optionally an object literal of options.

Options

OptionTypeDefault ValueDescription
autoScaleStringclientRectSet the auto-scaling strategy the Unit Map will employ. Supported values are width, clientRect, geo, and none.
backgroundColorStringundefinedSet the background color of the map. The value must be a valid CSS color value.
panZoomBooleantrueDetermines if pan and zoom gestures are enabled.
maxScaleFloat5.0A factor which is multiplied by the intrinsic pixel size of the map to determine a maximum size when zooming or setting other scale values.

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("Unit Map ready.");
});

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

Arguments

ArgumentRequiredTypeDefault ValueDescription
mapIdYesStringundefinedThe ID of a Unit Map to load.
callbackNoFunctionundefinedA callback invoked when the Unit Map has loaded and is ready. You may also use the ready event.

UnitMap.units()

Returns a UnitSelection object containing all Unit objects.

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

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

UnitMap.levels()

Returns a LevelSelection object containing all Level objects.

// Get a level selection object 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.translate([point])

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

Arguments

ArgumentRequiredTypeDefault ValueDescription
pointNoArrayundefinedAn array representing an x and y coordinate pair of a position in map space.
Example: [1, 5].

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

ArgumentRequiredTypeDefault ValueDescription
scaleNoFloatundefinedThe scale factor.

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

ArgumentRequiredTypeDefault ValueDescription
minScaleNoFloatundefinedThe minimum scale factor.

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

ArgumentRequiredTypeDefault ValueDescription
maxScaleNoFloatundefinedThe maximum scale factor.

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

ArgumentRequiredTypeDefault ValueDescription
factorNoFloat0.1A factor by which to increase the zoom level by.
To decrease the zoom level, provide a negative factor – e.g. -0.1.

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

ArgumentRequiredTypeDefault ValueDescription
pointYesArrayundefinedAn array representing an x and y coordinate pair of a position in map space.
Example: [1, 5].
factorNoFloat0.1A factor by which to increase the zoom level by.
To decrease the zoom level, provide a negative factor – e.g. -0.1.

UnitMap.panTo(point)

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

Arguments

ArgumentRequiredTypeDefault ValueDescription
pointYesArrayundefinedAn array representing an x and y coordinate pair of a position in map space.
Example: [1, 5].

Returns

The object chain.

UnitMap.panZoom([enabled])

Determines if pan and zoom gestures are enabled.

Arguments

ArgumentRequiredTypeDefault ValueDescrption
enabledNoBooleantrueDetermines if pan and zoom gestures are enabled.

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

ArgumentRequiredTypeDefault ValueDescription
autoScaleYesStringundefinedSet the auto-scaling strategy the Unit Map will employ. Supported values are width, 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

ArgumentRequiredTypeDefault ValueDescription
pointYesArrayundefinedAn array representing an x and y coordinate pair of a position in screen space.
Example: [32.9348319, -96.8533228].

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

ArgumentRequiredTypeDefault ValueDescription
pointYesArrayundefinedAn array representing an x and y coordinate pair of a position in map space.
Example: [1, 5].

Returns

An [x, y] coordinates Array.

Events

NameDescription
readySent when a Unit Map has been loaded and rendered onto the page
unit:[event]Listen for interactions with Unit objects. The follow events are sent: click, contextmenu, dblclick, mousedown, mouseenter, mouseleave, mousemove,mouseout, mouseover, mouseup, and show.

Example: unit:click.

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

ArgumentRequiredTypeDefault ValueDescription
eventYesStringundefinedAn event to listen on.
callbackYesFunctionundefinedA callback function to handle the event.
contextNoObjectundefinedThe context for the given callback function.

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

ArgumentRequiredTypeDefault ValueDescription
eventNoStringundefinedAn event to listen on.
callbackNoFunctionundefinedA callback function to handle the event.
contextNoObjectundefinedThe context for the given callback function.

What’s Next