du.widgets.map

Module implementing an interactive world map. The map widget is an interactive world map with all countries, dependent territories and special areas of geographical interest. All separate areas that have their own ISO 3166-1 numeric-3 code are included extended by Kosovo, Northern Cyprus and Somaliland. Therefore, the notion 'country' always refers to a region with their own ISO 3166-1 numeric-3 code.

Some of the built-in features:

Zoom: clicking on country zooms in the map, clicking on water zooms out. Scrolling on the map enables zoom in/out.
Attach callbacks on country/territory hover/leave/click.
Simply decide if a geo location is within a country or not.
Add multiple static layers, draw on or highlight any of them.
Add multiple dynamic layers with animated dots.
Pass a list of clusterings to the map and highlight any of them.

Additionally, you only need to work in geo locations, all transformations and projections are cared for under the hood. Note that the module already contains the paths for the countries as well as additional country data (capital info, population size), which results in a significantly large size even minified (~730 kB).

Requires: d3@v4 topojson@v1 leaflet@1.3.1 du.math.la du.Widget

Map

du.widgets.map.Map(name[, parent])

The map widget class.

arg	type	description
name	`string`	Identifier of the widget.
parent	`object`	Parent element to append widget to. If not specified, widget is appended to body. `optional`

resource

du.widgets.map.Map.resource(path)

Sets the map data file to the specified path. At the moment only valid paths to the world.json is supported. Default is null.

arg	type	description
path	`string`	Path to the map resource file.

return	description
`du.widgets.map.Map`	Reference to the current Map.

centerX

du.widgets.map.Map.centerX(dx)

Sets horizontal position of the map center relative to the widget's center. Default is 0.

arg	type	description
dx	`number`	Horizontal distance to set.

return	description
`du.widgets.map.Map`	Reference to the current Map.

centerY

du.widgets.map.Map.centerY(dy)

Sets vertical position of the map center relative to the widget's center. Default is 0.

arg	type	description
dy	`number`	Vertical distance to set.

return	description
`du.widgets.map.Map`	Reference to the current Map.

backgroundColor

du.widgets.map.Map.backgroundColor(color)

Sets color of the background (water). Default is white.

arg	type	description
color	`string`	Background color.

return	description
`du.widgets.map.Map`	Reference to the current Map.

foregroundColor

du.widgets.map.Map.foregroundColor(color)

Sets color of the foreground (soil). Default is black.

arg	type	description
color	`string`	Foreground color.

return	description
`du.widgets.map.Map`	Reference to the current Map.

borderColor

du.widgets.map.Map.borderColor(color)

Sets color of the borders. Default is white.

arg	type	description
color	`string`	Border color.

return	description
`du.widgets.map.Map`	Reference to the current Map.

outClick

du.widgets.map.Map.outClick(callback)

Sets callback for click on water. Can accept one parameter denoting if a zoom out was performed.

arg	type	description
callback	`function`	Callback to set.

return	description
`du.widgets.map.Map`	Reference to the current Map.

tiles

du.widgets.map.Map.tiles(provider)

Adds transparent tiles on top of the map from the specified provider. Supported provider codes: cartodb-positron. Only works while connected to the network. Default is null.

arg	type	description
provider	`string`	One of the supported provider code.

noZoom

du.widgets.map.Map.noZoom(disable)

Disables zooming functionality. Default is false.

arg	type	description
disable	`boolean`	Whether zooming should be disabled.

return	description
`du.widgets.map.Map`	Reference to the current Map.

ready

du.widgets.map.Map.ready(onReady)

Triggers callback when map is rendered. Default is null.

arg	type	description
onReady	`function`	Function to call.

return	description
`du.widgets.map.Map`	Reference to the current Map.

du.widgets.map.Map.countries

Namespace containing various country related methods.

get

du.widgets.map.Map.countries.get()

Returns an array containing id: number, name: string objects of the country ids and names in the map.

return	description
`Array`

capital

du.widgets.map.Map.countries.capital(country)

Returns the capital of a country or all countries. If country is passed and is valid, an object name: string, lon: number, lat: number is returned with with the name and geo coordinates of the capital. Otherwise, an array containing the capitals in the above format is returned. Note that some capitals and geo coordinates can be null.

arg	type	description
country	`string`	Name of the country to return capital data for.

return	description
`object` `Array`	Object or array of objects containing the capital data.

population

du.widgets.map.Map.countries.population(country)

