Note: Classic Esri Story Maps templates are in extended support on ArcGIS Online as of September 2021 and mature support on ArcGIS Enterprise 10.9.1. For the latest information on the transition from classic Esri Story Maps to ArcGIS StoryMaps, click here.
The Story Map Cascade℠ app lets you combine narrative text with maps, images, and multimedia content in an engaging, full-screen scrolling experience. In a Cascade story, sections containing text and in-line media can be interspersed with "immersive" sections that fill the screen with your maps, 3D scenes, images, and videos. Cascade is ideal for making compelling, in-depth stories that are very easy for people to navigate.
View it live | Download | Cascade page on Esri Story Maps website
Latest release is version 1.23.0, which corresponds to the June 2022 release of ArcGIS Online. If you want to be informed of new releases, we recommend you watch this repository (see GitHub help). See the release page for release notes.
- Introduction
- Instructions
- Feedback / support
- FAQ
- Configuration
- Customize the look and feel
- Developer guide
- Issues
- Contributing
- Licensing
A Cascade story can be created from ArcGIS Online, from the Esri Story Maps website, or from ArcGIS Enterprise. The Cascade story's data are stored in a Web Application Item. This repository provides the application source code for developers who want to customize the application.
For more information about the application, including a gallery of examples and a step-by-step tutorial, please see the Cascade page on the Esri Story Maps website.
First, create your Cascade story in ArcGIS using the step-by-step tutorial. Once your story is ready, you have to find its ID in ArcGIS. The ID is a 32 character string that you will find in your web browser's address bar when you are viewing your story.
- Download the application
- Deploy the application on your webserver. See FAQ for details
- Edit index.html, find the configuration section on line 47 and paste in your application ID
- Navigate to index.html (e.g.,
http://127.0.0.1/Cascade/index.html)
You can continue to use the builder in ArcGIS to modify your story.
See customize the look and feel section or developer guide if you want to modify the app.
If you are using ArcGIS Enterprise, please follow the instructions at the end of app/config.js to configure the application.
We would love to hear from you!
- StoryMaps Website
- Story Maps community forum
- Let us know about your story
- Story Maps Developers' Corner
- @EsriStoryMaps
- ArcGIS Blog
When you contact us, don't hesitate to include a link to your application to make it easier for us to understand what you are working on.
For more answers, please see the Story Map website FAQ page; it includes a section about Cascade.
Cascade stories are supported on Internet Explorer 11 and above, Chrome, Firefox, Safari and the most recent tablet and smartphone devices.
Cascade authoring is supported on a desktop computer for Chrome, Firefox, and Safari. We are considering support for other browsers.
We actively test the application in all major browsers but if you experience difficulties, especially with the builder, we recommend that you use Chrome.
We have posted a number of tips and tricks for authoring your Cascade app on the ArcGIS blog, as well as several "How To Cascade" tutorials using Cascade itself.
Yes, the regular ArcGIS security model applies. By default your story is private, you can share it through Cascade builder or ArcGIS. When you share your story through the Cascade builder, its maps and layers will also be shared if you own them or have privileges to share them. You will still need to make sure webscenes and embedded apps are accessible to your audience when you share, as they are not shared automatically with the story.
Yes.
When the story is hosted in ArcGIS Online or ArcGIS Enterprise, users who don't have access to the story or a web map used in the story will be redirected to the ArcGIS sign-in page. It is not possible to display an authentication dialog in the application when it's hosted in ArcGIS.
When the story is hosted on your web server, by default an authentication dialog will appear inside the application. But we recommend that you configure the application to use OAuth. OAuth 2.0 based authentication is available for ArcGIS Online users with developer or organizational accounts and ArcGIS Enterprise users. Follow this procedure to add and register an application to get an OAuth application ID. Once you have that application, open index.html, locate the configOptions section and fill the oAuthAppId property.
If you are using secured services but don't want users to have to authenticate, you can use a proxy to store the username/password to be used, see Working with Proxy Services, and add proxy rules to specify what services need to use the proxy by editing PROXY_RULES in app/config.js.
Deploying a Cascade story requires use of ArcGIS Online or ArcGIS Enterprise. The Cascade content must be created using the Cascade builder and will live in a Web Application Item.
This is not a supported use case at this time. Please let us know if you are interested in such a scenario.
The Cascade data are stored in a Web Application Item in ArcGIS Online or an ArcGIS Enterprise portal. This includes the narrative content, reference to any media used (web maps, web scenes, pictures, audio, videos, web pages), and app-wide settings.
The images, audio, and videos that you include in your story using the builder are not loaded into ArcGIS unless you upload them through the ArcGIS option. You have to make sure that those medias that are stored on other services are, and will remain, accessible to your audience.
Yes, Cascade is included with ArcGIS Enterprise starting at version 10.5.1.
Yes, when the story is configured with an application ID, adding the URL parameter edit will open the builder. You will be prompted for user authentication.
If you are not familiar with web servers, here are some solutions:
- Use the web server that comes with your Operating System. On Windows, this is Internet Information Services (IIS); if you have a
C:\inetpub\wwwrootfolder on your computer, you should be able to access its content usinghttp://localhost - On Windows or Mac OS, use a simple web server like Mongoose (not recommended for production)
If you are experiencing some rendering issues like improper symbols appearing instead of icons, you will have extra configuration to perform. Some servers require the configuration of a new mime type to be able to serve Cascade fonts correctly. See the following links for more information:
Yes. If you have customized the application and deployed it on your server, you don't need to copy it multiple times, edit index.html and paste a different application ID for each story you want to publish.
Instead edit index.html, locate the configOptions section and fill the authorizedOwners property with the ArcGIS Online or for ArcGIS login of the owner(s) of the story you want to use. This makes it possible for the application to display any of stories created by the specified user(s) through a URL parameter.
Example of the same application displaying two stories:
- http://myserver.com/Cascade/index.html?appid=c7ad1a55de0247a68454a76f251225a4
- http://myserver.com/Cascade/index.html?appid=c7ad1a55de0247a68454a76f251225a5
In addition to the configuration offered by the builder, the file app/config.js provides various additional settings. This is for example the place where you can override some settings like the list of Geocoder services to be used (changes override ArcGIS Online or your Organization default settings). See the documentation provided in that file for more details.
Cascade currently offers a light and dark theme and the option to choose between four different fonts. Other look and feel customizations can be done using the regular application download and including the css/html overrides directly into index.html. A style tag is already present for you in index.html (search for /* CUSTOM CSS RULES */).
As the application Javascript and CSS are minified, we don't recommend that you directly edit those files (e.g. viewer-min.css, viewer-min.js, ...). In addition to being hard to edit, this will make application update complex for you.
If you want to change the behavior of one functionality or want to add new one, follow the developer guide below.
The easiest way to find the ID or path of a DOM element that you want to customize is to use your browser's developer tools -- read the documentation for Chrome, Safari, Firefox.
This developer guide is intended for developers who want to modify the behavior of, or add new functionalities to, the Cascade application. It requires knowledge of HTML, Javascript and CSS languages.
For more infomation about using and customizing Esri's Storytelling Apps follow the Story Maps Developers' Corner.
Cascade fires events that allow customization with loose integration. This means that you don't need to understand the application internals to implement simple extensions.
To try those events, look in the file src/app/custom-scripts.js.
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
*/
// console.log('Cascade is ready');
});
/*
* Custom Javascript to be executed when a section becomes active
*/
topic.subscribe('story-navigated-section', function(/*cfg*/) {
// console.log('The section', cfg.index, 'is now active');
});
});In addition to the events described above, the story data, configuration and useful helpers functions can be accessed through the global variable app.
console.log("Story title", app.Controller.getStoryTitle());
console.log("Sections objects", app.data.sections);
console.log("First section bookmark", app.data.sections[0].getBookmark());
console.log("First section text preview", app.data.sections[0].getPreviewText());
console.log("Sections display informations", app.display.sections);
console.log("Second section vertical position (px)", app.display.sections[1].top);
console.log("IDs of all the ArcGIS content in the story", app.Controller.getArcGISContent());Clone the repository or download a copy of the repository as a zip file.
To build a production version of the application from the source code, you first need to install Node.js.
Then initialize the environment by running the following commands in the Cascade folder:
npm installnpm install –g grunt-cli
This will create a new node-modules folder in your project root with all the tools required to build the application. If you have trouble running the second command, see this documentation on how to install grunt-cli locally.
- Make accessible the Cascade folder on a web server. Use your favorite server or run one with
grunt server; this will start a server on port8080 - If using an ArcGIS Enterprise portal, configure the
DEFAULT_SHARING_URLproperty inapp/config.js(close to the bottom of the file) - Run the following command:
grunt dev - Navigate to index.html using the URL parameter
appidto specify the web item to be loaded, e.g.:http://localhost:8080/index.html?appid=ABCD(configuringindex.html>configOptions.appidis not supported in development mode) - If you want to use a non-public story or the builder you need to configure an
oAuthID inindex.html. Follow this procedure to add and register an application to get an OAuth application ID. Once you have that application, openindex.html, locate theconfigOptionssection and fill theoAuthAppIdproperty.
- Open a terminal and navigate to the Cascade folder
- Run the following command:
grunt
The deploy folder now contains the built application that you can deploy to your web server.
The build script performs code validation through ESLint. You can disable those validations by editing Gruntfile.js -- look for the following comments /* Comment out to disable code linting */.
Cascade relies on AMD and Dojo loader AMD for its application structure. Most of the viewer uses ES2015, and some builder components use React. The build chain is based on Grunt, r.js and Babel.
The application is structured as follows:
| Path | Contains |
|---|---|
| Gruntfile.js | Build configuration |
| src/ | Main source code folder with index.html |
| src/app/ | Javascript and CSS source code |
| src/app/config.js | App configuration file (loaded at execution time) |
| src/app/storymaps/tpl/ | Cascade modules (build configuration files in the root) |
| src/app/storymaps/tpl/builder/ | Builder modules (main modules are Builder.js, BuilderView.js) |
| src/app/storymaps/tpl/core/ | Core modules (main modules are Core.js, MainView.js) |
| src/app/storymaps/tpl/print/ | Print modules |
| src/app/storymaps/tpl/view/ | UI components of the viewer and builder |
| src/app/storymaps/tpl/view/media/ | Map, Scene, Image, Audio, Video, WebPage, Text |
| src/app/storymaps/tpl/view/section/ | Cover, Sequence, Immersive and Title sections |
| src/app/storymaps/tpl/view/ui/ | Header |
| src/app/storymaps/tpl/utils/ | Utils, sharing, some external libraries |
| src/app/storymaps/issue-checker/ | Issue checking utility (finds errors in story) |
| src/lib/ | Dependencies (included in the final app) |
| src/lib-build/ | Dependencies used by the build (not included in final app) |
| src/resources/ | Static resources |
The main dependencies are:
The application Javascript and CSS are minified into six files:
| File | |
|---|---|
| app/viewer-min.css | Compressed CSS loaded when accessing the story as a viewer |
| app/viewer-min.js | Compressed Javascript loaded when accessing the story as a viewer |
| app/builder-min.css | Compressed CSS loaded when accessing the story as an author |
| app/builder-min.js | Compressed Javascript loaded when accessing the story as an author |
| app/print-min.css | Compressed CSS loaded when accessing the story in print mode |
| app/print-min.js | Compressed Javascript loaded when accessing the story in print mode |
Depending on the URL parameters, index.html will load the corresponding files.
Find a bug or want to request a new feature? Please let us know by submitting an issue.
Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.
Copyright © 2016-2018 Esri
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
A copy of the license is available in the repository's LICENSE.txt file.
Some open-source components of this project are licensed under other License terms, see src/lib/ folder for respective license files.
| Library | License |
|---|---|
| Bootstrap | MIT |
| jQuery | MIT |
| MediumEditor | MIT |
| React | BSD with patent grant |
| React-redux | MIT |
| Redux | MIT |
| vimeo-player-js | MIT |
| youtube-api | N/A |
| Clipboard.js | MIT |
| ProgressJS | MIT |
| FastClick | MIT |
| Font Awesome | SIL/MIT |
| Sortable | MIT |
| React-Bootstrap | MIT |
| Loader | MIT |
| Hermite-resize | MIT |
| Babel Polyfill | MIT |
| jquery-mousewheel | MIT |
| Color Thief | MIT |
Additionally, The Unite Gallery open-source library is located at src/app/storymaps/tpl/utils/UniteGallery.js. It is licensed MIT; those portions modified by the Story Maps team are licensed Apache 2.0 with the rest of this project.