ucdavisdatalab / workshop_web_maps

Learn to build an interactive web map to display spatial data

Workshop: Building Web Maps with Leaflet

UC Davis DataLab
Winter 2022
Instructor: Michele Tobias <[email protected]>

• Reader
• Event Page

Description

In this workshop, attendees will be introduced to building an interactive web map to display spatial data using the Leaflet javascript library.

Learning Objectives

In this workshop, attendees will learn

• Introductory HTML skills, in particular, the tags that are most commonly used to format text on a webpage
• How to load javascript libraries into a web page
• An introduction to the Leaflet javascript library
• Where to get additional help with HTML and Leaflet
• Best practices for communicating data distributions with a web map

Skills

In this workshop, participants will be introduced to the following skills:

• HTML
• Javascript
• Leaflet Javascript Library

Prerequisites

Learners should have a basic understanding of spatial data formats such as vector and raster data, as well as experience with any coding language. Learners with previous experience with coding in HTML and javascript will have an easier time learning, but these skills are not required.

Template: Workshop Reader

This repository is a template for workshop readers for the UC Davis DataLab. This template uses bookdown to knit the reader. You can also optionally use renv to manage packages and Git Large File Storage to manage large files (instructions included).

To get started, create a new repo on GitHub from this template (instructions), then git clone your new repo.

Once you've cloned the repo, here's a checklist of things to do to prepare the repo:

1. renv (optional): To set up renv, open R at the top level of the repo and run:

   renv::init()

   Restart R. Then, to install the bookdown toolchain to the project package library, run:

   install.packages("bookdown")
   renv::snapshot()

   You can skip this step if you're not going to use renv.

2. index.Rmd: Replace the all-caps text with your workshop details.

   • Title (in 2 places, 1 of them in the output: HTML block)
   • Author's name
   • Repo name (in 4 places, 2 of them in the output: HTML block)
   • Description, learning goals, & prerequisites

3. README.md: Replace the all-caps text with your workshop details.

   • Title
   • Quarter & year
   • Author's name & email
   • Reader URL
   • Event URL
   • Description, learning goals, & prerequisites

4. GitHub: In the repo's About section, add the reader URL and appropriate tags.

5. GitHub: In the repo's Settings page, enable GitHub pages. Set the branch to master and the directory to docs/.

6. README.md: Remove these template instructions, which end at the # Workshop: header below

7. git add all changed files, then git commit and git push.

Contributing

The course reader is a live webpage, hosted through GitHub, where you can enter curriculum content and post it to a public-facing site for learners.

To make alterations to the reader:

1. Run git pull, or if it's your first time contributing, see Setup.

