Image for post
Image for post

Add Context to Story Map Journal with an Index Map

Stephen Sylvia
Feb 29, 2016 · 8 min read

Story Map Journals are often used to show a set of places, with each section in the Journal showing one place. In this narrative, each section has info about one particular place, including one or more photos, and the main stage map shows a close up of that place. This is a good use of the Story Map Journal, but typically readers have to browse through each of the sections and can’t jump directly to a particular place.

With the addition of an index map, however, we can address that and make the Story Map Journal easier to use for exploring sets of places. The index map provides a geographic overview of where the places are located, shows users the location of the place they are currently reading about, and lets them jump to a particular place by clicking on the map.

Essentials for Success

  • Have access to a web server to host your customized story.
  • Create a .
  • Basic understanding of HTML/CSS/JavaScript.

Getting Started

Image for post
Image for post
Completed demo showing the index map in the top left corner of the app

A couple years ago our team published a Story Map Journal that showcased the ten most visited parks in the United States according to the Trust for Public Lands report of 2014. This is an excellent example of a story that has a sequential narrative flow for the journal layout while at the same time having a need for the audience to explore further (example: a user wanting the find the park closest or farthest to them).

To begin, we’ll first need to download the . All of the Story Map apps are open source and available for download so you can use and customize as you wish. The source code for each app can be found by navigating to our and clicking the “Learn More” button under the description for each app. About halfway down this page, you should see a link to “Download configurable app.” Unzip the contents of this download to a new folder on your server.

Next, you’ll need to get the application ID that is associated with the version of the app that is hosted on ArcGIS Online. All the content of your story will still be hosted on ArcGIS Online and you’ll still be able to use the online builder to edit your story. The application ID will link your hosted version with the customized version that is now on your server. This application ID can be found by looking at the URL of your hosted app. Just copy the alphanumeric code that comes after the “appid=” in the url (see example in bold below).

Once you have this open the index.html file in your favorite text editor. Notepad works fine but I recommend using a text editor that has syntax highlighting to make it much easier to read. and are two free apps that work really well on both Mac and PC. Scroll down to configuration section and paste the application ID between the quotes of the appid variable.

Additionally, I recommend you add the username you used to create the story to the authorizedOwners variable. This will prevent others from using your version of the code, and your servers bandwidth for they’re own story.

Image for post
Image for post

At this point, if you open the app in your browser, you should have an exact duplicate of the app you created in ArcGIS Online except it will be hosted on your own server.

Create CSV of Locations

After you have the local version of your story ready to go, the first thing you’ll need to do is create a CSV that will drive the points in your index map. The CSV needs to include the point locations (latitude and longitude), a label for the tooltip, the index number of the corresponding map journal entry and a field to store whether the point is currently active.

A few things to note about my CSV. First, I intentionally made my labels short and sweet. You can have more expansive title for your journal entries but the tooltips work best if the labels are short. Also, the “Active” field is just the placeholder field that we will use to track if that point is selected. By default we can set every point to “FALSE” and our JavaScript will handle the rest. Finally, we need to get the index to the corresponding story. The index is the specific order that the entry is stored in the app. The home section is 0, the first section is 1, and so on. The easiest way to get this is to open up the and watch as you scroll through each section. You will see a line that says something like:

tpl.core.MainView - navigateStoryToIndex - 2

The number at the end of this line will be the index for that section. Add a new line (location) in your CSV for every section you want to link to.

Image for post
Image for post
Showing where to find the story index through the developer console.

IMPORTANT NOTE: If you use the organize feature in the online builder to change the order of your story, the story index will change and you will need to update your CSV file.

Once you have CSV completed, you can save it with your app files. I recommend saving in (create a new folder in resources named “index-map”):

Map Journal Root

If you keep the same field names and save your CSV file in the same location, you will have less to change in the code later.

Add supporting CSS

