Playlist

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

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

Data storage options

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.

FAQ

Is the template compatible with previous version?

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.

Can I deploy playlist on Portal for ArcGIS?

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.

Can I use private web map or layer?

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.

Can the template be used offline?

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

What's new?

Playlist 2.1.1 released on 12/12/2013

Update JavaScript API to version 3.8
Minor Bug Fixes

Playlist 2.1 released on 12/4/2013

Responsive UI to support tablets and smartphones
Click to copy Bitly link
Various bug fixes

Playlist 2.0 released on 11/22/2013

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

Developer guide

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.

Set up your local machine

Software

Download and install the following software

Git, Ruby, Ruby Dev Kit, Node

Steps

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 irb to run the Interactive Ruby shell. You should see: irb(main):001:0> in the console. Simply type exit to 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 init to set up the install configuration
- ruby dk.rb install to 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 bundler and 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.

Setup project folder

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

Preview and test development version

Run bundle exec middleman
Open http://localhost:4567/

Build project for deployment

Run bundle exec middleman build
Copy contents of the deploy folder to your web server

Feedback

We would love to hear from you!

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.

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

asizer / playlist-storytelling-template-js