Navigate Map Journal Sections Using the Main Stage Map

Turn your main stage map into an interactive table of contents

The Map Journal interface contains two primary elements: the narrative panel (also referred to as the side/floating panel), and the main stage. As the reader scrolls through entries or sections in the narrative panel, the main stage updates to show relevant content, such as maps, 3D scenes, images, videos, or even webpages. In terms of story navigation, it’s a one-way relationship: user interaction with the side panel updates the main stage content, and not the other way around.

But with a simple customization, it’s possible to invert this behavior, so that interacting with a map in the main stage actually navigates through the story. In other words, this customization allows you to click on a feature on the map, like a point, to jump directly to a specific narrative section. This is great if you want to create a Map Tour-esque story map using non-point features (like country polygons); or if you want to provide a geographic “table of contents” in the form of an interactive map; or for allowing readers to explore content in a non-linear manner. We’ve included this customization in several different stories of our own; in this tutorial, we’ll show you how to include it in your own Map Journal.

What you’ll need:

• A Map Journal containing at least one webmap, which itself must contain at least one feature layer to use for navigation
• A code editor (Sublime Text, Atom, and Notepad++ are all good options)
• A basic understanding of JavaScript
• A web server to host your customized story map

Note: the line numbers cited in this article may differ slightly from the line numbers you see when you download and open the source code. This is because the application files may’ve changed since we published this tutorial. When in doubt, use CMD/CTRL+F to find the proper locations in your code.

Directions:

Our primary goal here is to create a link between individual features in the webmap, and specific sections in the MJ’s narrative panel. To begin, we’ll create a new numerical field in our feature layer, containing the index of the corresponding MJ section. You can create a new attribute field directly in the map viewer, by toggling the feature layer’s table view, choosing the Options dropdown in the upper right of the table, and then selecting Add Field When you create the new field, be sure to choose the integer data type, and jot down the field name — you’ll need this later. It’s also a good idea to add a sensible alias.

Once the field has been added to your table, you should be able to manually edit individual values by double-clicking on the cells. If you’re unable to make edits, ensure that you’ve enabled editing under the Settings tab of the feature layer’s item page (shown at the very bottom of this image):

In this example, I don’t need to create a new field, since the feature layer’s Rank field already contains the section indices.

Edit attribute values by double-clicking on individual cells. In this example, I’m using the “Rank” column as the index, because I want the 1st largest refugee camp to be the first entry in our story.

Next, you’ll want to collect four pieces of information for later use. They are:

• Field name: if you didn’t grab the field name in the previous step, you can find it a few ways. The quickest way is to navigate to the feature layer’s item page, and select the Data tab. Then, click on the header of your desired column, and choose Show detailed view. This will reveal the field name. Note that there’s often a difference between the field name, what we’re looking for, and the field alias, which appears in the field’s header. (You can think of the alias as a shorthand nickname.)

Click “Show Detailed View” to obtain the field name. In this example, the field name and the alias are identical.

• Webmap ID: you can grab this directly from the URL; it’s the alphanumeric string appended to webmap=. Bear in mind that the webmap ID isn’t the same as the Map Journal ID.

The webmap ID appears at the end of the webmap viewer URL

• Layer ID: this is not the same as the layer item ID; it’s an identifier that’s unique to this webmap’s instance of the feature layer. Open the Developer Tools (CTRL or CMD+SHIFT+I in Chrome on Windows/Mac), and in the HTML preview, and scroll down to the map_layers div. Expand the SVG object at the bottom of the layers list (which contains all feature layers), and look for your layer ID. It should be similar to the service name, but possibly with a number and “layer” appended. In this case, it’s UNHCR_PoC_2016_8102_layer. Remove the “_layer” from the string and you have the layer ID. In my case, that’s UNHCR_PoC_2016_8102.

Alternatively, you can use ArcGIS Online Assistant to locate the layer ID. The process is a little more straightforward, but perhaps less efficient for developers. After logging in, select View an Item’s JSON from the I Want To… dropdown, and then select your webmap in the lefthand column. Scroll down to the Operational Layers section on the right, and then look for your layer in the list. The title value contains the name of the layer in the map’s table of contents, but it’s the ID value that you want to copy.

The layer ID is highlighted here.

• Application ID: the application ID is appended to the application’s URL, after “appid=”. Just copy the 32-character alphanumeric code. Again, bear in mind that this is not the same as the webmap ID.

The Map Journal application ID.

Now I have all the information I need:

• Webmap ID: 0df1997ac587470f9e3713a15c532cb9
• Layer ID: UNHCR_PoC_2016_8102
• Field name: Rank
• Application ID: 8ff1d1534e8c41adb5c04ab435b7974b

The next step is to download the Map Journal application source code from the Map Journal page on the Story Maps website, or directly from Github. (Remember, if you use the Github version, you’ll have to compile the source code into the production version before deploying. More information on that process is available in the repository’s readme.)

Once you’ve downloaded the application code, open index.html in your preferred code editor. (In the screenshots below, I’m using Atom.) Scroll down to around line 41, and paste your application ID into the appid field, surrounded by double quotes. Here’s how it looks for me (I’ve highlighted the appropriate line):

While you’re at it, don’t forget to add social media metadata and your Google Analytics tracking code, if you feel so inclined. (You should.)

Next, open custom-scripts.js (it’s in the app folder in the project directory). Replace the existing content of that file (which is just empty, non-functional placeholder stuff) with the following code snippet:

(Note that the line numbers in this snippet may not correspond to the line numbers in your code editor.)

Now, there are just three things you need to update. (Again, please bear in mind that these exact line numbers are subject to change as the application evolves).

• On line 13, insert your webmap ID where indicated, preserving the double quotes.
• On line 14, insert your layer ID where indicated
• On line 25, your field name where indicated

Remember to remove the placeholder text, and keep the double quotes. Here’s how it looks for me, after I’ve made these changes:

That’s it. Ensure that you’ve saved index.html and custom-scripts.js, upload all the application files to your webserver, and give it a spin. Pretty sweet, huh?

Further customization

If you want to take things a step further, you can also add mouseover tooltips to your features, so that when readers highlight features, they receive a clear indication that the point is interactive. To do so, you’ll simply add two additional methods to the snippet above: one that fires on mouse-on and shows the tooltip, and one that fires on mouse-out and hides the tooltip again. Here’s what that looks like:

Be sure to check out the full infoWindow (tooltip) documentation on the ArcGIS JS API website to learn how to get the most out of your tooltips.

Wrap up

Now, there are a couple caveats worth mentioning:

• The implementation outlined in this tutorial is not currently supported by touch/mobile devices, due to how the ArcGIS JSAPI interprets click events. (So, tapping on a point in the mobile version of Map Journal won’t automatically navigate to the corresponding section; the user will have to swipe through.)
• This method only works with a single webmap; of course, you can still include multiple webmaps in your Map Journal, but only one can be used for navigation. (There are workarounds for this — basically, defining multiple maps, layers, and attributes in custom-scripts.js — but they aren’t discussed in this post.)

Did you use this customization in your own Map Journal? Let us know!