├── LICENSE ├── README.md ├── carto_datasets.png ├── carto_table_setup.png ├── commit.png ├── css └── style.css ├── index.html ├── insert_function.sql └── screenshot.png /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Raphael Dumas and Mike Foster 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Crowdmap: Basic 2 | This is an attempt to create the most basic example of a web map for crowdsourcing... anything that users can draw on a map (points, squares, circles, lines, polygons...). 3 | It uses [Leaflet.draw](https://github.com/Leaflet/Leaflet.draw) ([demo](https://leaflet.github.io/Leaflet.draw/)), an extension of the [Leaflet](http://leafletjs.com/reference.html) javascript mapping library to enable users to draw shapes on a map and then inserts them in a [Carto table](https://carto.com/data-observatory/). The webmap is hosted on [gh-pages](https://pages.github.com/), which allows you to host free static websites on github, the codesharing website that you're reading this on currently. The only permitted behaviour is for users to view previously submitted input and to submit their own input. Editing or deleting input is not permitted. Examples of possible implementations include: 4 | - [Mapping neighbourhood boundaries](http://bostonography.com/hoods) ([code](https://github.com/mjfoster83/neighborhoods)) 5 | - [Collecting data on traffic safety issues](http://app01.cityofboston.gov/VZSafety/#_=_) 6 | - [Soliciting input on routes and points for better biking infrastructure](http://boston-cyclists-union.github.io/bikeways4everybody) (based on this workshop, [code here](https://github.com/radumas/bikeways4everybody)) 7 | 8 | [![Example Screenshot](screenshot.png)](http://radumas.github.io/crowdmap-basic) 9 | [Try it here](http://radumas.github.io/crowdmap-basic) 10 | 11 | # Table of Contents 12 | ### 1. [Set up guide](#guide) 13 | #### - [Set Up Accounts and Fork Repository](#set-up-accounts-and-fork-repository) 14 | 15 | ### 2. [Now what?](#now-what) 16 | ### 3. [How it works](#how-it-works) 17 | 18 | 19 | # Guide 20 | ## Set Up Accounts and Fork Repository 21 | 22 | 1. Get a [github](https://github.com/join) and a [carto](https://carto.com/signup) account. 23 | + (*Optional*) Mac & Windows users can install the [Github Desktop Software](https://desktop.github.com/) 24 | 2. Fork the repository by clicking on the [fork icon](#js-flash-container) at the top right of this page, like the image below. To learn more about forking, click [here](https://help.github.com/articles/fork-a-repo/). 25 | [![](https://help.github.com/assets/images/help/repository/fork_button.jpg)](#js-flash-container) 26 | 27 | ## After Forking this Repository 28 | 29 | ### Set up a Carto Database 30 | 31 | 1. Create a new Carto dataset. Find datasets by navigating to the top left, click on `Maps` and then `Your Datasets`. On that page click the `NEW DATASET` button on the right and then click `CREATE EMPTY DATASET` on the right. 32 | ![](carto_datasets.png) 33 | 34 | 2. The default dataset comes with the following fields: `{cartodb_id, the_geom, description, name}` 35 | Each row represents one submission from the map with the first field a unique id assigned by Carto to each geometry. `the_geom` is the geographic object. `description` is the user input description of the shape, and `name` is the user's name. **Click** on `untitled_table` to give your table a unique name. Remember this name, though the rest of this tutorial uses `crowdmap_basic` as the tablename. 36 | ![](carto_table_setup.png) 37 | 3. In the bottom left corner, slide the circle from `METADATA` to `SQL` to enable writing arbitrary SQL. SQL stands for Structured Query Language and it's a standardized programming language for databases that comes in a number of flavours for different database engines (Oracle, Microsoft SQL Server). Carto uses PostgreSQL under the hood. 38 | 39 | 4. Copy and paste the contents of `insert_function.sql` ([located here](insert_function.sql)) into the SQL pane (it has `SELECT * FROM untitled_table` in the image :point_up:), and then modify the name of the table to be inserted (if you changed the table name) in step 2 of this section: 40 | ``` 41 | _the_table TEXT := 'crowdmap_basic'; 42 | ``` 43 | This function allows you to send data from the map to the Carto using a publicly accessible URL while limiting what functions the public can perform on the data (for example, the public can't modify or delete existing data). This function takes the drawn shape as a GeoJSON, the description, and the username. It converts the GeoJSON to a PostGIS geometry object and then inserts a new row in the table with the geometry, and the other two user-input values. Since it isn't easy to view saved functions in Carto, I recommend saving the function in a text file. 44 | **If you have multiple tables** (because you're creating multiple maps, or you're teaching this workshop multiple times) see below for more information on keeping track of multiple files. Else go down to [**Edit HTML**](#edit-html) 45 | 46 | **Multiple tables:** you need to create a unique function for each, it's probably a good idea to save each function as a separate file so you can recall what is on your Carto account. Alternatively you can see which functions have been created with the following `sql` query ([source](http://stackoverflow.com/a/1559039/4047679)): 47 | ```sql 48 | SELECT proname, proargnames, prosrc 49 | FROM pg_catalog.pg_namespace n 50 | JOIN pg_catalog.pg_proc p 51 | ON p.pronamespace = n.oid 52 | WHERE n.nspname = 'public' 53 | AND p.proowner <> 10 54 | ``` 55 | ### Edit HTML 56 | You can download the contents of this repository as a folder (called [cloning](https://help.github.com/articles/cloning-a-repository/)) so you can modify and test it on your personal machine rather than displaying it on the web. If you're interested in that I'd recommend starting by downloading [GitHub Desktop](https://desktop.github.com/). 57 | 58 | However, the goal of this tutorial is to entirely use web tools, so we'll modify things in your browser. `index.html` is the lobby for the webpage for this project. This is a combination of html, CSS, and JavaScript code that tells your browser how to render the map prettily and where to send your data. 59 | 60 | 1. You can edit this file directly in your web-browser by clicking on the [`index.html`](index.html) filename above :point_up: and then clicking on the :pencil: icon in the top right. Modify the following variables in `index.html` (search for "TODO"): 61 | - `cartoDBusername` to your Carto username 62 | - `cartoDBinsertfunction` to the name of your insert function (if you changed it) 63 | - `cartoDBtablename` to the name of your table in Carto (if you changed it) 64 | 2. Commit your changes! A "Commit" is equivalent to saving a document in Version Control, but instead it saves the difference to the document, so you can see it's entire history on GitHub as well as useful notes for yourself or collaborators on what you actions you took in your commit. You commit by navigating to the bottom of the page :point_down: where you were editing where you'll see the below box. You can leave the empty defaults but it's good practice to write meaningful messages. 65 | ![](commit.png) 66 | 3. After your modifications are committed, GitHub will build and publish your project on the web. Go to http://YOURGITHUBUSERNAME.github.io/crowdmap-basic to see your own map, and start submitting data, you can see the submitted data by going to the data view for that table in your Carto account. 67 | 4. :tada: Give yourself a pat on the back! This may be the end of the workshop, but this is just the beginning. 68 | 5. Modify the code to your whims ([now what?](#now-what)). 69 | 70 | # Now What? 71 | What to do and modify on your map once it's working. Have a look at the different parameters in the `config` variable in [`index.html`](index.html) to get a sense of what you can modify: 72 | - **Where the map is focused** on with the `mapcenter` parameter 73 | - **The shapes that can be drawn** (line, marker, etc...) under the `drawOptions` parameters. See more Leaflet.Draw options [here](https://github.com/Leaflet/Leaflet.draw#options) 74 | + You can also enable editing and deleting of shapes, however this will require additional configuration of the function that communicates with the Carto database, see [this Carto tutorial](https://carto.com/blog/read-and-write-to-cartodb-with-the-leaflet-draw-plugin/) for more details. (**Note**: that Carto example may be vulnerable to SQL Injection, see [here](https://dba.stackexchange.com/questions/49699/sql-injection-in-postgres-functions-vs-prepared-queries)) 75 | - **The base map** (background) by modifying `var CartoDB_Positron = L.tileLayer(...)`, you can test a number [here](https://leaflet-extras.github.io/leaflet-providers/preview/) 76 | - **The map style** (e.g. height, width, font) by modifying [`css/style.css`](css/style.css). See [this](http://flexboxfroggy.com/) quirky frog-based tutorial as an introduction to [Cascading Style Sheets](http://stackoverflow.com/a/9289668/4047679) 77 | - **[Advanced] what fields are collected.** This requires the modification of: 78 | + The table in Carto 79 | + The [`insert_function`](insert_function.sql) (and then re-executing this in Carto) 80 | + The field(s) used after `
` in `index.html` 81 | + The `setData()` function in `index.html` 82 | 83 | Once you've collected data from users, have a look at the [tutorials at Carto](https://carto.com/docs/tutorials/) for what kinds of maps you can make from your data. 84 | 85 | # How it works 86 | ## Sending Leaflet.draw data to Carto 87 | 88 | This section details the modifications made from the [excellent tutorial](http://duspviz.mit.edu/web-map-workshop/cartodb-data-collection/#) by Mike Foster ([@mjfoster83](https://github.com/mjfoster83/web-map-workshop)). If this is your first introduction to leaflet, you should probably go through the entire webmapping workshop 89 | 90 | 2. Modify the `setData()` function to construct the SQL query which calls the function to insert the data to Carto. 91 | ```javascript 92 | //Convert the drawing to a GeoJSON to pass to the Carto sql database 93 | var drawing = "'"+JSON.stringify(layer.toGeoJSON().geometry)+"'"; 94 | 95 | //Construct the SQL query to insert data from the three parameters: the drawing, 96 | //the input username, and the input description of the drawn shape 97 | var sql = "SELECT insert_crowd_mapping_data("; 98 | sql += drawing; 99 | sql += ","+enteredDescription; 100 | sql += ","+enteredUsername; 101 | sql += ");"; 102 | ``` 103 | 3. And then add the sql query to an AJAX call in order to pass the data to your Carto table 104 | ```javascript 105 | //TODO: Change to your username 106 | var cartoDBusername = "raphaeld" 107 | //Sending the data 108 | $.ajax({ 109 | type: 'POST', 110 | url: 'https://'+cartousername+'.cartodb.com/api/v2/sql', 111 | crossDomain: true, 112 | data: {"q":sql}, 113 | dataType: 'json', 114 | success: function(responseData, textStatus, jqXHR) { 115 | console.log("Data saved"); 116 | 117 | }, 118 | error: function (responseData, textStatus, errorThrown) { 119 | 120 | console.log("Problem saving the data"); 121 | } 122 | }); 123 | ``` 124 | 4. After each new drawing is inserted, the data from the `drawnItems` layer is passed to the `cartoData` layer without re-querying the database. This does mean that a user **won't** see others' edits to the map after load. See Mike Foster's [tutorial](http://duspviz.mit.edu/web-map-workshop/cartodb-data-collection/#) for the easy fix to reload the data from Carto after every draw. 125 | ```javascript 126 | // Transfer drawing to the Carto layer 127 | var newData = layer.toGeoJSON(); 128 | newData.properties.description = description.value; 129 | newData.properties.name = username.value; 130 | 131 | cartoDBData.addData(newData); 132 | ``` 133 | -------------------------------------------------------------------------------- /carto_datasets.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/radumas/crowdmap-basic/a18ee1fcca0e3cc6029160eb4a27c49df6b9db27/carto_datasets.png -------------------------------------------------------------------------------- /carto_table_setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/radumas/crowdmap-basic/a18ee1fcca0e3cc6029160eb4a27c49df6b9db27/carto_table_setup.png -------------------------------------------------------------------------------- /commit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/radumas/crowdmap-basic/a18ee1fcca0e3cc6029160eb4a27c49df6b9db27/commit.png -------------------------------------------------------------------------------- /css/style.css: -------------------------------------------------------------------------------- 1 | @import url(//fonts.googleapis.com/css?family=Open+Sans); 2 | 3 | body { 4 | margin: 0px; 5 | font-family: 'Open Sans', Helvetica, sans-serif; 6 | } 7 | 8 | img { 9 | float: left; 10 | padding-right: 10px; 11 | } 12 | 13 | p { 14 | font-size: 15px; 15 | line-height: 25px; 16 | } 17 | 18 | h1 { 19 | line-height: 60px; 20 | margin-top: 0px; 21 | margin-bottom: 0px; 22 | font-weight: lighter; 23 | } 24 | 25 | #wrapper { 26 | width: 750px; 27 | } 28 | 29 | #map { 30 | width: 750px; 31 | margin: 0 auto; 32 | height: 375px; 33 | } 34 | 35 | #controls { 36 | width: 100%; 37 | margin: 0 auto; 38 | float: left; 39 | } 40 | 41 | #form { 42 | margin-top: 5px; 43 | font-size: 12px; 44 | text-align: left; 45 | line-height: 16px; 46 | width:375px; 47 | float: left; 48 | } 49 | 50 | #header { 51 | margin-top: 0px; 52 | margin-bottom: 0px; 53 | } 54 | 55 | #credits p { 56 | margin-top: 5px; 57 | font-size: 12px; 58 | text-align: right; 59 | line-height: 16px; 60 | } 61 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Leaflet to Carto - Point Collection Tool Beta 6 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 18 |
19 |
20 |

Click points for more information, or add your own.

21 | 22 |
23 |

©2015, Mike Foster and Raphael Dumas

24 |
25 |
26 | 27 |
28 |
29 |
30 |
    31 |
    • 32 |
    • 33 |
    • 34 |
    • 35 |
36 | 37 |
38 |
39 |
40 | 41 | 44 | 45 | 46 | 47 | 48 | 227 | 228 | 229 | 230 | -------------------------------------------------------------------------------- /insert_function.sql: -------------------------------------------------------------------------------- 1 | DROP FUNCTION IF EXISTS insert_crowd_mapping_data(text,text,text); 2 | --Assumes only one value being inserted 3 | 4 | CREATE OR REPLACE FUNCTION insert_crowd_mapping_data ( 5 | _geojson TEXT, 6 | _description TEXT, 7 | _name TEXT) 8 | --Has to return something in order to be used in a "SELECT" statement 9 | RETURNS integer 10 | AS $$ 11 | DECLARE 12 | _the_geom GEOMETRY; 13 | --The name of your table in cartoDB 14 | _the_table TEXT := 'crowdmap_basic'; 15 | BEGIN 16 | --Convert the GeoJSON to a geometry type for insertion. 17 | _the_geom := ST_SetSRID(ST_GeomFromGeoJSON(_geojson),4326); 18 | 19 | 20 | --Executes the insert given the supplied geometry, description, and username, while protecting against SQL injection. 21 | EXECUTE ' INSERT INTO '||quote_ident(_the_table)||' (the_geom, description, name) 22 | VALUES ($1, $2, $3) 23 | ' USING _the_geom, _description, _name; 24 | 25 | RETURN 1; 26 | END; 27 | $$ 28 | LANGUAGE plpgsql SECURITY DEFINER ; 29 | 30 | --Grant access to the public user 31 | GRANT EXECUTE ON FUNCTION insert_crowd_mapping_data( text, text, text) TO publicuser; -------------------------------------------------------------------------------- /screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/radumas/crowdmap-basic/a18ee1fcca0e3cc6029160eb4a27c49df6b9db27/screenshot.png --------------------------------------------------------------------------------