How to Add a Map to Dashboard

You can add a map to your dashboard, so that you can display regional data in a graphical form.

All you have to do is to create a Highmaps map widget and use it in your dashboard. The widget is defined by a calculation logic using the api.buildHighmap method. The data can come either from Analytics or other storages or can be created on the fly.

Refer to the Highmaps API reference to explore the full variety of settings. At the very least you need to provide a chart.map value, series[n].joinBy value and series[n].data.

def definition = [
	chart: [ map: 'custom/europe' ],

	series: [
		[
			name: 'Test',
			keys: ['country', 'value'],
			data: [
				[ 'Italy', 0.5 ],
				...
			],
			joinBy: ['name', 'country']
		]
	]
]

def chart = api.buildHighmap(definition)
return chart

// return chart.addModule(String... moduleNames)
// return chart.addMap(mapName)

The joinBy array tells Highmaps how to match the map definition with the data. Typically for international maps, the country name is the 'name' field, which matches the 'country' field of the data in our the example above. There are also 'iso-a2' and 'iso-a3' fields, which feature the 2- and 3-character ISO standards, and many more. Exploring the JavaScript definitions on the Highmaps - Map Collection page should help understanding how this works.

The following example is based on Color axis and data labels with a 1 to 1 translation from JavaScript (as found in "View Options" on the linked page) to Groovy:

//======================================================
// to be adapted to your partition's Datamart definition
def DM_NAME = 'datamart_transaction'
def COUNTRY_FIELD = 'Country'
def REVENUE_FIELD = 'InvoicePrice'
def REGION_FIELD = 'Region'
//======================================================

def ctx = api.getDatamartContext()
def dm = ctx.getDatamart(DM_NAME)
def customQuery =
  ctx.newQuery(dm,true)
	.select(COUNTRY_FIELD, 'Country')
	.select('SUM('+REVENUE_FIELD+')', 'Revenue')
//	.where(REGION_FIELD + "='Europe'")
	.orderBy('Country')

def res = ctx.executeQuery(customQuery)?.getData()
def max = res.selectColumn('Revenue').max()?.getValue()?.toInteger()
def data = []

res.each  { row ->
  def country = row.get('Country')
  switch (country) {
    case 'UK': country = 'United Kingdom'
    break
    case 'USA': country = 'United States of America'
    break
  }
  def value = row.get('Revenue')
  if (value) {
    value = value.toInteger()
  }
  // by using the 'keys' option in series, we can
  // replace this commented out map by a simple array
  //data.push([ 'country' : country, 'value'   : value ])
  data.push([ country, value ])
}

api.trace('data', '', data)

def definition = [
  chart: [
    map: 'custom/europe',
    //map: 'custom/world',
    borderWidth: 1
  ],

  title: [
    text: 'Revenu by Country (EUR)'
  ],

  legend: [
    layout: 'horizontal',
    borderWidth: 0,
    backgroundColor: 'rgba(255,255,255,0.85)',
    floating: true,
    verticalAlign: 'top',
    y: 25
  ],

   mapNavigation: [
     enabled: true
   ],

   colorAxis: [
     type: 'linear',
     minColor: '#EEEEFF',
     maxColor: '#000022',
     stops: [
       [0, '#EFEFFF'],
       [0.67, '#4444FF'],
       [1, '#000022']
     ]
   ],

   series: [[
     animation: [ duration: 100 ],
     keys: ['country', 'value'], // see the above comment at data.push()
     joinBy: ['name', 'country'], // map key is 'name', data key is 'country'
     data: data,
     dataLabels: [
       enabled: true,
       color: '#FFFFFF',
       format: '{point.country}'
     ],
     name: 'Revenue',
     tooltip: [
       pointFormat: '{point.country}: {point.value} EUR'
     ]
  ]]
]

api.buildHighmap(definition)

You can also use latitude/longitude coordinates in Highmaps:

[
"capital":"Reutlingen",
"lat":48.483334,
"lon":9.216667,
"population":400000
]

If you cannot find an example of an existing logic that uses a chart type that you require, it should be fairly easy to adapt one of the Highmaps Demos.

Select your chart and click on the "View Options" button and you will see the JS source code, including a Highcharts.mapChart('container', {...}) call. This {...} content is the definition map.
You will have to convert it from JS to Groovy.
1. This always implies replacing the curly brackets by square brackets ({} -> []).
2. You may also sometimes encounter code like Highcharts.color(colors[5]).brighten(0.2).get() which you should replace by your own hard coded colors, or formatter: function () {...} which you would have to replace by simpler pattern formatter format: '{point.name}: {point.y:.1f}%'.

Currently, not all maps of the extensive Highmaps collection are supported (bundled) – see the list below. If you are missing a map, let us know (open a support ticket) and we will do our best to add it in the next patch release.

World and Continents

/custom/africa
/custom/asia
/custom/europe
/custom/european-union
/custom/oceania
/custom/central-america
/custom/north-america
/custom/north-america-no-central
/custom/south-america ²
/custom/usa-and-canada
/custom/world
/custom/world-continents
/custom/world-eckert3
/custom/world-palestine
/custom/world-robinson

Countries

Since Godfather (8.0) all the countries listed under the Countries heading on the Map Collection page are supported with the exception of countries that have more than one map – in this case only the primary map is supported (e.g, 'Burundi' is supported but 'Burundi, admin2' is not).

Note that maps marked with a red star require that the original source of the map data is credited. By default the credits are enabled and it is important that you do not disable them in the code when using such map.

Support of country maps in previous releases:

Country	Map

Country	Map
Australia	countries/au/au-all¹
Canada	countries/ca/ca-all¹
China	countries/cn/cn-all^{1 3} countries/cn/custom/cn-all-sar^{1 3} countries/cn/custom/cn-all-sar-taiwan^{1 3}
Czech	countries/cz/cz-all¹
Denmark	countries/dk/dk-all¹
Finland	countries/fi/fi-all¹
France	countries/fr/fr-all¹
Germany	countries/de/de-all¹
Hungary	countries/hu/hu-all^{1 3}
Italy	countries/it/it-all¹
Japan	countries/jp/jp-all^{1 3}
Netherlands	countries/nl/nl-all¹
New Zealand	countries/nz/nz-all¹
Poland	countries/pl/pl-all^{1 3}
South Korea	countries/kr/kr-all¹
Spain	countries/es/es-all¹
Sweden	countries/se/se-all¹
Switzerland	countries/ch/ch-all¹
UK	countries/gb/gb-all¹ countries/gb/custom/gb-countries¹
US	countries/us/us-all countries/us/custom/us-all-territories¹

¹since El Presidente PR4 (3.6.4)

²since Collins PR2 (5.2)

³minor character encoding issues remain