handsondataviz / leaflet-storymaps-with-google-sheets

Scroll-driven story map, with point markers and narrative text in GeoJSON, using Leaflet and jQuery

Leaflet Storymaps with Google Sheets

Customize your Leaflet story map with linked Google Sheets template and scrolling narrative. Supports images, audio and video embeddings, and Leaflet TileLayer/geojson overlays.

Live links (replace with your own)

• Leaflet Map https://handsondataviz.github.io/leaflet-storymaps-with-google-sheets/
• Google Sheets template https://docs.google.com/spreadsheets/d/1AO6XHL_0JafWZF4KEejkdDNqfuZWUk3SlNlQ6MjlRFM/edit#gid=0

Create Your Own

• See step-by-step tutorial in Hands-On Data Visualization https://HandsOnDataViz.org/leaflet-storymaps-with-google-sheets.html

Geocode your address data with Google Sheets add-on

To geocode (find latitude and longitude coordinates), we recommend installing the free Geocoding by SmartMonkey add-on for Google Sheets. Insert your addresses in place of the samples in the Geocoding Details tab, then use Add-Ons > Geocoding > Geocode Details menu. Learn more in Hands-On Data Visualization https://handsondataviz.org/geocode.html

To finalize your map, you need to either:

• Download each Google Sheets tab as a CSV file and upload into a csv subfolder in your GitHub repo
  • OR
• Get your own Google Sheets API Key to insert into google-doc-url.js

See more in the tutorial https://handsondataviz.org/leaflet-storymaps-with-google-sheets.html

Update your code for any pre-October 2020 storymaps before January 2021

If you used our code to create a storymap prior to October 2020, you will need to update your version before January 26, 2021 for it to continue to work. Google announced that it will migrate from Google Sheets API v3 to v4 in Jan 2021, and we released our update of Leaflet storymaps code v1.2 on September 29th to address Google's changes.

Three options to update your code:

Option A: If you understand (or are willing to learn about) GitHub Desktop, use it to move copies of the newer code (index.html, scripts folder, markers folder, style.css, etc.) into your repo via your local computer. In the google-doc-url.js file, copy and paste the Google Sheets API key that appears in the lower half of our code, but keep your own Google Sheets ID that appears in the upper-half of your code.

OR

Option B: If you originally "forked" a copy of our code, create a GitHub "pull request" to update your repo with our code revisions, including the Google Sheets API key. We recommend this option only if you understand (or are willing to learn about) GitHub pull requests, and can deal with resolving conflicts between your code and our updated code. Warning: Since this operation might overwrite some of your code, go to Code > Download ZIP to make a backup to your local computer.

1. Log into the web interface of your GitHub storymap repository.
2. Click Pull requests and click the green button for a New pull request.
3. On the Comparing Changes page, use the menus to pull code into your repo from the original repo, named HandsOnDataViz/leaflet-storymaps-with-google-sheets. GitHub may warn that you cannot automatically merge the files, but proceed anyways.
4. You may need to click the Resolve conflicts button on the next screen, which means you need to sort out which portions of your code to keep and which portions of our code to accept. Generally speaking, you should accept our updates for index.html, style.css, and most scripts.js, while keeping your own content for README.md, media, and geojson folder content. In the google-doc-url.js file, you should keep your own Google Sheet ID, but temporarily add our Google Sheets API key until you create your own. In GitHub, you can resolve code conflicts by deleting/keeping lines in specific files.

OR

Option C: Start over with a brand-new repo, and migrate your existing map content. Make a copy of our newer code by clicking the green 'Use template' button. Migrate any media folder or geodata folder content from your old repo to your new repo, by downloading to your local computer and uploading to GitHub. Reconnect your Google Sheet ID to the google-doc-url.js file in your new repo.

Email us at [email protected] if you need assistance with updating your code.

Credits (and licenses)

Developed by Ilya Ilyankou and Jack Dougherty with support from Connecticut Humanities and Trinity College, CT. Inspired by Code for Atlanta mapsfor.us (2016) https://github.com/codeforatlanta/mapsforus (BSD-3-Clause). Adapted from MUX Lab, Map Effects 100: https://github.com/muxlab/map-effects-100, see http://muxlab.github.io/map-effects-100/Leaflet/11_scroll-driven-map-navigation.html.

We use Google Sheets API version 4, with these open-source components:

• Leaflet v1.7.1 https://leafletjs.com (BSD-2-Clause)
• jQuery v3.5.1 https://code.jquery.com (MIT)
• PapaParse v5.3.0 to parse CSV with JavaScript (MIT)
• Font Awesome v5.8.1 https://cdn.fontawesome.com (MIT, SIL OFL 1.1)
• leaflet-providers (v1.10.2) https://github.com/leaflet-extras/leaflet-providers (BSD-2-Clause)
• Leaflet.awesome-markers (v2.0.4), manually updated to svg to allow hex and material icons https://github.com/sigma-geosistemas/Leaflet.awesome-markers (MIT)
• Leaflet.ExtraMarkers (v1.0.5) https://github.com/coryasilva/Leaflet.ExtraMarkers (MIT)
• jQuery-CSV (v1.0.11) https://github.com/evanplaice/jquery-csv (MIT)
• Single Element CSS Spinner (31 May 2016) https://github.com/lukehaas/css-loaders (MIT)
• Lightbox by Lokesh Dhakar (v.2.11.3) https://github.com/lokesh/lightbox2 (MIT)

leaflet-storymaps-with-google-sheets's Issues

suggestions for code improvements and/or tutorial tips

@ilyankou - Thanks to my partner Beth @jhsgh we have another interesting storymap demo (https://github.com/jhsgh/storymap) and her suggestions for code improvements and/or tutorial tips. Let's discuss whenever we have time. She writes:

All in all this is a great tool! A few things I’ve noted while working on this:

• File pathnames to media are case sensitive
• Even the .jpg extension seems to need to be lowercase. When I uploaded media with .JPG (in ALL CAPS), they would not display in the map
  -Media file size can be an issue; files that are too large show up as broken links in the map. Can you add a warning about suggested max file size, or recommend that users resize images to an ideal size?

Tip:
In my storymap (https://jhsgh.github.io/storymap/) I was able to include multiple photographs of the same location by listing them in adjacent rows, leaving off the chapter name, and leaving the address info blank.

Code requests:

• If feasible, I would like the option to color-code numbers on the map to categorize them. For instance in this case, synagogues established after a certain date would be a helpful category. Perhaps you could add this option as a column in the Google Sheet?
• If feasible, could there be options to change the font and size of the map title and subtitle?
• Best way to insert a logo in the title? In my map I did this by inserting a blank chapter.

Note:

• in the book tutorial, be sure to explain how to insert hyperlinks in the body of chapter text

does not work with 1st generation ipad

should we standardize our list of GeoJSON feature properties?

Hi @ilyankou -- As I'm finishing Chapter 13, I'm looking back at our Aug 14th emails and am trying to recall if it's feasible or advisable to standardize our list of feature.properties for displaying overlays based on the original GeoJSON file.

feature.properties.weight
color
opacity
fillColor
fillOpacity

Based on the emails below, I recall we agreed this was not a broad, urgent need. But if it's just a matter of standardizing our list, it would be a great way to show in the soon-to-be updated demo storymap and chapter text how users can set the properties inside their GeoJSON files when creating them, which is great for displaying complex ones such as choropleth maps.

Let me know what you think. Here's the relevant emails from August (with some updated links):

I tried inserting “props.fill” and could not make it work. But then I inserted “feature.properties.fillColor” at the front of the list, and it worked perfectly.
See https://github.com/HandsOnDemo/storymap4/blob/main/scripts/storymap.js#L341

Jack

On Aug 14, 2020, at 11:55 AM, Ilya Ilyankou [email protected] wrote:

The property needs to be called COLOR or fillColor (see https://github.com/HandsOnDataViz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L328 ), but now when I think about it, "fill" makes more sense, just like "stroke".

This:
fillColor: feature.properties.COLOR || props.fillColor || 'white',

means the tool will first try COLOR, if value is not found, it will move to fillColor, and if that's not found, then defaults to 'white'. You should be able to add another value (props.fill) in the chain.

impossible to display levels 19 and 20 of an overlay tile layer

In the chapter Overlay cell, I added as stated link to a overlay tile map. Display is fine from levels 15 to 18 but impossible to have levels 19 to 20 displayed.
I changed maxZoom values in line 86 to
L.tileLayer.provider(basemap, {maxZoom: 20}
but no effect. Is there another place where max Zoom for overlays are specified ?

Also, I did install a slider on the map to change overlay opacity but It doesn't work (console says : ReferenceError: Can't find variable: overlay)
Here's slider in html :

Scroll listener is initialized multiple times (?)

Correct me if I'm wrong, but it appears that because the scroll listener is located inside the onEachFeature function, the listener is called once for every feature in the featureCollection. This means that the flyTo function is called repeatedly, which could have performance issues.

onEachFeature: function (feature, layer) {
  (function(layer, properties) {
    ...
    $('div#contents').scroll(function() {
      ...
      map.flyTo(....

I don't yet have an alternative approach, I just thought I'd raise the issue in case you're already aware of it. I'm also aware that you've parked this project for the meanwhile.

Cheers,
Steve

Using multiple media

Hi !
thanks very much for this very useful code !
I'd like to know what changes could be done to allow the use of different media in chapters, like an image + a sound + whatever.
I also would love to insert galleries instead of single image (and allow images to open full screen or in a lightbox).
Another option could be interesting : add a column in the .csv with a link to a sag to personnalise every marker.
Thanks very much for your help !

add Google Analytics option

in the Options, consider adding a box for author to enter their Google Analytics tracking ID (such as UA-5488840-29)

and add the tracking code to the index.html page

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-5488840-29"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'UA-5488840-29');
</script>

please remove google_v4 branch

@ilyankou
we no longer need it, and its presence will confuse new users
thanks!

Heatmap

How can i add a Headmap in one part of the story?

change anchor at bottom of narrative

options

1. back to top text/button
   or
2. refresh browser button

A missing > ?

Not sure if I'm missing something in how the pages are getting put together. Sorry if I am, but it seems like this should have a closing >

mediaContainer = $('<div></div', {

leaflet-storymaps-with-google-sheets/scripts/storymap.js

Line 206 in a25746c

mediaContainer = $('<div></div', {

Probably something that browsers just deal with, but noticed it as I was browsing the code and was curious if I'm missing something.

Thanks! I'm loving this solution to lots of problems!

problem with move scroll fast

Hi jack

I'm trying to reproduce your story map code for my need, but I have a problem when I move the scroll fast, my geojson layers dont work well, dont remove or refresh in the new map.

The position conteiner, texts and others elementes of my story map worked with success, but the layers o geojson dont.

you may help me with may problem?

this story map is an interesting tool for me

tks

preparing for next release, please add CSV upload

Hi @ilyankou

Here's what I've done so far to help us move ahead toward the next release

1. Updated Google Sheet and removed old Geocoder script
2. Added your fav favicon!
3. Updated CDNs in index.html, except I'll leave leaflet-providers for you. CartoDB has updated for https, so we can pull from CDN rather than local modified code.
   <script src="https://unpkg.com/[email protected]/leaflet-providers.js"></script>
4. Updated README

Would you please add the CSV upload feature? It is not yet working. I added a csv folder, where the Options Storymap Title = "My Story Map from CSV" to help you know when it is working properly. When it does, please delete the csv folder.

Please remove the non-master branch.

Also, when everything is ready, please make a new release version in the GitHub repo, and match it to the title of the Google Sheet

add option to make responsive storymap appear side-by-side vs. top-bottom?

Hi @ilyankou -- While working on images for chapter 13, I wondered if we have an option to manually determine how the storymap appears, such as "always side-by-side" or "always top-and-bottom" or "responsive" (default). Not urgent, but let me know what you think, since I believe this is a case where side-by-side might be preferable, but I don't currently see an easy way to control it.

No zoom steps when using + zooming button for the first time

When story has scrolled to a new chapter, when + button is clicked on map to zoom, zooming goes directly to the highest zoom level without zooming step by step.

Help proposed

Hello,
I've been building interactive maps from your code and have brought many addons (icon customization, geojson overlay with interactive actions, element properties display in narrative, lightbox for fullscreen image and video display). I would like to propose you my help if ever you are to wish to add this elements in the native code. This additions may not be perfect but they may help you take them further.
Here are some exemples :
https://www.weneedtotalkabouttheborder.eu
https://www.laurentgontier.com/Storymap_Normandie/
In the latest, check for "CITÉ DE SOYE" chapter on the page (use search function for the browser) to see a geojson overlay exemple (polygons are clickable); Red polygons have popup with photos.
Thank you very much for your good work !
Laurent

Change base map drop down on google sheet

Hiya,

I would like to add: Esri.WorldImagery and a few others to the dropdown on the 'Options' tab under Base Maps on the google sheets template, can you advise how I can do that please?

The main reason for wanting to do this is because the other base maps don't cover the area where I want my story map so it just shows as grey.

All the best,
Mark

Overlay does not show

Maybe I am doing something wrong, but if I place my own PNG and TIFF in the media-directory and place the link in the Sheet it does not show. I used a PNG and a TIFF which I exported from QGIS. After import them again they show up any the right place in QGIS.

Browser navigation and new page trigger

Your story-map template is excellent ! However, I've noticed that it tends to register every move that the user makes as a new web page. Eventually, I'm unable to use my browser to navigate back from the demo (Figure). Same thing in Chrome and Mozilla. Do you have an idea how to prevent this behaviour ?
Thanks !

Add a custom number or id to the marker

Apart from the option "Numbered", add an option "CustomNumbered" (or similar), and a way to specify the custom number or identifier of the marker.

Uncaught TypeError

Getting an error relating to turning overlays on and off in the newest version:
Uncaught TypeError: Cannot use 'in' operator to search for '_leaflet_id' in undefined
Looks like the code in lines 313-320 is causing the trouble

Last item in list isn't targeted

When the browser height is greater than ~850px, the last item in the list isn't targeted and the map won't zoom to it's location.

feasible to add slugify to Storymaps?

@ilyankou - I liked your slugify solution in Leaflet Point Map with Sidebar so much that I wonder if it's feasible for you to add it to Leaflet Storymaps. One reason is that CTH is going to want to add some internal links in long storymaps, to help people see connections between chapters at the beginning and end.

If feasible, let me know if you recommend linking it to the chapter title (which may not be unique) or to the chapter row number (1, 2, 3..., if the code tracks those). Also, your estimated time to add this code.