Story Map Cascade

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.0.3, if you want to be informed of new releases, we recommend you to watch this repository (see GitHub help). See the release page for release notes.

Introduction

A Cascade story can be created from ArcGIS Online, from the Esri Story Maps website or from a Portal for ArcGIS deployment. The Cascade's data are stored in a Web Application Item. This repository provides the application source code for developers that 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.

Instructions

First create your Cascade story in ArcGIS Online using the step-by-step tutorial. Once your story is ready, you have to find its ID in ArcGIS Online. 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 41 and paste in your application ID
Navigate to index.html (e.g., http://127.0.0.1/Cascade/index.html)

Enjoy! You can continue to use the builder in ArcGIS Online 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 Portal for ArcGIS, please follow the instructions at the end of app/config.js to configure the application.

Feedback / support

We would love to hear from you!

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.

FAQ

For more answers, please see the Story Map website FAQ page it includes a section about Cascade.

What are the supported browsers?

Cascade stories are supported on Internet Explorer 11 and above, Chrome, Firefox, Safari and the most recent tablet and smartphone devices. During the beta period, Cascade authoring is only supported on Chrome and Safari on a desktop computer. We are working on supporting more 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.

Tips for your content

We have a series of blog posts coming, stay tuned!

Security

Can I keep my story private?

Yes, the regular ArcGIS Online security model applies. By default your story is private, you can share it through Cascade builder or ArcGIS Online. When you share your story, it is your responsibility to make sure that all the resources of your story (webmaps, webscenes, images, videos) are accessible to your audience.

Can I use private web map or layer?

Yes.

When the story is hosted in ArcGIS Online or Portal for ArcGIS, users that don't have access to the story or a webmap used in the story will be redirected to the ArcGIS Online sign-in page. It is not possible to display an authentication dialog in the application when it's hosted in ArcGIS Online.

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 and Portal for ArcGIS users with developer or organizational accounts. Follow the following 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 a proxy rules to specify what services need to use the proxy by editing PROXY_RULES in app/config.js.

Deployment

Deploying a Cascade require to use ArcGIS Online or Portal for ArcGIS. The Cascade content have to be created using the Cascade builder and will live in a Web Application Item.

Can I use the template without ArcGIS Online or Portal for ArcGIS?

This is not a supported use case at that time. Please let us know if you are interested by such a scenario. Cascade rely heavily on the Portal for ArcGIS API but it is doable to modify the application to support other scenarios.

Where is the data stored?

The Cascade data are stored in a Web Application Item in ArcGIS Online or Portal for ArcGIS. This include the narrative content, reference to the webmap(s), webscene(s), picture(s), video(s), web page(s) and the settings.

The image and videos that you include in your story using the builder are not copied in ArcGIS Online except if 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.

Can I deploy Cascade on Portal for ArcGIS?

Cascade will be included with Portal starting at 10.5. The application is not supported with earlier version but it works with some of the most recent version.

Can I use the builder with the downloadable?

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.

How to deploy the application on a web server?

If you are not familiar with web servers here is three solutions:

Use a free hosting service like Dropbox, you may have to configure Dropbox to enable webpage hosting
Use the web server that comes with your server Operating System. On Windows this is Internet Information Services (IIS), if you have a C:\inetpub\wwwroot folder on your computer, you should be able to access it's content using http://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 symbol appearing instead of icons, you will have an extra configuration to perform. Some servers require to configure a new mime type to be able to serve Cascade fonts correctly. See the following links for more information:

Can I use a single deployment of Cascade for multiple stories?

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 Portal for ArcGIS login of the owner(s) of the story you want to use. This make possible for the application to display any of stories created by the specified user(s) through an URL parameter.

Example of the same application displaying two stories:

Configuration

In addition to the configuration offered by the builder, the file app/config.js provide 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.

Customize the look and feel

Cascade doesn't yet offer a configuration experience to customize the application colors. Most of the look and feel customization 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 directely 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 developer tool, read documentation for Chrome, Safari, Firefox.

Developer guide

This developer guide is intended for developers that wants to modify the behavior 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.

Application life cycle

Cascade fires events that allow customization with lose integration. This mean that you don't need to understand the application internals to implement simple extension.

To try those events, look for the Custom Javascript block at the far end of index.html.

...
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-navgigated-section", function(cfg){
    console.log("The section", cfg.index, "is now active");
  });
});
...

