Friday, December 23, 2016

analysis of JS: create your own Storymap with leaflet and hosted by GitHub Pages

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


Scroll-driven navigation, using screen swipe, trackpad, or keyboard down-arrow. Initial map displays all point markers.
Viewers can pan and zoom the map independently of the narration, or click on any point to go directly to that chapter.
Easy-to-learn template to create your own storymap.
Upload text, point coordinates, zoom levels, and image links to a CSV generic spreadsheet, and drag into to create a GeoJSON data file.
Images can be stored in local subfolder or pulled from an external URL.


Due to GeoJSON data limitations, there is no easy way to insert hyperlinks inside the 'description' text. They must be created outside, in fields such as "source-link" (see below in "comment")

Requires open-source libraries

Now use the plugin leaflet.extra-markers to create a marker like this:

  // Creates a red marker with the coffee icon
  var redMarker = L.ExtraMarkers.icon({
    icon: 'fa-coffee',
    markerColor: 'red',
    shape: 'square',
    prefix: 'fa'

  L.marker([51.941196,4.512291], {icon: redMarker,}).addTo(map);


The Leafet 1.x code includes a 'fly to' feature that animates the distance traveled from one map point to the next. Users with some coding skills can easily modify the background map, or add map overlays, or extend the code by adding new features.

Click on map.geoJSON. You can directly open the map in GitHub.

Click on map.CSV. You can directly open the tab in GitHub.

The structure of the HTML:
div "title"
div "narration"

  • "contents"
    • "space-at-the-top"
    • "container1"
    • "container2",  etc...
Dans chaque container1:
<div id="container1" class="image-container inFocus">
  • <p class="chapter-header">Hartford Public High School 1847</p>
  • <div class="img-holder"><img src="img/1847-HPHS-Catalog1904p164.jpg"></div>
    <a href="" target="_blank" class="source">
    Source: HPHS Quadrennial Catalogue 1904</a>
  • <p class="description">This scroll-driven storymap is built on an open-source Leaflet template. The design is ideal for telling a story that narrates different locations on a map. Or users can click any marker point to go directly to the chapter narrative.</p>

it's a small JS.

// create map
// loads the GeoJSON map data file from a local folder

  1.  // first, creates numerical icons to match the ID numbers avec ExtraMarkers.icon and put on the map (layer.setIcon)
  2. // creates the contents of each chapter from the GeoJSON data. Unwanted items can be removed, and new ones can be added. Rem: It's easy to add new structure.
  3. // Calculating total height of blocks above active
  4. Only one scroll for all slides (in "contents")
    Where there is an event  scroll of "contents", you have this js:
    $('div#contents').scroll(function() {
               if ($(this).scrollTop() >= areaTop && $(this).scrollTop() < areaBottom) {
                  $('div#container' +['id']).addClass("inFocus").removeClass("outFocus");

                  map.flyTo([feature.geometry.coordinates[1], feature.geometry.coordinates[0] ],['zoom']);
  5. map.flyTo is only available with leaflet v1
    Sets the view of the map (geographical center and zoom) performing a smooth pan-zoom animation.
  6. end (initMap)


Before you begin, review previous tutorials in this book:
  • Edit and Host Code Templates with GitHub
  • Create and Convert Map Data with
Go to the GitHub repository template ( and fork a copy of this repo to your own GitHub account. Requires signup for a free GitHub account. 
Reminder: if you have already forked one copy, go to your GitHub repository Settings to rename or delete the first copy, so that you may create a second copy.

Go to your copy on GitHub and click the "download" button to create a zipped (compressed) copy on your local computer. On most computers, double-click to unzip the folder.

The input

The map.csv file contains the map data in an easy-to-edit format. 

Open map.csv with any spreadsheet tool and replace the existing data with your own.

The structure is:
  1. id -- Assign numbers 1, 2, 3. . to each point, in desired order of appearance.
  2. chapter -- Add title for each section of the narrative.
  3. zoom -- Insert a zoom level for each chapter, usually between 11 (zoomed out) and 18 (zoomed in).
  4. image -- If storing images in local "img" folder, follow this format: img/photo1.jpg. Or if loading images from an external site, insert the full URL. Currently, images must be about 300px wide and roughly similar height.
  5. source-credit -- Add caption to credit the origin of the image. Write in this format: Source: ABC or leave blank if none.
  6. source-link -- Add a URL to make the source-credit appear as a hyperlink, or leave blank if none. (If you want a link in your text, you must put here)
  7. description -- Add text to display in the narrative. Currently, the length is not adjustable.
  8. lon and lat -- Insert the longitude and latitude coordinates of each point. 

To find coordinates in Google Maps, right-click any point and select What's Here. Reminder: Google Maps stores points in lat-lon format, but GeoJSON stores them in the reverse order (lon-lat, the same as X-Y coordinates in mathematics), so enter carefully into the map.csv spreadsheet.
Save the spreadsheet in CSV format. 

Open in a browser.

Drag in the map.csv file to inspect your point data. 
To export, save in GeoJSON format, and the browser will download a file named: map.geojson.

Go to your forked repository of leaflet-storymap 

Go to your forked repository of leaflet-storymap in your account. Click on 'branches' and keep the master branch, but delete any others (such as gh-pages and/or dev).
In the master branch of your repo, click on Upload Files button, upload the two new files you created on your local computer, and replace the existing files with those names.
  1. In your master branch, click on the index.html file, 
  2. click on the pencil icon to turn on the editor, and edit lines 7 and 22 to change the titles that will be displayed. 
  3. When done, scroll down and click the clean Commit Changes button to save your edits to the master branch.
Host your storymap code on the live web with GitHub Pages. At the top level of your repo on, select the master branch drop-down menu, and type in this new branch name: gh-pages. When you first create this branch, it contents may take several minutes to appear the first time on the public web, but updates will take only seconds to appear. Your public URL follows this format:
Learn more about how to edit your GitHub branches and make 'pull requests' to save changes from one branch to the other in the GitHub section in this book.

No comments:

Post a Comment