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

Factory

Description

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

Option

Type

Default Value

Description

autoScale

String

clientRect

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

backgroundColor

String

undefined

Set the background color of the map. The value must be a valid CSS color value.

panZoom

Boolean

true

Determines if pan and zoom gestures are enabled.

maxScale

Float

5.0

A 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

Argument

Required

Type

Default Value

Description

mapId

Yes

String

undefined

The ID of a Unit Map to load.

callback

No

Function

undefined

A 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

Argument

Required

Type

Default Value

Description

point

No

Array

undefined

An 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

Argument

Required

Type

Default Value

Description

scale

No

Float

undefined

The 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

Argument

Required

Type

Default Value

Description

minScale

No

Float

undefined

The 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

Argument

Required

Type

Default Value

Description

maxScale

No

Float

undefined

The 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

Argument

Required

Type

Default Value

Description

factor

No

Float

0.1

A 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

Argument

Required

Type

Default Value

Description

point

Yes

Array

undefined

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

factor

No

Float

0.1

A 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

Argument

Required

Type

Default Value

Description

point

Yes

Array

undefined

An 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

Argument

Required

Type

Default Value

Descrption

enabled

No

Boolean

true

Determines 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

Argument

Required

Type

Default Value

Description

autoScale

Yes

String

undefined

Set 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

Argument

Required

Type

Default Value

Description

point

Yes

Array

undefined

An 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

Argument

Required

Type

Default Value

Description

point

Yes

Array

undefined

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

Returns

An [x, y] coordinates Array.

Events

Name

Description

ready

Sent 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

Argument

Required

Type

Default Value

Description

event

Yes

String

undefined

An event to listen on.

callback

Yes

Function

undefined

A callback function to handle the event.

context

No

Object

undefined

The 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

Argument

Required

Type

Default Value

Description

event

No

String

undefined

An event to listen on.

callback

No

Function

undefined

A callback function to handle the event.

context

No

Object

undefined

The context for the given callback function.


What’s Next