Returns the population of a country or all countries. If country is passed and is valid, the population is returned, otherwise an array containing name: string, population: number objects is returned containing all population data. Source: CIA World Factbook (2017)

arg	type	description
country	`string`	Name of the country to return population data for.

return	description
`number` `Array`	Population or array of population data.

containsGeoLoc

du.widgets.map.Map.countries.containsGeoLoc(country, latLon)

Checks if a geo location is inside a country.

arg	type	description
country	`string`	Name of the country to check boundaries against.
latLon	`Array`	Two element array containing the latitude and longitude of the point.

return	description
`boolean`	True if point is inside the country, false otherwise.

du.widgets.map.Map.clustering

Namespace containing various clustering related methods.

selector

du.widgets.map.Map.clustering.selector(id, name)

Returns the ID selector to a clustering and a group. This can be passed to methods that require a group selector.

arg	type	description
id	`string`	Identifier of the clustering.
name	`string`	Name of the group.

return	description
`string`	Selector representing the clustering and group name.

get

du.widgets.map.Map.clustering.get(id)

Returns an array of clustering group IDs or existing clustering IDs.

arg	type	description
id	`string`	Identifier of clustering. If invalid or not specified, the list of clustering IDs is returned.

return	description
`Array`	Array of existing clustering IDs.

add

du.widgets.map.Map.clustering.add(id, groups)

Adds a new clustering.

arg	type	description
id	`string`	Identifier of the clustering to add.
groups	`object`	Object containing the key as the name of the group and value as array of countries.

return	description
`boolean`	True if clustering doesn't exist and could be added, false otherwise.

remove

du.widgets.map.Map.clustering.remove(id)

Removes a clustering.

arg	type	description
id	`string`	Identifier of the clustering to remove.

return	description
`boolean`	True if clustering exists and could be removed, false otherwise.

dim

du.widgets.map.Map.dim(level)

Dims map to the specified opacity level.

arg	type	description
level	`number`	Opacity level to dim map to.

return	description
`du.widgets.map.Map`	Reference to the current Map.

highlight

du.widgets.map.Map.highlight([id[, color[, duration]]])

Highlights a single country or a group of countries.

arg	type	description
id	`?string`	ID of a country or a group to highlight. If not specified, all countries are highlighted. `optional`
color	`string`	Optional color to use for highlight (default is the bright version of foreground). `optional`
duration	`string`	Optional duration length in ms (default is 0). `optional`

return	description
`du.widgets.map.Map`	Reference to the current Map.

du.widgets.map.Map.staticLayer

The static layers namespace.

get

du.widgets.map.Map.staticLayer.get()

Returns an array of existing static layers.

return	description
`Array`	Array of existing static layer IDs.

add

du.widgets.map.Map.staticLayer.add(id)

Adds a new static layer to the map if it there is no layer with the same ID already.

arg	type	description
id	`string`	Identifier of the new static layer.

return	description
`boolean`	True if new layer could be added, false otherwise.

erase

du.widgets.map.Map.staticLayer.erase(id)

Erases the content of a static layer.

arg	type	description
id	`string`	Identifier of the layer to use.

return	description
`boolean`	True if layer exists and could be erased, false otherwise.

highlight

du.widgets.map.Map.staticLayer.highlight(id)

Highlights a specific layer. If no layer is passed, removed highlight.

arg	type	description
id	`string`	Identifier of the static layer to highlight. If not given, highlight is cancelled.

return	description
`du.widgets.map.Map`	Reference to the current Map.

du.widgets.map.Map.staticLayer.draw

Namespace containing drawing functions.

dot

du.widgets.map.Map.staticLayer.draw.dot(id, latLon, size, color)

Adds a dot to the specified static layer.

arg	type	description
id	`string`	Identifier of the layer to use.
latLon	`Array`	Array containing the latitude and longitude.
size	`number`	Size of the dot.
color	`string`	Color of the dot.

return	description
`boolean`	True if layer exists, coordinates are valid and dot could be added, false otherwise.

circle

du.widgets.map.Map.staticLayer.draw.circle(id, latLon, radius, color)

Adds a circle to the specified static layer.

arg	type	description
id	`string`	Identifier of the layer to use.
latLon	`Array`	Array containing the latitude and longitude for the center of the circle.
radius	`number`	Radius of the circle.
color	`string`	Color of the circle.

return	description
`boolean`	True if layer exists, coordinates are valid and circle could be added, false otherwise.

arrow

du.widgets.map.Map.staticLayer.draw.arrow(id, startLatLon, endLatLon, width, color)

