Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ralucanicola/workshop-holiday-map

An (intermediate) introduction to web technologies - creating a map of holidays
https://github.com/ralucanicola/workshop-holiday-map

Last synced: 25 days ago
JSON representation

An (intermediate) introduction to web technologies - creating a map of holidays

Awesome Lists containing this project

README 

        
# Map your holiday - EuroCarto 2022 Workshop



## Workshop Prerequisites



- Node.js 16.0+ - [Installation](https://nodejs.org/en/)

- [VSCode](https://code.visualstudio.com/)

- git - [Installation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) (optional, only if you want to publish your project on the web later on)



## The one where we set up the project locally 🏠



In the command line (tip - I use [Hyper](https://hyper.is/) and I love it):



If you want to use `git` then you can go to the [Github project](https://github.com/RalucaNicola/workshop-holiday-map) and fork the project. Then you can clone your own repository:



```

git clone [email protected]:yourGithubUsername/workshop-holiday-map.git

```



If you don't want to use `git` then you can download the repository on the [github website](https://github.com/RalucaNicola/workshop-holiday-map). [Here is a description](https://sites.northwestern.edu/researchcomputing/resources/downloading-from-github/) of how to do that. Unzip the folder.



Go to the newly created folder and install the dependency libraries:



```

cd workshop-holiday-map

npm install

```



To start a local server with the project:



```

npm run dev

```



Then open your browser at http://localhost:3000/



## The one where we discover the structure of the story 🕵️



Take a look at the structure of [index.html](./index.html). The story map has:



- the intro page of the story. You can add the title of the story and a description with an intro image. You can change the styling in [general.scss](./src/general.scss).

- the content with different sections for each part of the story. The id of the section is important, we will link it with the geodata. The content can be text, video or images.

- at the end of the content there is a map panel. This has a fixed location at the bottom of the screen and scrolling through text is synchronized with what is being shown in the map.

- the closing page of the story (text and image)



At this part start drafting the structure of your story and replace the content in my template. Add a title, add content for the different sections and what you want to display on the map.



## The one where we set up the map 🗺️



To create the map you'll need a free [ArcGIS Developer account](https://developers.arcgis.com/sign-up). Once you created it and confirmed your email address go to the main page and click "Upgrade to developer account". If you go to API keys you should see a default key:



![api key](./public/assets/api-key.png)



Copy the Default API Key and paste it in the `esriConfig.apiKey`: [see on Github](https://github.com/RalucaNicola/workshop-holiday-map/blob/main/src/main.ts#L13).



Now you can create a web map:



1. Go to the [ArcGIS Map Viewer](https://www.arcgis.com/apps/mapviewer/index.html) and login with the account you created.

1. Activate the "Basemap" selection tool.

1. Choose a basemap.

1. Save the web map.

1. Copy the ID.

1. Share it (Choose: "Everyone (public)").

1. Load it in the application using your ID.



![Steps to create a web map](./public/assets/steps-to-create-a-webmap.png)



Note: It's out of the scope of this workshop, but if you'd like to create a custom vector tile basemap, you can do it with the [Vector Tile Style Editor](https://developers.arcgis.com/vector-tile-style-editor/).



## The one where we set up the bookmarks 📖



For a certain section of the storymap, you'll want to zoom to a location. We can store these locations by using bookmarks. In [ArcGIS Map Viewer](https://www.arcgis.com/apps/mapviewer/index.html) open the map you previously created and:



1. Go to Bookmarks.

1. Zoom and scroll on the map to go to the viewpoint you want to have in your section. Click to Add a new bookmark.

1. Name that bookmark using the section id.

1. Save the map



![Steps to create a web map](./public/assets/steps-to-create-bookmarks.png)



## Synchronizing the map and the text - how does it work ❓



When the application loads, when the user scrolls or when the window is resized we calculate which section is currently visible. The id of the current visible section is used to either animate a path from [tracks.geojson](./public/data/tracks.geojson) (with the same id), to go to a map viewpoint or to filter the points in [points.geojson](./public/data/points.geojson).



## The one where we create the data 💾



I used [geojson.io](https://geojson.io/) to create the [point and line data](./public/data/) for this project. I animated the line data based on the scroll progress of a certain section and I filter the points based on the section they're supposed to be displayed in.



For example, the point that should be displayed in `"section-0"` will have a property `id` with the key `section-0`. The same for the tracks that will be animated. A polyline that should be animated in `"section-1"` will have a property `id` witht the key `section-1`. Have a look at the [data](./public/data/).



## The one where we spend some more time polishing the project 💅



Maybe you want to rephrase that sentence? or change the style of the basemap? or swap this image for another one where you look much better 😉

This is where we do all these final changes.



## The one where we go public - deploying project to [GitHub Pages](https://pages.github.com/) (optional) 🌐



Once you are happy with your map you can create a production build and deploy it to [GitHub Pages](https://pages.github.com/).



```

npm run build

```



The `dist` folder then contains all the files for the web app which can either be copied to a web server or pushed to the `gh-pages` branch to be served at `https://arnofiva.github.io/arcgis-core-template`.



In order to use the `gh-pages` approach, see the following instructions. Make sure you remove an existing `dist` folder if it has been created from a previous build.



### Create `gh-pages` branch



Follow these steps to create an orphan `gh-pages` branch (meaning it does not share any history with `main`):



```

mac: rm -rf dist // windows: rmdir dist

git checkout --orphan gh-pages

git rm -rf .

git commit --allow-empty -m "Init empty branch"

git push origin gh-pages

```



Return to `main` branch:



```

git checkout main

```



### Checkout `gh-pages` branch in `dist/` folder



The following will create a `dist` folder (fails if it already exists) and make it point to the root of the `gh-pages` branch:



```

git worktree add dist gh-pages

```



### Deploy new version on `gh-pages` branch



Once the previous steps have been completed, you can repeat the following every time you want to deploy a new version of your local code:



```

npm run build

cd dist/

mac: touch .nojekyll // windows: echo.> .nojekyll

git add .

git commit -am 'Deploy'

git push origin gh-pages

cd ../

```



Note: we need to add the .nojekyll file in the dist folder because Jekyll doesn't copy files that start with underscore to the final site and like this we bypass it.

[See more explanation here](https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/).