National Map in GovCMS

19 March 2019

NationalMap is the perfect tool for displaying geographical data from a range of Australian government agencies, and now with the NationalMap Component in Convivial we can augment geo data from additional data sources to see data in a new light.

NationalMap is an intuitive interface that allows you to explore and filter a vast collection of geographic data. Convivial is a distribution that extends GovCMS with a NationalMap Component. In this article we will walkthrough embedding a national map without a single line of code, and show you how we built it.

National Map Embed
A map displaying geo data via 3 different methods (Custom GeoJSON, URL and Share URL)

NationalMap Component

In Convivial we have created a "NationalMap" paragraph which allows you to augment geo data from multiple data sources onto the one map. Geo data can be sourced from, or by pasting in custom geo data.

An example entry of GeoJSON data looks like:

National Map Catalog Item

In this example we've referenced GeoJSON via a URL. GeoJSON is a great format for storing spacial data as it's easy to author, read and consume by National Map. Geo data can either be referenced via URL, pasted directly into the Data field, or by referencing the "Share URL" provided by NationalMap when adding data via its UI.

Once you've added a few entries, simple save the form and the resulting page will show a National Map of all your geo data.


NationalMap introduces the concept of Catalogs and Catalog Items, which we adhere to closely.


National Map Catalog

A catalog can be thought of as a layer except it contains multiple catalog items within it, each with their own data source. A catalog has 2 important properties:

  • Name - What will be displayed in the sidebar for the "layer"
  • Open - Whether the layer's geo data should be hidden or seen on the map

Catalog Item

A catalog can have many catalog items, but usually will have just one. The catalog item is where the magic happens and has a few key properties:

  • name - In most cases will match the name of the catalog
  • type - Data type such as "geojson" or "csv"
  • url - URL to the geo data of the same data type specified by "Type"
  • zoom - The map will zoom in to the bounding box around the data with this option checked

Our Technical Implementation

The software behind NationalMap is called Terria.js, and is open source. We can embed a national map and populate it with geo data via its API. Our implementation is as follows:

Step 1 - Process geo data

From the user supplied form data we generate JSON suitable for consumption by Terria.js/NationalMap. In GovCMS it is not possible to add new code via custom modules, however it's possible to add server side logic via the theme layer. We can use the template_preprocess_paragraph() hook to generate JSON for consumption by the front end.

In the template_preprocess_paragraph() hook we check that the entity type is a paragraph and that the entity bundle is a national_map. We then generate an array of catalog data. The last but most important part is to pass that data to the client side with:

$vars['#attached']['drupalSettings']['national_map'][$id] = [
  'id' => $id,
  'catalogs' => $catalogs,

Now the JSON can be accessed on the client side via drupalSettings.national_map with a Drupal behaviour.

Step 2 - Embed map

Embed NationalMap via an iframe:

<iframe id="map" src="" width="100%" height="500px"></iframe>

Step 3 - Wait for map to load

Get the iframe and wait for it to load via Javascript:

// Wait for message event.
window.addEventListener('message', function(event) {
  // Get iframe's content window.
  var iframe = $('iframe#map').get(0).contentWindow;
  // When iframe has loaded.
  if (event.source === iframe && === 'ready') {
    // Step 3...

Step 4 - Render geo data

The iframe was introduced in 1997. HTML has come a long way since then and now lets us communicate through the iframe to the embedded website via HTML5's postMessage method:

// Ask iframe to render catalogs.
  initSources: [{
    catalog: []
}, '');

The catalog property takes an array of catalog objects. An example data set looks like this:

  type: "group",
  name: "Ballarat Recreation",
  items: [{
      type: "geojson",
      name: "Ballarat Bike Racks",
      url: "",
      zoomOnEnable: false
      type: "geojson",
      name: "Ballarat BBQ's",
      url: "",
      zoomOnEnable: true

The NationalMap Component generates all of this HTML and JSON for you, so you don't have to play around with JSON data structures each time you'd like to embed a national map.



Convivial's NationalMap Component lets you embed a NationalMap using data from a variety of sources anywhere on a page in a straight forward manner.

An example of the NationalMap embed can be seen on the Convivial Demo page.