Developer helpers

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());

Environment setup

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 install
npm 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.

How to use the application from the source code

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 port 8080
If using a Portal for ArcGIS instance configure the sharing url app/config.js (last property)
Run the following command: grunt dev
Navigate to index.html using the URL parameter appid to specify the web item to be loaded, e.g.: http://localhost:8080/index.html?appid=ABCD (configuring index.html > configOptions.appid is not supported in development mode)
If you want to use a non-public story or the builder you need to configure an oAuth ID in index.html. Follow the following 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.

How to build application from the source code

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.

Issues building the application

The build script perform code validation through ESLint, you can disable those validations by editing Gruntfile.js and look for the following comments /* Comment out to disable code linting */.

Design

Cascade relies on AMD and Dojo loader AMD for application structure. Most of the viewer use ES2015 and some builder components use React. The build chain is based on Grunt, r.js and Babel.

The application is structured as this:

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/common/	Modules common across storymaps templates (main module is Core.js)
src/app/storymaps/common/builder/	Builder modules (main module is Builder.js)
src/app/storymaps/common/ui/	UI components
src/app/storymaps/common/utils/	Utils, connector,...
src/app/storymaps/common/_resources	Static resources
src/app/storymaps/tpl/	Cascade modules (build configuration files in the root)
src/app/storymaps/tpl/builder/	Builder modules (main module is BuilderView.js)
src/app/storymaps/tpl/core/	Core modules (main module is MainView.js)
src/app/storymaps/tpl/view/	UI components of the viewer and builder
src/app/storymaps/tpl/view/media/	Map, Scene, Image, 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
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 four 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

Depending on the URL parameters, index.html will load the corresponding files.

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

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 licence files.

Library	License
Bootstrap	MIT
jQuery	MIT
MediumEditor	MIT
React	BSD
React-redux	MIT
Redux	MIT
Fluidbox	MIT
Froogaloop	N/A
youtube-api	N/A
ZeroClipboard	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

[](Esri Tags: Storytelling Cascade ArcGIS-Online Template) [](Esri Language: JavaScript)

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
src		src
.babelrc		.babelrc
.bowerrc		.bowerrc
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.txt		CONTRIBUTING.txt
Gruntfile.js		Gruntfile.js
LICENSE.txt		LICENSE.txt
README.md		README.md
bower.json		bower.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Story Map Cascade

Help content

Introduction

Instructions

Feedback / support

FAQ

What are the supported browsers?

Tips for your content

Security

Can I keep my story private?

Can I use private web map or layer?

Deployment

Can I use the template without ArcGIS Online or Portal for ArcGIS?

Where is the data stored?

Can I deploy Cascade on Portal for ArcGIS?

Can I use the builder with the downloadable?

How to deploy the application on a web server?

Can I use a single deployment of Cascade for multiple stories?

Configuration

Customize the look and feel

Developer guide

Application life cycle

Developer helpers

Environment setup

How to use the application from the source code

How to build application from the source code

Issues building the application

Design

Issues

Contributing

Licensing

About

Releases

Packages

Languages

License

cooney/storymap-cascade

Folders and files

Latest commit

History

Repository files navigation

Story Map Cascade

Help content

Introduction

Instructions

Feedback / support

FAQ

What are the supported browsers?

Tips for your content

Security

Can I keep my story private?

Can I use private web map or layer?

Deployment

Can I use the template without ArcGIS Online or Portal for ArcGIS?

Where is the data stored?

Can I deploy Cascade on Portal for ArcGIS?

Can I use the builder with the downloadable?

How to deploy the application on a web server?

Can I use a single deployment of Cascade for multiple stories?

Configuration

Customize the look and feel

Developer guide

Application life cycle

Developer helpers

Environment setup

How to use the application from the source code

How to build application from the source code

Issues building the application

Design

Issues

Contributing

Licensing

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages