Interactive Storytelling

A low-code template to help you tell your map-based story

What does this solution do?

From Commercial Real Estate to Brand Marketing, Newsrooms to Board Rooms, telling compelling stories with data is a critical aspect of doing business. The growth of IoT and connected sensors means that the data to which these analysts, developers, and journalists have access increasingly includes a location context. So telling these stories using maps as the canvas can make them more understandable, powerful, and memorable.

Newsrooms (who are leading the charge in location-based storytelling) report that they see higher reader engagement on the stories that include interactive maps, compared to stories with static images or no visuals at all. These top news publishers, including the Washington Post, New York Times, and USA Today, use maps to surface insights more quickly, shed light on their investigative stories, and even change federal policy as a result.

While newsrooms have dedicated development resources to build the beautiful interactive maps they feature, we want to make it easy for anyone to tell their stories with a map. The Mapbox Storytelling Template provides a low-code, modularized template that anyone can use to input copy, select the elements of the map that they want to feature for each “chapter,” and quickly publish a highly interactive story experience with high quality visuals to support the content.

The template works well for any story that highlights multiple locations, and especially ones that include custom map data. For example, in a story about the changing size of glaciers, maps of the glaciers at different points in time display alongside the text describing those changes.

Use it to compare demographic data in different cities, share reports about factory site output, highlight housing market trends, communicate interactive travel itineraries, maybe display migratory patterns; the template allows easy output and publication of these datasets using the rich, interactive and compelling canvas of a map. Try the example below for yourself.

Solution Architecture
Version:
1.0
Last Updated:
November 5, 2019
Author:
Mapbox
Start building

Source code on Github

Solution Details

The template contains two files:

  • A story content file (config.js). This JSON-formatted text file includes story copy, location information, and settings to control how the map & story are displayed. This is what the storyteller edits.
  • A map story file (index.html). This HTML file reads information from the content file and dynamically builds out the story and map controls. This is what the reader sees.

Once the content file is set up, these two files are published together to a static web-hosting location.

Story content file

Think of a story as a set of data and the content file as a template for how the data is structured. The storyteller takes the story elements and puts them into the defined structure, enabling the code in the index.html file to read the data and bring the story to life.

The content file has general settings like horizontal alignment (left, right, or center), light or dark theme for the page, and which map to use. It also has settings for each location in the story, including a photo, description, and coordinates. If you have set up custom map data in Mapbox Studio, there are also settings to control which map layers to show and hide.

Map story file

The map story file does not have to be edited. It already contains the basic HTML structure, the CSS properties that define the style and layout, and the JavaScript code that dynamically builds the page based on information in the config.js file.

If the user has CSS knowledge and wants to customize the map story file, its simple structure makes it easy to enhance. You can change the theme colors and adjust the layout, spacing, and look of the story.

We have also provided a React-based version of the map story file, if you prefer to write in React. This version is still driven by the information in the config.js file, and the code in the App.js and App.css files does not need to be edited.

We also built an HTML page to help find location coordinates and set up the best "camera angle" to showcase a location. Find the helper page here.

Technical Information

Things you need to get started:

  • a Mapbox access token. Sign-up for a free account here.
  • a text editor. Atom, Sublime Text, and VS Code are common options.
  • a place to host your story files. Any web-accessible location will work, like a web server, S3 bucket, or service like Netlify. Github pages, Glitch, and bl.ocks.org are fine options, too.

Mapbox usage:

Every view on your story triggers a "map load". Mapbox has a generous free tier (up to 50,000 map loads per month). For more pricing details, consult the Mapbox pricing documentation.