Add tutorials #774

matthewma7 · 2018-02-08T15:44:24Z

Add a few tutorials and apply some style updates.

This is a WIP, but feel free to comment.

The style change on the website:

manthey · 2018-02-12T14:52:10Z

tutorials/vector_point/index.pug

+block mainTutorial
+  :markdown-it
+    # Tutorial - Vector point
+    First, let's create our map and add a base map. Also, to make simple, we import our data inline.


I would change to make simple to to keep it simple.

manthey · 2018-02-12T15:18:01Z

tutorials/vector_point/index.pug

+  :markdown-it
+    Then create point feature and set the data.
+
+  +codeblock('javascript', 3).


I recommend making the default step that runs be this one, since it shows points on the map (and therefore will be better for the thumbnail showing off the tutorial).

manthey · 2018-02-12T15:18:59Z

tutorials/vector_point/index.pug

+
+block mainTutorial
+  :markdown-it
+    # Tutorial - Vector point


This tutorial is called Vector Point, but it is just showing points (not vectors), so I think it should be renamed.

Oh, yes that's right. (I was thinking this is not WMS layer, but now I see you mean a point is not a vector). So, do you think the name Geography Point?

I think Geospatial Point or Geographic Point.

Or just simple point. I'make it simple point for now.

manthey · 2018-02-12T15:21:47Z

tutorials/vector_point/index.pug

+    var feature = layer.createFeature('point')
+      .data(cities.features)
+      .position(function (city) {
+          return { x: city['geometry']['coordinates'][0], y: city['geometry']['coordinates'][1] };


I'd recommend, in general, using shorter lines in the tutorial so that there is less chance the user has to scroll to see the whole line. So this return could be rewritten as

return { x: city['geometry']['coordinates'][0], y: city['geometry']['coordinates'][1] };

manthey · 2018-02-12T15:28:13Z

tutorials/contour/index.pug

+
+  :markdown-it
+    Then load some data. 
+    The data is grid data describing geospatial point elevation, a record of z value -9999 means it's sea level. 


Pedantically, the value of -9999 means that there is no land data (rather than that it is sea level).

manthey · 2018-02-12T15:32:59Z

tutorials/contour/index.pug

+    }));
+
+  :markdown-it
+    Once the data is loaded. We create the contour feature with default color range. *min: 0* means only showing data with elevation.


You can surround examples that are in the code with backticks (rather than using an asterisk to italicize it). With the change the background color for the tutorials, we may want to add code: { background: <some contrasting color>; } to the tutorial css.

manthey · 2018-02-12T15:34:16Z

tutorials/contour/index.pug

+          colorRange: ['rgb(224,130,20)', 'rgb(253,184,99)', 'rgb(254,224,182)', 'rgb(216,218,235)', 'rgb(178,171,210)', 'rgb(128,115,172)', 'rgb(84,39,136)']
+        })
+        .draw();
+    });


Can you also show using stepped: false?

manthey · 2018-02-12T15:46:41Z

Eventually, I'd like to see some of the tests added to these (it can wait for a future PR). For the contour test, this will probably require PR #775 to be merged to pass on Chrome headless.

manthey · 2018-02-12T16:04:16Z

tutorials/vector_point/index.pug

+  :markdown-it
+    We can also use GeoJSON reader to create the point feature.
+
+  +codeblock('javascript', 10, 3, false, 'Step 3-B').


I think you want the parent step to be step 2.

manthey · 2018-02-12T16:07:42Z

If we wanted to make the point (and the choropleth) tutorial simpler, we could have the data be in a simpler form that GeoJSON (possibly we GeoJSON as an alternative).

For instance, step 1 could define cities as:

var cities = [
  {x: -74.0059413, y: 40.7127837, name: "New York", population: 8405837},
  {x: -118.2436849, y: 34.0522342, name: "Los Angeles", population: 3884307},
  {x: -87.6297982, y: 41.8781136, name: "Chicago", population: 2718782},
  {x: -95.3698028, y: 29.7604267, name: "Houston", population: 2195914},
  {x: -75.1652215, y: 39.9525839, name: "Philadelphia", population: 1553165},
  {x: -112.0740373, y: 33.4483771, name: "Phoenix", population: 1513367}
];