2. Edit an existing chapter file or create a new one. Chapter files are R Markdown files (.Rmd) at the top level of the repo. Enter your text, code, and other information directly into the file. Make sure your file:

   • Follows the naming scheme ##_topic-of-chapter.Rmd (the only exception is index.Rmd, which contains the reader's front page).
   • Begins with a first-level header (like # This). This will be the title of your chapter. Subsequent section headers should be second-level headers (like ## This) or below.
   • Uses caching for resource-intensive code (see Caching).

   Put any supporting resources in data/ or img/. For large files, see Large Files. You do not need to add resources generated by your R code (such as plots). The knit step saves these in docs/ automatically.

3. Run knit.R to regenerate the HTML files in the docs/. You can do this in the shell with ./knit.R or in R with source("knit.R").

4. Run renv::snapshot() in an R session at the top level of the repo to automatically add any packages your code uses to the project package library.

5. When you're finished, git add:

   • Any files you added or edited directly, including in data/ and img/
   • docs/ (all of it)
   • _bookdown_files/ (contains the knitr cache)
   • renv.lock (contains the renv package list)
   • .gitattributes (contains the Git LFS file list)

   Then git commit and git push. The live web page will update automatically after 1-10 minutes.

Caching

If one of your code chunks takes a lot of time or memory to run, consider caching the result, so the chunk won't run every time someone knits the reader. To cache a code chunk, add cache=TRUE in the chunk header. It's best practice to label cached chunks, like so:

```{r YOUR_CHUNK_NAME, cache=TRUE}
# Your code...
```

Cached files are stored in the _bookdown_files/ directory. If you ever want to clear the cache, you can delete this directory (or its subdirectories). The cache will be rebuilt the next time you knit the reader.

Beware that caching doesn't work with some packages, especially packages that use external libraries. Because of this, it's best to leave caching off for code chunks that are not resource-intensive.

Large Files

If you want to include a large file (say over 1 MB), you should use git LFS. You can register a large file with git LFS with the shell command:

git lfs track YOUR_FILE

This command updates the .gitattributes file at the top level of the repo. To make sure the change is saved, you also need to run:

git add .gitattributes

Now that your large is registered with git LFS, you can add, commit, and push the file with git the same way you would any other file, and git LFS will automatically intercede as needed.

GitHub provides 1 GB of storage and 1 GB of monthly bandwidth free per repo for large files. If your large file is more than 50 MB, check with the other contributors before adding it.

Github Actions

GitHub Actions can be set up to automatically render your reader when you push new content to a repo. If you would like to use this function, download the materials in datalab-dev/utilities/render_bookdown_site and follow the instructions there.

Setup

Git LFS

This repo uses Git Large File Storage (git LFS) for large files. If you don't have git LFS installed, download it and run the installer. Then in the shell (in any directory), run:

git lfs install

Then your one-time setup of git LFS is done. Next, clone this repo with git clone. The large files will be downloaded automatically with the rest of the repo.

R Packages

This repo uses renv for package management. Install renv according to the installation instructions on their website.

Then open an R session at the top level of the repo and run:

renv::restore()

This will download and install the correct versions of all the required packages to renv's package library. This is separate from your global R package library and will not interfere with other versions of packages you have installed.

Back to Top

workshop_web_maps's Issues

Feedback Section 3. Build a web page

Its a bit of a pain but I would add screenshots for each part in the reader. During the workshop itself I assume the learners will be able to follow along, but learners just working with the reader would benefit from more screenshots (even of just the empty page)

You may also want to add text explaining how to open the html file (right click, open with....)

Perhaps add a section 3.3:

Introduce the Inspector, firefox, chrome and derivatives such as brave, and Safari all have an inspect element tool with console.

Replace Text Editor

The workshop uses Atom, but that is being retired. We need to identify a new text editor that works across platforms to use in this workshop.

Preview the Data File in Section 4.3.1

From Arthur:
You may want to have a preview of the first few lines of the campus_cats.js file and mention that its a text file. You could even take some time to mention what a js file is, and what json is. You probably don't need to explain the difference in the workshop itself, but it may be nice as a note within the reader.

I think this is better addressed in Section 4.3.1

Replace or Rework Dataset

The cat data still works because we have our own copy of it, but the images were links to a site that has been taken down. Either we need to find a new dataset to work with or we need to improve the data we currently use.

Feedback Section 4. Build a Leaflet Web Map

4.1 Prepare your page

Add easy to copy version for the leaflet CSS file and Leaflet JS file

4.1.2

Maybe add border: 1px solid #333 on the map div.

4.3.3 Personally, I would move this to the head of the html

4.4.1

Add code chunks for this

End of 4.4 typo we bmapp

4.5

Perhaps, for the future of the workshop You could preview doing all of this with GitHub! Or add a Section at the very end showing the workflow (create repo, add code + commit, push, change settings on github, navigate to link)

Broken Links to Example Code

Probably need to check all the links to make sure they all work.

Feedback Section 2. Setting up your file structure

I would rename this section to "Setup".

2.1

In my experience, hosting the data through github (in this repo) and sharing the link to the raw file content is an easy way to share small ish files with the learners. That way you don't need to maintain the data at a different source, don't need to worry about any log in stuff.

You may want to have a preview of the first few lines of the campus_cats.js file and mention that its a text file. You could even take some time to mention what a js file is, and what json is. You probably don't need to explain the difference in the workshop itself, but it may be nice as a note within the reader.

2.3

Typo in the file tree:
index.htm

Feedback Section 5. Resources

Some additional resources:

Programming Historian walk through: https://programminghistorian.org/en/lessons/mapping-with-python-leaflet

Anatomy of a web map presentation: http://maptime.io/anatomy-of-a-web-map/

Link to leaflet R package: https://rstudio.github.io/leaflet/

Github Pages Documentation: https://docs.github.com/en/pages

Feedback Section 1. Introduction

1.1

Rather than the “often, the user can pan and zoom …” stuff I would directly define static vs dynamic web map:

Static map - An image of map. Can be useful for some applications. Especially for figures that summarize visual information. Since its an image it can easily be rendered by the browser.

[Screenshot of digital map]

dynamic web map - What people refer to when they say web map. Links data with an active mapping engine (think google maps). Allows users to interact with the data through zoom, pan, filtering, clicking, hovering… and many other features common in interactive data visualization. The mapping engine will handle the interactive elements to appropriately display the data. Data is displayed on some base map.

[Animated Gif of dynamic web map]

1.2

Some additional talking points for why make a web map:

• Help tell a narrative about the data
• Its fun to interact with and visualize data in novel ways
• Great for data that is inherently dynamic (many factors, time component)
• Data Validation
• They are easy to share.
• They are easy to modify and update.
• They are easy to document.

1.3

I wonder if ParkMobile uses leaflet?

1.5

I would mention that there are several alternatives to Leaflet, but that Leaflet is your preferred open source option. I would also mention that Leaflet has plugins and that there is a package in R for working with Leaflet.