Now that we’ve added the HTML elements, we need to add some CSS to style them. At the top of the body tag, you will find a style tag with a comment “CUSTOM CSS RULES” to enter the following CSS ().

Supporting CSS needed for the index map

There are four colors (hex value) that should change to make both the point label tooltip and helper tooltip match the theme of the app like I have done in the sample.

Image for post
Image for post
CSS added in context

Add supporting HTML

The index map needs a few HTML elements to be added to the index.html. These are the container for the map itself, a container for the mouse-over tooltip label, and a small helper tooltip to show your audience they can click on the map to navigate to a new section. Below is the html you will need to add.

Supporting HTML needed for index map

Make sure to change the helper tooltip text to match the topic of your story. It currently reads “Click a park to explore.” If you are using the Side Panel layout, add these elements just before the div with the class “appTitle” (). If you are using the Floating Panel layout, add these elements just before the div with the class “appTitle” ().

Image for post
Image for post
HTML elements added in context

Wire up the Index Map with JavaScript

To complete the demo, you’ll need to add a bit of JavaScript in the file to load the new map, add click events to the points and update the selected point as your user scrolls through the story. When you first open it you should see this bit of code:

require([“dojo/topic”], function(topic) { 

/* * Custom Javascript to be executed while the application is initializing goes here */
// The application is ready
topic.subscribe(“tpl-ready”, function(){

/* * Custom Javascript to be executed when the application is ready goes here */


Replace it with this code:

Supporting JavaScript needed for the Index Map

I’ve added comments to the code so you can see what each function is doing. If you’ve followed the directions up until this point, the code should just work to create the map, add the points layer, add the click events to navigate to a new section and change the active point when a user scrolls through the story. You’ll probably notice that the map is still centered over the United States and the point symbols match the color scheme in my demo. There are two section in the JavaScript that you can change these.

We’ll start by updating the small variables config at the top of this section (Line 32 in the snippet above). The first three variables allow you to match the CSV field names to the names used in the code. If you changed any of the fields names (include upper/lower case changes), you will need to make sure these variables match exactly to what you have in the CSV.

var LabelField = ‘Label’;
var StoryIndexField = ‘StoryIndex’;
var ActiveField = ‘Active’;

Next we can change the point colors used in the map:

var defaultMarkerColor = new Color([114, 100, 87, 0.7]);
var activeMarkerColor = new Color([0, 105, 0, 0.9]);

Update these to match the theme of your story. The color variables are being stored in RGBA array which allows us to use a slight transparency. You can use any color that is supported by the .

The last variable allows you to change the path to the CSV file if you’ve put in a different folder or changed the filename:

var csvPath = ‘resources/index-map/index-map-layer.csv’;

Once you have finished the general config, you can move down change the options used in the map (line 53 in the snippet above) which will allow you to change the the starting map location, basemap, and min/max zoom scales, etc.

var indexMap = new Map(‘index-map’,{ 
basemap: ‘gray’,
center: [-95,38],
zoom: 3,
minZoom: 1,
maxZoom: 8,
logo: false,
showAttribution: false

All the options available to be changed can be found in the .

See the completed and files.

Image for post
Image for post
Completed Demo

That’s it, you should now have a working index map, matched to your story’s theme. If you’ve been working off a test server, it’s now time to move your code over to your production server and share your story with the public. If you haven’t already done it, I recommend filling in the open graph tags so your app is discoverable by Google and looks nice when shared as well as add Google Analytics so you know who is visiting your story.

Story Maps Developers' Corner

Learn best practices, read quick tips, and discover new…

Stephen Sylvia

Written by

A front end web developer working on Esri’s Story Maps team

Story Maps Developers' Corner

Learn best practices, read quick tips, and discover new ways to make your story map stand out from the crowd. Start creating your story at:

Stephen Sylvia

Written by

A front end web developer working on Esri’s Story Maps team

Story Maps Developers' Corner

Learn best practices, read quick tips, and discover new ways to make your story map stand out from the crowd. Start creating your story at:

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store