Best practices for customizing classic Esri Story Maps
This article covers a topic related to the classic Esri Story Maps templates. Story authors are encouraged to use the current-generation ArcGIS StoryMaps to create stories. However, Esri will continue to maintain the classic templates for your use. For more information, see the Product road map.
Here on the Story Maps Developers’ Corner, we share a lot of tips and techniques about customizing story maps for people who know a little code as well as expert web developers.
If you are closely following any of the techniques we’ve published here on the Developers’ Corner, your customizations are safe. We make every effort to make sure stories customized in these ways continue to work.
However, if you’re going off-script you’ll want to make sure you follow the guidelines below to make sure your customizations are safe and your stories won’t break in future Story Map template updates.
Only use approved HTML
If you are adding HTML in a Story Map builder to customize a story map that’s hosted on ArcGIS Online, be sure to read our article on using HTML:
Only some HTML tags and attributes are approved for use in stories that are hosted on ArcGIS Online. The article above contains a list of approved HTML. If a tag or attribute is not specifically listed in this list, you should not use it.
Even though a customization may seem to work in your story, if the HTML you are using is not on the approved list it’s possible that your customized story could break in a future update.
Don’t reference internal code
An experienced developer might find information in a browser’s dev tools to use for customizations. But if you are using HTML to customize a story map that’s hosted on ArcGIS Online, make sure your customizations do not use any internal methods or code. In other words, don’t reference application code that is not documented. This includes methods used by the story map application code or from internal libraries or dependencies (e.g., Bootstrap).
While these risky customizations might work for the moment, future updates to the Story Map template that remove, update, or otherwise modify code your customization relies on will likely break them.
Consider self-hosting
As mentioned above, a good rule of thumb is that if you are using any of the techniques in our published blog articles, those customizations are safe. Making other types of modifications brings you into risky territory.
If you can’t do what you want using the customization methods that are allowed/safe for stories hosted in ArcGIS Online, you can download or fork the open-source Story Maps template code from Github and self-host your customized code.
By self-hosting, you assume any risk for your customizations and you control when you update the Story Map template code. Before merging in updates from a new release, you can test them with your custom code. If the update affects your customizations, you can modify them before updating or choose not to update the code.
For instructions on hosting your own story map, check out this article:
Intro photo by Émile Perron on Unsplash
