The playlist app is a storytelling template that organizes point data sets, usually from a CSV file embedded in a web map, into an organized interactive list. Your audience can explore the points from the map itself or they can click on a corresponding item in a list.
View it live | User Download (source code not included) | Developer Download
Latest release is version 2.1.1, if you want to be informed of new releases, we recommend you to watch this repository.
This help will guide you through the steps for publishing playlist apps like:
- How to deploy a playlist app
- Data storage options
- FAQ
- What's new
- Developer guide
- Feedback
- Issues
- Contributing
- Licensing
To use the downloadable version, download the User Download; it contains the following files:
| File | Contains |
|---|---|
| app/ | Minified source code |
| resources/ | Application resources (markers, icons, fonts) |
| samples/ | Sample data to create your web map |
| index.html | Application html file (Contains app configuration) |
| license.txt | Application terms of use |
| Readme.pdf | How to create your first app |
To create a playlist tour follow a few simple steps, outlined below. To successfully publish your story map using this template you’ll need to be able to host the application and the photos you will use on a publicly accessible server and you’ll also need an ArcGIS Online account (public or subscription) to author and save the map used in the playlist. The storytelling playlist app relies on a web map ID from ArcGIS Online to get the data.
Currently, the playlist supports CSV or feature service layers that have been added to a web map.
To get started, follow these basic instructions:
- Open ArcGIS Online web map viewer
- Create a web map that fits your needs (basemap, additional context layers, etc.)
- Import your playlist data layers into the web map
- Save the web map at the initial extent that you would like your playlist to begin
- Share your web map with everyone
- Open index.html with a text editor
- Scroll down till you find the configOptions settings and edit these options
- webmap: unique identifier for the ArcGIS.com map.
- showMultipleLayersAsTabs: If true and more than one playlist compatiple layer is found, each layer will include a tab.
- dataFields (change only if not following sample data)
- nameField: field to be used as playlist text
- imageField: field to be used as thumbnail in playlist
- colorField: field to determine marker color
- orderField: field to determine playlist order
- filterField: field to determine what items will added to the search filter (leave blank to remove filter)
- playlistLegend
- layerTitle: name the playlist layer for display in the map legend
- items
- visible: choose (true or false) if item is visible in legend
- name: add name for item to be displayed in legend
- dataFields (change only if not following sample data)
- excludedLayers: If a playlist compatiple layer is found that should not be included in the list, add a unique string from the layer name.
- layerProperties: Configure layer specific properties
// Sample Layer Properties Array
// {
// "layers": [{
// "name": "sampleLayer1", // Unique text string from layer name
// "properties": {
// "keepWebmapStyle": true, // Set to true to use symbology defined in webmap
// "tabTitle": "Title for tab 1", // Text displayed in tab 1
// "tabOrder": 1 // Tab order (acsending)
// }
// },{
// "name": "sampleLayer2", // Unique text string from layer name
// "properties": {
// "keepWebmapStyle": false, // Set to false replace points with numbered icons.
// "tabTitle": "Title for tab 2", // Text displayed in tab 2
// "tabOrder": 2 // Tab order (acsending)
// }
// }]
// }
- Optionally remove samples folder and Readme.pdf
- Copy files to your web server root or in a specific folder
It is crucial for the application performance that your tour points have well-defined thumbnail images. Thumbnail images are used in the side playlist. If you choose to host the pictures yourself, you will have to manually create thumbnails of your pictures. Using the full resolution pictures for the thumbnail will result in poor performance. The recommended thumbnail size is 70x70px.
You can use any point Feature Service or CSV as a playlist data source as long as your layer follow the expected requirements detailed below. To use your layer, simply add it into your webmap through ArcGIS Online web map viewer.
| Fields | Valid fields names (case insensitive) |
|---|---|
| Name | name, title |
| Thumbnail | thumb_url, thumbnail |
| Color | color |
| Order | order |
If your playlist layer has different field attributes, you will need to change the dataFields options under the configOptions in the index.html.
The playlist template also supports thumbnails which will be displayed along side of item's title and map icon. These thumbnail will be pulled from the thumbnail attribute above but requires the images to be hosted on the web. The thumbnail can either be hosted on your organization's web server or on a third party service such as Flickr or Dropbox.
Yes, web map designed for the previous version should continue to work without any modification. Customization and enhancement of the application will require code changes, most of them should be easy to translate into the new application.
Yes, by default the playlist app expects web maps to be saved on ArcGIS.com. If you are using using portal, you will need to modify the sharingUrl option in the index.html. If you also require a login to the app, see below.
Yes, but you will need to install a proxy server on your web server to make sure the login credentioals can be pass securely to ArcGIS Online. For more information, see the Using the proxy page in the ArcGIS JavaScript documentation.
Yes, by using Portal for ArcGIS. When deployed on a Portal for ArcGIS instance, the Map Tour doesn't require any external service to function. But by default the template will still include the header social buttons and template publishers are able to import pictures from the some online pictures hosting services
- Update JavaScript API to version 3.12
- Option to display multiple playlist compatible layers as tabs
- Layer specific properties for playlist compatible layers including:
- Keep symbology defined in webmap (Numbers will be used in list instead of full numbered icon).
- When adding layers as tabs, there are options to modify the tab text and tab order.
- Update JavaScript API to version 3.8
- Minor Bug Fixes
- Responsive UI to support tablets and smartphones
- Click to copy Bitly link
- Various bug fixes
- Supports feature layers and shapefiles
- Search function with optional filter button
- Legend for playlist layers
- Toggle for legend and description
- Toggle side pane
- Banner will be removed when embeded
- Various bug fixes
This developer guide is intended to developer that wants to modify behavior or add new functionalities to the playlist application. If you only need to customize look and feel of the playlist, you should be able to do so using the User download. It requires basic knowledge of HTML, Javascript and CSS languages.
Download and unzip the Developer download or clone the repo. All changes should be made in the source/ folder of the source code.
Download and install the following software
- Git, Ruby, Ruby Dev Kit, Node
- Start by installing Ruby 1.9.3. As you step through the install make sure the following is selected
- Add Ruby executables to PATH
- When the installation is finished, verify Ruby was installed correctly by opening up a command prompt and running
irbto run the Interactive Ruby shell. You should see:irb(main):001:0>in the console. Simply typeexitto close irb, and then close the command prompt window. - Next, install the Ruby Development Kit. This download is just a self extracting archive, so pick a permanent place you want to extract the files to. (e.g. C:\rubydev)
- After the Ruby Development Kit has been extracted, open another command prompt window and change the directory to the location you extracted the files to: (e.g. C:\rubydev)
- We will be running two commands to setup the Development Kit to work with your Ruby installation:
ruby dk.rb initto set up the install configurationruby dk.rb installto link up the development kit to your Ruby location.
- While still in the command prompt window, the Bundler (http://gembundler.com/) gem will have to be installed so the project can run and download all the needed dependencies. Type
gem install bundlerand Ruby will install the gem. - Now install GitHub, and step through the installation process.
- Now install Node JS.
- Make sure to include the Node Package Manager (NPM) in your installation.
- If you haven't created your own fork of the playlist app, do so now by clicking on the Fork button in the upper left.
- You will now want to clone your forked repo to your local machine.
In order to modify pages locally on your machine you will have to set up GitHub and the development environment on your machine.
- Open git shell/bash at project folder
- Run
bundle install - Run
npm install -g grunt-cli - Run
npm install
- Run
bundle exec middleman - Open http://localhost:4567/
- Run
bundle exec middleman build - Copy contents of the deploy folder to your web server
We would love to hear from you!
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 2013 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.
[](Esri Tags: Storytelling Playlist Template) [](Esri Language: JavaScript)