Customizing the Esri Shortlist Story Map App

landing page for esri shortlist story map application

The Esri Story Maps platform is pretty popular among GIS professionals these days.  I wanted to share one of the enhancements I made to the Shortlist template.  I have a fork of this project on GitHub, where I’ve provided the custom code for both the 1.4.9 and 2.2.3 versions of the app.

At version 2.x, the app underwent a major rewrite.  And to be honest, it is much simpler to hook your custom code into the app at version 2.x.  I also have live demos of the Shortlist for both versions.  The code samples in this post come directly from the wiki page for the project, so please check that out.

Below is the list of enhancements I’ve made.  I’m only going to cover the toggable legend in this post.  Feel free to check out the project on GitHub to learn about the others.

  • A toggable legend located on the map
  • Text placeholder in the header area of the app for the date the data was last updated
  • A map/app loading message for desktop and mobile versions of the app (ver 1.4.9 only. I may add this to the 2.x version in the future)
screenshot of the interactive data map web application for Cumberland County, PA
Sample Shortlist Story Map Application

Adding The Toggable Legend

The toggable legend is simply a div element containing un-ordered lists (ul) representing the legend item and an image.  They are static elements that you update as needed.  If you know your way around the Esri JS API, you could probably dynamically generate the legend from the map/feature services.  You would of course need to update the CSS for these elements based upon how many items are in the legend.  I put the following HTML code as the first children of the div id=”map” element around line 138 of the index.html file.

<!-- Custom Legend -->
<!-- Legend Button -->
<div id="customLegendBtn">
<!-- Legend Container -->
<div id="customLegend">
	   <li><!-- [Name of Layer]--></li>
	   <li><img src="" alt="" /><!-- Graphic representing layer --></li>
	   <li><!-- [Name of Layer]--></li>
	   <li><img src="" alt="" /><!-- Graphic representing layer --></li>
   <!-- Use one unordered list per layer -->
<!-- end Custom Legend -->

Now that we have created some DOM elements, it’s time to write the JavaScript.  With the 2.x release of the app, there is a file named custom-script.js within the app/ directory.  This is the recommended spot to add custom code.  We add our code within the topic.subscribe(“tpl-ready”, function(){}); function.

We essentially wire up a click event to the div id=”customLegendBtn” element (legend button) that shows/hides the div id=”customLegend” element (the legend) using jQuery’s toggle() method.  Because the app loads differently above and below the breakpoint (768/769px boundary), we have to control when the legend button appears (its display property is set to none by default).

// Viewport Width
var viewportWidth = $(window).width();
// Custom Legend Button
var customLegendBtn = $('#customLegendBtn');

// Custom Legend - If screen width is above breakpoint, display legend button
if (viewportWidth > 768) {;
} else {
   $('#mobileThemeList .mobileTitleThemes').click(function() {; // show legend button once map is visible below breakpoint

// Custom Legend - add display/hide functionality to Legend button () {
   $('#customLegend').toggle(); // hide/show legend when legend button clicked

Again, if you’re interested in learning more about how to make these enhancements, please visit the following pages:

  • Github Project Page – The master branch is for version 2.x and there is also a branch for version 1.4.9
  • Demo page for live samples of both 2.x and 1.4.9 versions
  • Project Wiki page where I document the custom code

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s