⚠️

This page describes map widgets, an experimental feature of Cartographer that may be subject to change in the future. The instructions below require some familiarity with web development languages such as HTML and CSS. Proceed at your own peril!

Most Cartographer maps can be embedded on external web sites using our map widget. This lets you present an interactive view of your data for public engagement and reporting. For example, here is a map widget showing habitat complexity values derived from the Modular River Survey.

Creating a Map Widget

Click on one of the Maps menu items in the left-hand sidebar to navigate to the map page for your chosen map:

Click the cog icon in the inspector panel to view the map options:

Scroll to the bottom of the Map Options pane to view the section entitled Map widget (experiemental). Here you’ll see an HTML snippet that can be copied onto your web site to create a map widget:

The HTML snippet contains a number of configuration parameters that affect the display of the map widget. Many of these parameters, including the position and zoom of the map and the selected attribute in the inspector pane, update automatically to reflect the settings of the map you’re currently viewing. Try panning and zooming the map now to see the parameters in the HTML snippet change in real time:

Adjust the map to get the position and zoom level right. Then copy the HTML snippet and paste it into the source of your web page. Here’s an example from the map above:

<!-- Start of Cartographer map widget -->
<script src="https://widget.cartographer.io/map/v1/loader.js"></script>
<div data-cartographer-map
     data-subdomain="mrs"
     data-layer="mrsMorph"
     data-attribute="NumFlow"
     data-center="52.119999,-3.273926"
     data-zoom="7"
     data-from="2014-06-07"
     data-to="2019-06-07"
     data-global="false"
     data-tiles="terrain"
     data-fixed="false"
     data-scrollwheel="true"
     data-selectradius="10"
     data-inspector="options"
     data-legend="hide"></div>
<!-- End of Cartographer map widget -->

Customising the Map Widget

You can adjust some of the data- parameters to tweak your widget. Here are the ones we recommend experimenting with. Don’t change others as you may break the widget:

data-cartographer-map — Don’t edit this one. This is a special attribute used by the map widget. It must be present for the widget to work.

Layer and Attribute

data-layer — Unique ID of the map layer to show.

data-attribute — Unique ID of the attribute to use to colour code map features. Attribute names are specific to each map.

Workspace

data-subdomain — The subdomain of the workspace whose data to show.

data-global — If this is a shared map layer, setting this attribute to "true" will show data from all participating workspaces.

Position and Zoom

data-center — The WGS84 GPS position of the center of the map in "longitude,latitude" format.

data-zoom — A number from "1" to "20", where "1" shows the whole world and increasing numbers zoom in more and more.

Date Range

data-from — The earliest survey date to show in "yyyy-mm-dd" format. Remove this attribute to show all surveys back to the start of the dataset.

data-to — The latest survey date to show in "yyyy-mm-dd" format. Remove this attribute to show all surveys up to today.

Appearance and Interactions

data-tiles — The background layer to use on the map. There are two possible values: "terrain" and "satellite".

data-fixed — Set this to "true" to prevent users panning or zooming the map.

data-scrollwheel — Set this to "false" to disable mouse scroll wheel interactions. This is useful if the map widget is embedded on a web page where users use mouse wheels to scroll up and down.

Inspector and Legend Panels

data-inspector — Customises the inspector panel on the left of the map (see ). The value should be in the format "mode,option,option,option" where:

mode is one of the following:

no — don’t display the inspector at all;
yes — do display the inspector;
hide — don’t display the inspector by default, but allow the user to toggle it on.

you can have zero or more options, each of which customises the inspector behaviour as follows:

nophotos — disable the Photos tab;
nocharts — disable timelines and histograms;
nooptions — disable the map options panel;
nolayerselect — prevent the user clicking the inspector to select attributes.

data-legend — Customises the legend panel on the right of the map. The value should be one of the following:

"no" — completely disable the legend;
"hide" — enable the legend but hide it by default;
"show" or "yes" — enable the legend and show it by default.

data-selectradius — The radius of the lasso (in meters) that is used to draw timeline charts on the inspector.

Styling the Map

The map widget injects some basic styles into your web page to give the map a minimum size. To really make the map look good, however, you will need to apply your own style rules using CSS.

A full discussion of CSS is beyond the bounds of this document. However, the following may be a good starting point. This makes all maps on the page 500 pixels tall and as wide as their containing section, and gives then a single-pixel black border:

<style>
  .cartographer-map {
    width: 100%;
    height: 500px;
  }

  .cartographer-map iframe {
    border: 1px solid black;
  }
</style>

Using the WordPress Plugin

If you have a WordPress web site, you can use our wordpress plugin to make it easier to embed maps in posts and pages. The plugin enables a cartographer_map shortcode that looks like the following:

[cartographer_map 
  subdomain="mrs" 
  layer="mrsMorphV2"
  attribute="ChannelPhysicalHabitatComplexity"
  center="51.8,-1.5"
  zoom="7"
  inspector="hide,nophotos,nooptions"
  legend="hide"
  charts="no"
  selectlayers="no"
  selectradius="500"]

The shortcode is of the form [cartographer_map option="value" ...] where each option is one of the options decribed above without the data- prefix.

Embedding a Map on Your Web Site