Add Context to Story Map Journal with an Index Map
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 Story Map Journal.
- Basic understanding of HTML/CSS/JavaScript.
Getting Started
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 source code. 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 apps page 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).
http://www.arcgis.com/apps/MapJournal/?appid=84c097f098c04c6f8b2b6924ce7f5e1bOnce 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. Notepad++ and Atom Editor 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.
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 developer console and watch as you scroll through each section. You will see a line that says something like:
tpl.core.MainView - navigateStoryToIndex - 2The 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.
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
|__resources
|__index-map
|__index-map-layer.csvIf 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 (about line 80).
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.
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.
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” (about line 158). If you are using the Floating Panel layout, add these elements just before the div with the class “appTitle” (about line 258).
Wire up the Index Map with JavaScript
To complete the demo, you’ll need to add a bit of JavaScript in the custom-scripts.js 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:
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 Dojo Color object.
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 Map documentation of the ArcGIS API for JavaScript.
See the completed index.html and custom-scripts.js files.
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.
