Drilldown option requires several configurations. First we need to define a hierarchy in the system that reflects the maps topological hierarchy. Then we need to add several configs to the aggregation config and lastly we need to add the layers object to the chart config.

Hierarchy

To learn how to define a data hierarchy go to Data Collection Hierarchies

In this example we need the following hierarchy:

Generel overview and country level:

province level:

district level:

Chart config

layers: [
  {
    mapKey: 'africa-s4da',
    layer: 1,
    filterField: 'ADM0_NAME'
  },
  {
    mapKey: 'africa-s4da-drilldown',
    filterField: 'NAME_1',
    layer: 2,
    parentMapFilterField: 'ADM0_NAME'
  }
]

Here, we add an Array of layers to the config. Each layer has a “mapKey” which is the code of the topoMap uploaded and a layer number called “layer“ that defines the position in the layer hierarchy. The lower layer (the one drilled down to) has an additional property “parentLayerIdentifier“.

The property “parentLayerIdentifier“ is for filtering the correct features from the map. Its the property of the current layer that identifies that a feature is part of the area that has been clicked.

Example:

If we have a map of all s4da countries of Africa and we click on the country Ethiopia to load a map of all provinces of Ethiopia. Now this identifier tells us to only fetch the provinces that have the value “Ethiopia“ in the field given to “parentLayerIdentifier“. If you are unsure what field to put into “parentLayerIdentifier“ then look what is defined as “filterField“ under “filter” in your chart config. The values in those two fields should match. So if you have selected a field for the filter that matches a name then you should configure an equivalent field as “parentLayerIdentifier“. Often the fields are named exactly the same in both maps but if you have the maps from different sources their names might differ.

{
  legend: true,
  mapCode: 'africa-s4da',
  geometriesKey: 'S4DA_topo_chart',
  areaIdentifierPropertyKey: 'ISO3',
  areaDisplayNameKey: 'ADM0_NAME',
  dataToAreaDataKey: 'value',
  featureCollectionPath: 'geo',
  borderColor: '#888',
  borderWidth: 1,
  showMapLayer: true,
  featureNamePath: 'ADM0_NAME',
  featureIdentifierPath: 'ISO3',
  logScalingColors: false,
  tooltipTemplate: 'return (dataItem ? dataItem.result : 0) + \' measures\'',
  filter: {
    filterCode: 'country',
    filterField: 'ADM0_NAME'
  },
  fillColors: [
    {
      color: 'none',
      start: 0
    },
    {
      color: '#E7F4B9',
      start: 3
    },
    {
      color: '#B5E48C',
      start: 10
    },
    {
      color: '#52B69A',
      start: 20
    },
    {
      color: '#168AAD',
      start: 30
    }
  ],
  layers: [
    {
      mapKey: 'africa-s4da',
      layer: 1,
      filterField: 'ADM0_NAME'
    },
    {
      mapKey: 'africa-s4da-drilldown',
      filterField: 'NAME_1',
      layer: 2,
      parentMapFilterField: 'ADM0_NAME'
    }
  ]
}

Aggregation config

Example aggregation (as found on S4DA CapDev measures) config for data collection named “consultants“. We want all consultants in a Province or district on a topo map:

Group Stage

{
  "$group": {
    "_id": "###hierarchy###",
    "count": {
      "$sum": 1
    },
    "capdev": {
      "$first": "$$ROOT"
    }
  }
},

Project Stage

{
  "$project": {
    "_id": 0,
    "name": "$_id.answers.name",
    "value": "$capdev.###hierarchyProjectionPath.iso###",
    "result": "$count"
  }
}

Explanations

Parameters:

• “code: hierarchy”:

• “code: hierarchySelector“:

ParameterValues:

• hierarchy: The code of the entry layer for the chart and config. E.g. if you have the layers with codes “country”, “province” and “district” and you want a map that first shows the results by provinces when first loading the dashboard, then you would type “province“ as your entry layer. The codes are the same as defined in your chart config above for the object “layers“.

aggregations:

• ###hierarchy###:

• $$ROOT:

• ###hierarchyProjectionPath.iso###:

Additionally we need to select our data hierarchy defined previously in the field “Use Data Hierarchy“ on the left panel and define the entry path into the hierarchy from our collection in the field “Data Hierarchy entry path“ also on the left panel.