Adds an arrow between two points on a static layer. The body of the arrow follows a geodesic curve.

arg	type	description
id	`string`	Identifier of the layer to use.
startLatLon	`Array`	Array containing the latitude and longitude of the arrow source.
endLatLon	`Array`	Array containing the latitude and longitude of the arrow target.
width	`number`	Arrow width. Head size is adjusted to the width.
color	`string`	Arrow color.

return	description
`boolean`	True if layer exists, coordinates are valid and arrow could be added, false otherwise.

du.widgets.map.Map.dynamicLayer

The dynamic layers namespace. Dynamic layers are used to draw temporary, usually animated primitives on the map. Note that every element drawn to the dynamic layer is removed after 10 seconds to avoid elements being stuck in the map (e.g., due to the browser being in the background or other circumstances that prevent the animation). Also, dynamic layer content is not scaled during zoom.

get

du.widgets.map.Map.dynamicLayer.get()

Returns an array of existing dynamic layers.

return	description
`Array`	Array of existing dynamic layer IDs.

add

du.widgets.map.Map.dynamicLayer.add(id)

Adds a new static layer to the map if it there is no layer with the same ID already.

arg	type	description
id	`string`	Identifier of the new static layer.

return	description
`boolean`	True if new layer could be added, false otherwise.

erase

du.widgets.map.Map.dynamicLayer.erase(id)

Erases a dynamic layers.

arg	type	description
id	`string`	Identifier of the dynamic layer to erase.

return	description
`boolean`	True if layer exists and could be erased, false otherwsise.

highlight

du.widgets.map.Map.dynamicLayer.highlight(id)

Highlights a specific dynamic layer. If no layer is passed, removes highlight.

arg	type	description
id	`string`	Identifier of the layer to highlight. If not given, highlight is cancelled.

return	description
`du.widgets.map.Map`	Reference to the current Map.

du.widgets.map.Map.dynamicLayer.draw

Namespace containing drawing methods.

dot

du.widgets.map.Map.dynamicLayer.draw.dot(id, latLon, radius[, color[, duration[, callback]]])

Draws an exponentially shrinking circle on a dynamic layer.

arg	type	description
id	`string`	Identifier of the dynamic layer to use.
latLon	`Array`	Array containing the latitude and longitude of the circle center.
radius	`number`	Initial radius of the circle.
color	`string`	Color of the circle. `optional`
duration	`number`	Duration of the circle animation. If not specified, 700ms is applied. `optional`
callback	`function`	Callback to trigger after the animation ends but before the circle is removed from the map. `optional`

return	description
`boolean`	True if layer exists, coordinates are valid and circle could be added, false otherwise.

arrow

du.widgets.map.Map.dynamicLayer.draw.arrow(id, startLatLon, endLatLon, width, color, duration[, callback])

Draws an arrow that travels from one point to another on a dynamic layer. The body of the arrow follows a geodesic curve.

arg	type	description
id	`string`	Identifier of the dynamic layer to use.
startLatLon	`Array`	Array containing the latitude and longitude of the arrow source.
endLatLon	`Array`	Array containing the latitude and longitude of the arrow target.
width	`number`	Arrow width.
color	`string`	Arrow color.
duration	`number`	Duration of the pointing animation. If not specified, 700ms is applied.
callback	`function`	Callback to trigger once the animation ends but before the arrow is removed from the map. `optional`

return	description
`boolean`

du.widgets.map.Map.touchLayer

The invisible touch layer namespace. The touch layer is used to place invisible interactive elements on the map.

add

du.widgets.map.Map.touchLayer.add(id, latLon, radius[, mouseover[, mouseleave[, click]]])

Adds a touch element to the touch layer. A touch element is an invisible circle.

arg	type	description
id	`string`	Identifier of the touch element.
latLon	`Array`	Array containing the geo coordinates of the touch element.
radius	`number`	Radius of the touch element.
mouseover	`function`	Callback on hovering the touch element. `optional`
mouseleave	`function`	Callback on leaving the touch element. `optional`
click	`function`	Callback on clicking the touch element. `optional`

return	description
`boolean`	True if coordinates are valid and touch element could be added, false otherwise.

remove

du.widgets.map.Map.touchLayer.remove(id)

Removes a touch element from the layer.

arg	type	description
id	`string`	Identifier of the touch element to remove.

return	description
`boolean`	True if element could be removed, false otherwise.

erase

du.widgets.map.Map.touchLayer.erase()

Erases the touch layer.