From b550669b26bbef85a9c94506fd8c3857ae54da35 Mon Sep 17 00:00:00 2001 From: Joe Hawes Date: Sat, 2 Dec 2023 00:30:39 -0800 Subject: [PATCH] docs: expanded guide pages and other small improvements (#123) * docs: expanded guide pages and other tweaks This PR includes the following documentation improvements. Getting Started: - Added full HTML example for the Script Tag section - Updated TD unpkg references to latest version (terra-draw@0.0.1-alpha.50) - Updated ML unpkg references to latest version (maplibre-gl@3.6.2/) Common Patterns: - Rewording and formatting of Changing Mode section Development: - Improve setup instructions - Added example .env.example file, updated .gitignore to include Lots of other minor tweaks and re-formatting :) * version number tweak --------- Co-authored-by: Joe Hawes <> --- .gitignore | 4 +- development/.env.example | 2 + development/README.md | 20 ++++- guides/COMMON_PATTERNS.md | 35 ++++---- guides/DEVELOPMENT.md | 8 +- guides/GETTING_STARTED.md | 168 ++++++++++++++++++++++++-------------- 6 files changed, 154 insertions(+), 83 deletions(-) create mode 100644 development/.env.example diff --git a/.gitignore b/.gitignore index addee736..efe8b787 100644 --- a/.gitignore +++ b/.gitignore @@ -5,9 +5,9 @@ dist/ node_modules/ example/dist/ example/node_modules/ -example/.env ROADMAP.md data/ scratch/ .idea -.env \ No newline at end of file +.env* +!.env.example \ No newline at end of file diff --git a/development/.env.example b/development/.env.example new file mode 100644 index 00000000..11112b0f --- /dev/null +++ b/development/.env.example @@ -0,0 +1,2 @@ +GOOGLE_API_KEY=YOUR_KEY_HERE +MAPBOX_ACCESS_TOKEN=YOUR_KEY_HERE \ No newline at end of file diff --git a/development/README.md b/development/README.md index a1fd41a7..9bc5ef0d 100644 --- a/development/README.md +++ b/development/README.md @@ -1,10 +1,22 @@ -# Terra Draw Local Example +# Local Development Example This example shows how to use Terra Draw with a variety of providers (currently Leaflet, Mapbox GL, Google Maps) +# Installation + + +If you haven't already, you will need to install the dependencies for the root of the project, as well as the dependencies for the `development/` directory: + + +```shell +npm install +cd development/ +npm install +``` + # Running Locally -Create a `.env` file with the following variables: +Create a `.env` file (or rename the included `.env.example`) in the `development/` directory with the following variables: ``` GOOGLE_API_KEY=YOUR_KEY_HERE @@ -13,6 +25,8 @@ MAPBOX_ACCESS_TOKEN=YOUR_ACCESS_TOKEN_HERE You can then create a watching build that allows you to test out both changes in the example but also the Terra Draw source itself, like so: -`npm run serve` +```shell +npm run serve +``` This will start a hot reloading development server on port 9000 that you can explore via [http://localhost:9000](http://localhost:9000). \ No newline at end of file diff --git a/guides/COMMON_PATTERNS.md b/guides/COMMON_PATTERNS.md index df688608..8536dbb9 100644 --- a/guides/COMMON_PATTERNS.md +++ b/guides/COMMON_PATTERNS.md @@ -2,19 +2,7 @@ ### Changing Mode -To change mode we need to set the current mode to match the name of the mode we want. You can see the name of the mode -in each modes 'mode' property in the modes source file. For convenience here are the built in mode names listed out: - -- TerraDrawStaticMode - 'static' -- TerraDrawPolygonMode - 'polygon' -- TerraDrawPointMode - 'point' -- TerraDrawCircleMode - 'circle' -- TerraDrawLineStringMode - 'linestring' -- TerraDrawSelectMode - 'select' -- TerraDrawLineStringMode - 'freehand' -- TerraDraqwGreatCircleMode - 'greatcircle' - -We can then create these modes and change to them like so: +Modes are added to Terra Draw when you instantiate it through the `modes` property like so: ```typescript const draw = new TerraDraw({ @@ -30,7 +18,11 @@ const draw = new TerraDraw({ }); draw.start(); +``` +Once you have created a Terra Draw instance you can change mode by calling the `setMode` method and providing the mode name: + +```typescript // Change to our TerraDrawPolygonMode instance draw.setMode("polygon"); @@ -38,6 +30,21 @@ draw.setMode("polygon"); draw.setMode("arbitary"); ``` +The `mode` property represents the mode name and can be found in each modes source file. The available mode names are: + +| Class | Mode Name | +|---------------------------|-----------------| +| TerraDrawCircleMode | 'circle' | +| TerraDrawLineStringMode | 'freehand' | +| TerraDraqwGreatCircleMode | 'greatcircle' | +| TerraDrawLineStringMode | 'linestring' | +| TerraDrawPointMode | 'point' | +| TerraDrawPolygonMode | 'polygon' | +| TerraDrawRectangleMode | 'rectangle' | +| TerraDrawSelectMode | 'select' | +| TerraDrawStaticMode | 'static' | + + ### Loading in External Data It is common pattern to want to load in data from an external source (GeoJSON file, API call, etc). This can be achieved @@ -245,4 +252,4 @@ draw.on('deselect', () => { // Do something //... }) -``` \ No newline at end of file +``` diff --git a/guides/DEVELOPMENT.md b/guides/DEVELOPMENT.md index 2731cb69..9aea688c 100644 --- a/guides/DEVELOPMENT.md +++ b/guides/DEVELOPMENT.md @@ -18,7 +18,7 @@ A few things you will need to have installed in order to develop on this project - `dist` - the bundled distributed files of the project - `docs` - the demo app that is published to GitHub pages - `development` - the local development app that is used for developing locally (see below) -- `common` - code that is used across `development` and `docs` folder` +- `common` - code that is used across `development` and `docs` folder ### Technologies Used @@ -43,19 +43,19 @@ Terra Draw uses [jest](https://jestjs.io/) as it's testing framework. You can di To run the tests as they would run in CI: -``` +```shell npm run test ``` You can also check the coverage by running: -``` +```shell npm run test:coverage ``` For local development you may benefit from the `nocheck` option which allows you to avoid running TypeScript type checking when running the tests. This option also only checks files which are explicitly tested (i.e. have a spec file.) -``` +```shell npm run test:nocheck npm run test:nocheck:coverage ``` diff --git a/guides/GETTING_STARTED.md b/guides/GETTING_STARTED.md index 3c494c21..632dde68 100644 --- a/guides/GETTING_STARTED.md +++ b/guides/GETTING_STARTED.md @@ -1,8 +1,8 @@ # Getting Started -## Install +## Installation -We start with the assumption that you have [Node.js](https://nodejs.org/en) installed and [npm](https://www.npmjs.com/) (node package manager). +We start with the assumption that you have both [Node.js](https://nodejs.org/en) and [npm](https://www.npmjs.com/) (node package manager) installed. You can install the Terra Draw into your project like so: @@ -10,10 +10,10 @@ You can install the Terra Draw into your project like so: npm install terra-draw ``` -Be aware Terra Draw is currently in alpha, the initial API is still being finalised. It is strongly advised to pin your installation to a specific version i.e. not using carat, asterix or tilde for versions but giving a version explicitly in your `package.json` +Be aware Terra Draw is currently in alpha, the initial API is still being finalised. It is strongly advised to pin your installation to a specific version i.e. not using carat, asterix or tilde for versions but giving a version explicitly in your `package.json`. ``` - "terra-draw": "0.0.1-alpha.47" +"terra-draw": "0.0.1-alpha.50" ``` Once terra-draw is out of alpha this suggestion will be removed as we will aim to move to semantic versioning. @@ -23,23 +23,69 @@ Once terra-draw is out of alpha this suggestion will be removed as we will aim t Some people may want to experiment with using Terra Draw without a build step. To do this you can use the UMD bundle that is put onto npm via a CDN like unpkg. For example if we were using Terra Draw with MapLibre we might do something like this in our `` tag: ```html - - - + + + ``` Later on in our JavaScript code we can access the global `terraDraw` like so: ```javascript - const td = new terraDraw.TerraDraw({ - adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map }), - modes: [new terraDraw.TerraDrawRectangleMode()] - }); +const draw = new terraDraw.TerraDraw({ + adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map }), + modes: [new terraDraw.TerraDrawRectangleMode()], +}); +``` + +Putting this together we can create a simple map with rectangle drawing like so: + +```html + + + + + + + + + + +
+ + + + ``` ## API Docs -You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api) +You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api). ## Common Patterns @@ -51,7 +97,9 @@ Terra Draw can be used with a set of different adapters to allow you to use it w ### Leaflet -Here is some simple starter code for using Terra Draw with the popular open source mapping library Leaflet. It assumes you are going instantiate your map in a div with and id of `map`, which is assumed to exist within your HTML. +Here is some simple starter code for using Terra Draw with the popular open source mapping library [Leaflet](https://leafletjs.com/). + +We are instructing Leaflet to display within an element with the id of `map` (i.e. `
`), which must exist within your HTML. ```typescript // Import the leaflet mapping library @@ -120,7 +168,7 @@ const draw = new TerraDraw({ allowSelfIntersections: false, pointerDistance: 30, }), - ] + ], }); // Start drawing @@ -197,7 +245,7 @@ loader.load().then((google) => { allowSelfIntersections: false, pointerDistance: 30, }), - ] + ], }); // Start drawing @@ -223,44 +271,45 @@ Here is some starter code for using Terra Draw with the MapLibreGL JS. It assume ```typescript // Import the MapLibre mapping library -import MapLibreGL from 'maplibre-gl' -import 'maplibre-gl/dist/maplibre-gl.css' +import MapLibreGL from "maplibre-gl"; +import "maplibre-gl/dist/maplibre-gl.css"; // Import Terra Draw, we will import the MapLibre adapter, select mode and polygon mode import { TerraDraw, TerraDrawMapLibreGLAdapter, TerraDrawSelectMode, - TerraDrawPolygonMode -} from 'terra-draw' + TerraDrawPolygonMode, +} from "terra-draw"; // Initialize a new MapLibre map, providing the id of the div to display the map // Set the initial center (longitude, latitude) and the zoom level const mapLibreMap = new MapLibreGL.Map({ - container: 'map', + container: "map", style: { version: 8, sources: { - 'osm-tiles': { - type: 'raster', - tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'], + "osm-tiles": { + type: "raster", + tiles: ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"], tileSize: 256, - attribution: '© OpenStreetMap' - } + attribution: + '© OpenStreetMap', + }, }, layers: [ - { - id: 'osm-tiles', - type: 'raster', - source: 'osm-tiles' - } - ] + { + id: "osm-tiles", + type: "raster", + source: "osm-tiles", + }, + ], }, center: [lng, lat], zoom: 4, minZoom: 3, - maxZoom: 20 -}) + maxZoom: 20, +}); // Instantiate the TerraDraw API with a MapLibre adapter and custom modes const draw = new TerraDraw({ @@ -272,42 +321,42 @@ const draw = new TerraDraw({ map: mapLibreMap, // The decimal precision of the coordinates created - coordinatePrecision: 9 + coordinatePrecision: 9, }), // Modes is an object containing all the modes we wish to // instantiate Terra Draw with modes: [ - new TerraDrawSelectMode({ - flags: { - // Following flags determine what you can do in - // select mode for features of a given mode - in this case polygon - polygon: { - feature: { - scaleable: true, - rotateable: true, - draggable: true, - coordinates: { - midpoints: true, + new TerraDrawSelectMode({ + flags: { + // Following flags determine what you can do in + // select mode for features of a given mode - in this case polygon + polygon: { + feature: { + scaleable: true, + rotateable: true, draggable: true, - deletable: true - } - } - } - } - }), - new TerraDrawPolygonMode({ - allowSelfIntersections: false, - pointerDistance: 30 - }) - ] -}) + coordinates: { + midpoints: true, + draggable: true, + deletable: true, + }, + }, + }, + }, + }), + new TerraDrawPolygonMode({ + allowSelfIntersections: false, + pointerDistance: 30, + }), + ], +}); // Start drawing -draw.start() +draw.start(); // Set the mode to polygon -draw.setMode('polygon') +draw.setMode("polygon"); ``` ## Other Examples @@ -321,4 +370,3 @@ The [development folder features an example](https://github.com/JamesLMilner/ter ### Full Example The [Terra Draw official website](https://github.com/JamesLMilner/terra-draw-website) is open source acts as a full working implementation of how to use Terra Draw. In this case it is used with popular framework Preact (has very similar API to React). -