Then step 3 becomes just:

var feature = layer.createFeature('point')
  .data(cities)
  .draw();

And step 3-B would redefine cities (or use a new variable name of geojsonCities or similar) as the original geojson given in the current Step 1, with the description changed "We can also use GeoJSON and the GeoJSON reader to create the point feature."

manthey · 2018-02-12T16:14:36Z

tutorials/choropleth/index.pug

+    Now we style polygon with color.
+
+  +codeblock('javascript', 3, 2, false).
+    var polulations = (states.features.map(function (state) { return state.properties.population }));


polulations -> populations

matthewma7 · 2018-02-12T16:17:57Z

I was thinking GeoJSON is mentally simple to accept. I kinda don't want to depend on default behavior too much because it might give the user an impression that the input data has to be formatted in a certain way, and you can only use geojson with the json reader.

manthey · 2018-02-12T16:35:15Z

I agree that I don't want people thinking we only accept one format, which is why I think we need to show it is something besides (and simpler than) GeoJSON. We also want to show that it is easy to handle GeoJSON, since it is the common format.

Instead of using x and y, use lon and lat and then use a position function.

Or, we ultimately (not now) want another tutorial showing the flexibility of formats using various positions and styles.

manthey · 2018-02-12T16:36:35Z

tutorials/common/index-website.pug

-      button.codeblock_run Run
-      button.codeblock_reset Reset
+      button.codeblock_run.btn.btn-primary.btn-sm Run
+      button.codeblock_reset.btn.btn-link.btn-sm Reset


We should add these classes to the tutorials/common/index.pug file as well, since I generate thumbnails from that and it will then look the same).

Oh, when you generate, is it the exact same page as local tutorials? If so, I think I'll need to update the overwritten bootstrap styles to match the website first.

I use xvfb and Chrome with the local tutorials to generate the thumbnails (that way it doesn't have the framing elements as part of the tutorial). To my eye, the button style change is the only significant difference, so it would be sufficient.

I should say, I don't think the font difference is that significant for the thumbnails.

manthey · 2018-02-12T16:55:30Z

tutorials/choropleth/tutorial.json

+  "tutorialCss": [],
+  "tutorialJs": [],
+  "about": {
+    "text": "Create a choropleth map"


This is the text shown when hovering over a tutorial, so I'd like it to be a bit more verbose. Perhaps Create a choropleth map, set the colors used, and add a legend.

manthey · 2018-02-12T16:57:00Z

tutorials/contour/index.pug

+
+block mainTutorial
+  :markdown-it
+    # Tutorial - Contour map


It looks like I've mostly capitalized things in other tutorial titles, so can this be Contour Map. Also change in the tutorial.json file and do similarly for the Simple Point tutorial as well.

manthey · 2018-02-12T16:57:39Z

tutorials/contour/tutorial.json

+  "tutorialCss": [],
+  "tutorialJs": [],
+  "about": {
+    "text": "Add a contour map"


A better description might be: Plot grid data as a color contour.

manthey · 2018-02-12T17:23:59Z

tutorials/simple_point/index.pug

      .position(function (city) {
        return {
-          x: city['geometry']['coordinates'][0],
-          y: city['geometry']['coordinates'][1]
+          x: city['lon'],


city.lon and city.lat would work, too.

manthey · 2018-02-12T17:25:04Z

Elsewhere in the css for the local version we expect the navbar to have a height of 60px. Removing flatly breaks that assumption, which would require changing several more things. For now, I would revert this removal.

I don't include the navbar as part of the thumbnails, so that won't be affected.

…tion; Rename one tutorial;

matthewma7 force-pushed the add_tutorials branch 3 times, most recently from 398e8b7 to 9f1ebc9 Compare February 9, 2018 20:50

matthewma7 changed the title ~~[WIP] Add tutorials~~ Add tutorials Feb 9, 2018