Merge pull request #81 from openlayers/foss4g-2017

Updates for FOSS4G '17

.gitignore

@@ -1,21 +1,4 @@
-# ignore installed dependencies from node
 node_modules/
-
-# ignore complete build directory (pdfs etc)
 build/
-
-# from this folder gitbook serves its content
-src/_book
-
-# copied when the dev server runs (in each language folder)
-ol.css
-
-# from custom builds chapter, *.json and *.js (in each language folder)
-ol-custom.js*
-
-# the main example file (in each language folder)
-src/*/map.html
-
-openlayers-workshop-en.zip
-openlayers-workshop-fr.zip
-openlayers-workshop-pt.zip
+doc/_book
+openlayers-workshop-*.zip

.travis.yml

@@ -4,20 +4,17 @@ node_js:
   - 6
 script:
   - npm test
-  - node node_modules/openlayers/tasks/build.js src/shared/vector-chapter-build-config.json custom-build.js &&  stat -c "%n %s bytes" custom-build.js && rm custom-build.js
 cache:
   directories:
     - node_modules
 before_deploy:
-  - npm run archive:en && npm run archive:fr && npm run archive:pt
+  - npm run archive:en
 deploy:
   provider: releases
   api_key:
     secure: ag2ObhNaZYbULIABDARbHyvqk9DChYg6j6HZUmocdfM4Go/MF/OckpR0VntiMKpv+eQ8vdmTyRWVcW4Y/B+AOkMs/fhRs4rYOLq7BXWyLLbcvNaXP+3n6HDB/RZBPcNCYdQUo+oDDOyk7W9vF5T3o4aKlXFRLQIVQgABrwEQC1I=
   file:
     - openlayers-workshop-en.zip
-    - openlayers-workshop-fr.zip
-    - openlayers-workshop-pt.zip
   on:
     repo: openlayers/workshop
     tags: true

README.md

@@ -12,16 +12,9 @@ Start the development server:
 
     npm start
 
-Now you can modify the `src` content.  When adding new pages or restructuring things, update the `src/SUMMARY.md` (this is used to generate the content tree in the navigation).  Also update any of the nested `README.md` files (these provide the index page for each section).
+The workshop content is divided into two directories.  The `doc` directory contains the documentation sources.  The `src` directory contains all of the sources that will be used by workshop participants (e.g. data, examples, etc.).  The build process creates an archive with the build version of the docs together with the `src` files.
 
-## Updating the workshop with a new release of OpenLayers
-
-To update the workshop with a new release of OpenLayers one needs to change the version number of the `openlayers` dependency in four places:
-
-* Top level `package.json`,
-* English workshop `src/en/package.json`
-* French workshop `src/fr/package.json` and
-* Portuguese workshop `src/pt/package.json`
+When adding new pages or restructuring things, update the `doc/SUMMARY.md` (this is used to generate the content tree in the navigation).  Also update any of the nested `README.md` files (these provide the index page for each section).
 
 ## Creating a new release
 

archive.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+#
+# Run this script to generate a zip archive for the workshop in a single
+# language.
+#
+set -o errexit
+
+#
+# Destination directory for build.
+#
+BUILD=build
+
+#
+# Display usage and exit.
+#
+display_usage() {
+  cat <<-EOF
+
+  Usage: ${1} <lang>
+
+  Example:
+
+    ${1} en
+
+  This will generate a zip archive for the English version of the workshop.
+  The openlayers-workshop-en.zip should be posted to the release page.
+
+EOF
+}
+
+#
+# Exit if the current working tree is not clean.
+#
+assert_clean() {
+  source `git --exec-path`/git-sh-setup && \
+      require_clean_work_tree "publish" "Please commit or stash them."
+}
+
+#
+# Build the workshop and create an archive for a single language.
+#
+build_archive() {
+  npm run build
+  mkdir -p ${BUILD}/openlayers-workshop-${1}
+  cp doc/${1}/README.md ${BUILD}/openlayers-workshop-${1}/
+  cp src/${1}/*.* ${BUILD}/openlayers-workshop-${1}
+  cp -r src/${1}/data ${BUILD}/openlayers-workshop-${1}/data
+  cp -r src/${1}/examples ${BUILD}/openlayers-workshop-${1}/examples
+  cp -r ${BUILD}/openlayers-workshop/${1} ${BUILD}/openlayers-workshop-${1}/doc
+  cp -r ${BUILD}/openlayers-workshop/gitbook ${BUILD}/openlayers-workshop-${1}/gitbook
+  cd ${BUILD}
+  zip -FSr ../openlayers-workshop-${1}.zip openlayers-workshop-${1}
+}
+
+#
+# Build the archive.
+#
+main() {
+  root=$(cd -P -- "$(dirname -- "${0}")" && pwd -P)
+  cd ${root}
+  assert_clean
+  build_archive ${1}
+}
+
+if test ${#} -ne 1; then
+  display_usage ${0}
+  exit 1
+else
+  main ${1}
+fi

src/LANGS.md → doc/LANGS.md

@@ -2,4 +2,4 @@
 
 * [English](en/)
 * [Français](fr/)
-* [Português](pt/)
+* [Português](pt/)

src/book.json → doc/book.json

@@ -1,7 +1,7 @@
 {
   "gitbook": "^3.2.3",
   "variables": {
-    "workshopUrl": "http://localhost:4000"
+    "workshopUrl": "http://localhost:3000"
   },
   "links": {
     "sidebar": {
@@ -10,11 +10,15 @@
   },
   "plugins": [
     "image-captions",
-    "include"
+    "include",
+    "include-codeblock-patched"
   ],
   "pluginsConfig": {
     "image-captions": {
       "caption": "_CAPTION_"
+    },
+    "include-codeblock": {
+      "unindent": true
     }
   },
   "styles": {

doc/en/README.md

@@ -0,0 +1,29 @@
+# OpenLayers Workshop
+
+Welcome to the **OpenLayers Workshop**. This workshop is designed to give you a comprehensive overview of OpenLayers as a web mapping solution.
+
+## Setup
+
+These instructions assume that you are starting with an `openlayers-workshop-en.zip` archive from the latest [workshop release](https://github.com/openlayers/workshop/releases).  In addition, you'll need [Node](https://nodejs.org/) v6 or higher installed to run a development server for the workshop.
+
+After extracting the zip, change into the `openlayers-workshop-en` directory and install some additional dependencies:
+
+    npm install
+
+Now you're ready to start the workshop development server.  This serves up the [workshop documentation]({{book.workshopUrl}}/doc/) in addition to providing a module bundler for the OpenLayers library.
+
+    npm start
+
+This will start a development server where you can read the workshop documentation and work through the exercises.  You should be able to confirm that things are working by seeing an alert pop up at {{book.workshopUrl}}/.  You can read through the workshop documentation at {{book.workshopUrl}}/doc/.
+
+## Overview
+
+This workshop is presented as a set of modules.  In each module you will perform tasks designed to achieve a specific goal for that module.  Each module builds upon lessons learned in previous modules and is designed to iteratively build up your knowledge base.
+
+The following modules will be covered in this workshop:
+
+* [Basics](basics/README.md) - Learn how to add a map to a webpage.
+* [Vector Data](vector/README.md) - Working with vector data.
+* [Vector Tiles](vectortile/README.md) - Create beautiful maps with vector tiles.
+* [Raster Operations](raster/README.md) - Manipulating pixels with a raster source.
+* [Deploying](deploying/README.md) - Building applications for production.

doc/en/SUMMARY.md

@@ -0,0 +1,25 @@
+# Summary
+
+* [Basics](basics/README.md)
+  * [Creating a map](basics/map.md)
+  * [Zooming to your location](basics/geolocation.md)
+  * [Drawing a point at your location](basics/point-feature.md)
+  * [Showing a popup on feature click](basics/popup.md)
+* [Vector Data](vector/README.md)
+  * [Rendering GeoJSON](vector/geojson.md)
+  * [Drag and drop](vector/drag-n-drop.md)
+  * [Modifying features](vector/modify.md)
+  * [Drawing new features](vector/draw.md)
+  * [Snapping](vector/snap.md)
+  * [Downloading features](vector/download.md)
+  * [Making it look nice](vector/style.md)
+* [Vector Tiles](vectortile/README.md)
+  * [The VectorTile layer](vectortile/map.md)
+  * [Interact with VectorTile features](vectortile/interact.md)
+  * [Styling a VectorTile layer](vectortile/ugly.md)
+  * [Making things look bright](vectortile/bright.md)
+* [Raster Operations](raster/README.md)
+  * [Map setup](raster/map.md)
+  * [Render elevation data](raster/elevation.md)
+  * [Render sea level](raster/raster.md)
+* [Deploying](deploying/README.md)

doc/en/basics/README.md

@@ -0,0 +1,8 @@
+# Basics
+
+Now that we have set up our development environment, let's get started by creating a simple web page with an  OpenLayers map, and add some animation and interactivity to it.
+
+* [Creating a map](map.md)
+* [Zooming to your location](geolocation.md)
+* [Drawing a point at your location](point-feature.md)
+* [Showing a popup on feature click](popup.md)

doc/en/basics/geolocation.md

@@ -0,0 +1,21 @@
+# Zooming to your location
+
+Browsers provide an API to get the current location of the user. We want to use this feature to zoom the map to where the user currently is. To make it easier for the user to see what is going on on the map, we want to animate the zoom.
+
+## Application changes
+
+First of all, we need to assign the map to a constant, so we can access it from other components we're going to add in this exercise:
+
+[import:'map-const'](../../../src/en/examples/basics/geolocation.js)
+
+To add the geolocation functionality, we append a short code block to our `main.js` file:
+
+[import:'geolocation'](../../../src/en/examples/basics/geolocation.js)
+
+This requires a new import for the `proj.fromLonLat()` function, which converts longitude/latitude coordinates into the coordinate system OpenLayers uses by default for the map view (Web Mercator, EPSG:3857).
+
+[import:'import-proj'](../../../src/en/examples/basics/geolocation.js)
+
+### View the result
+
+When we look at the map in the web browser ({{book.workshopUrl}}/), we will probably get asked whether we want to give the page access to our location. After answering 'Yes', an animated zoom should take us to our current location.

doc/en/basics/map.md

@@ -0,0 +1,37 @@
+# Creating a map
+
+In OpenLayers, a map is a collection of layers that get rendered to a web page.  To create a map, you need some markup (HTML) that creates the map viewport (e.g. a `<div>` element), a bit of style to give the map viewport the appropriate dimensions on your page, and map initialization code.
+
+## Working example
+
+Make sure you've completed the [setup instructions](../) to install dependencies and get the development server running.
+
+Now let's create a fully working example of an OpenLayers map. At a minimum, we need some markup with a container element for a map, and an OpenLayers `Map` instance which we configure with a layer and a view.
+
+### The markup
+
+First, we create an `index.html` file in the root of the workshop directory:
+
+[import](../../../src/en/examples/basics/map.html)
+
+Note that we do not need to include any `<script>` for our application. Our webpack setup takes care of that. Our `<style>` makes the map container fill the whole page, and we will use the container `<div>` with the `map-container` id as target for the map.
+
+### The application
+
+To work with OpenLayers, we import the [`ol` package](https://www.npmjs.com/package/ol) from npm. This is done with an `npm install` in our terminal:
+
+    npm install --save ol
+
+Next, as entry point of the application, we create a `main.js` file, and also save it in the root of the workshop directory:
+
+[import](../../../src/en/examples/basics/map.js)
+
+At the top, we import the required modules from the `ol` package. Note the `'ol/ol.css'` import, which adds the styles that OpenLayers requires for its basic UI components. With everything we need imported, we create move on and create a `Map`. The `target` points to the container `<div>` we have in our markup. We configure the map with a tiled image layer (`TileLayer`) and an `XYZSource`. Finally, the `View` defines the initial `center` and `zoom`.
+
+### Viewing the map
+
+Now our application is ready for testing. Let's open the working map in a web browser: {{book.workshopUrl}}/. This is how it should look:
+
+![A map of the world](map.png)
+
+In the final chapter of the workshop, we will learn how create a production build of the application for deployment.

doc/en/basics/point-feature.md

@@ -0,0 +1,33 @@
+# Drawing a point at your location
+
+Now that we have a map centered on our location, we also want to show the exact location by rendering a point at it.
+
+## Adding a vector layer
+
+In addition to displaying maps from tiles provided by a tile service, OpenLayers can render vector data. A vector layer has a source which contains features. In this simple example, we just add a single feature with a point geometry that represents our location.
+
+A few more imports are required:
+
+[import:'import-vector'](../../../src/en/examples/basics/point-feature.js)
+
+The vector layer itself is created with the following code, which we place between the `const map` and `navigator.geolocation` blocks in our `main.js` file:
+
+[import:'point-layer'](../../../src/en/examples/basics/point-feature.js)
+
+We now can create a point feature and add it to the vector layer as soon as we know our location. This is done with a single line at the end of the `geolocation`'s' `getCurrentPosition` callback:
+
+[import:'add-point'](../../../src/en/examples/basics/point-feature.js)
+
+## Styling the point
+
+To make the point of our location easier to see on the map, we can give the vector layer some style. This requires more imports to be added at the top of our `main.js`.
+
+[import:'import-style'](../../../src/en/examples/basics/point-feature.js)
+
+The code for adding the style can be added after the `VectorLayer` definition:
+
+[import:'style'](../../../src/en/examples/basics/point-feature.js)
+
+When done, the result should look like this:
+
+![User location with a marker](point-feature.png)

doc/en/basics/popup.md

@@ -0,0 +1,39 @@
+# Showing a popup on feature click
+
+OpenLayers can anchor markup to a position on the map. This can be used to display a popup at a user clicked location. In this case, we just want to show the latitude and longitude of the current user location in a nice little popup.
+
+## CSS and markup for the popup
+
+For nice styling of the popup, we can go to http://www.cssarrowplease.com/ and design a container for our popup. I changed the arrow size to 10 and played a bit with the colors. The resulting css is simply copied to the `<style>` section of our index.html:
+
+[import:'css'](../../../src/en/examples/basics/popup.html)
+
+To make the popup look nicer, we give the `.arrow-box` some padding and rounded corners:
+
+[import:'nicer-css'](../../../src/en/examples/basics/popup.html)
+
+In addition to the css, we also need to add the markup for the container the body of our `index.html`:
+
+[import:'markup'](../../../src/en/examples/basics/popup.html)
+
+## Application code for interacting with the map
+
+The `Overlay` module is responsible for anchoring markup to a position on the map, and the `coordinate` module provides a function to format a position in degrees, minutes and seconds. Let's import these two modules:
+
+[import:'import-popup'](../../../src/en/examples/basics/popup.js)
+
+To create the overlay and connect it to the popup, we append the following code to our `main.js`:
+
+[import:'overlay'](../../../src/en/examples/basics/popup.js)
+
+Note the `offset` we configured for the `Overlay`. The y offset (`-10`) has to compensate for the arrow size we provided on http://www.cssarrowplease.com/.
+
+The last step is to append another code snippet to `main.js`, where we listen for user clicks on the map and handle them by showing the popup at the position of the clicked vector feature:
+
+[import:'listen'](../../../src/en/examples/basics/popup.js)
+
+The `on()` function is used to register a listener for clicks, and `Map#getFeaturesAtPixel()` returns the features at the pixel position, where pixels are relative to the map viewport. That `pixel` is provided by the event object (`e`) we get as argument for the listener function.
+
+Now look at the working map in the web browser: {{book.workshopUrl}}/. Once you are zoomed to the current location and see the circle marker, click on it to get the popup. When you click somewhere else on the map, the popup will disappear again.
+
+![A map with a popup at our location](popup.png)

doc/en/deploying/README.md

@@ -0,0 +1,17 @@
+# Deploying
+
+Throughout the workshop, we've been using a development server to view the examples.  This is similar to the setup you would use when developing an application with the [`ol` package](https://www.npmjs.com/package/ol).  When you're ready to deploy your application, you'll want to create a minified bundle of your application entry point with a build step.
+
+We've been using [webpack](https://webpack.js.org/) for module bundling during development.  The `webpack.config.js` at the root of the workshop directory includes webpack configuration profiles for `dev` and `prod` environments.  When we started the development server with `npm start`, we were using the `dev` profile.  The `prod` profile adds two webpack plugins: the [`EnvironmentPlugin`](https://webpack.js.org/plugins/environment-plugin/) and the [`BabiliPlugin`](https://github.com/webpack-contrib/babel-minify-webpack-plugin).  This provides a good starting point for your `prod` build profile.  Explore the other [webpack plugins](https://webpack.js.org/plugins/) to see what else you might want to bring in.
+
+To build assets for deployment, we run our `build` script from `package.json`:
+
+    npm run build
+
+This runs `webpack --env=prod`, but doesn't require that `webpack` is on our path.
+
+After the build finishes, you'll have artifacts in the `build` directory.  These are the assets that you would deploy to your production server (or S3, or wherever you want to host your application).  You can see what the app looks like by opening the `index.html` file in your browser.
+
+    open build/index.html
+
+That's it.  You're done!