# Getting Started

Terra Draw adds a number of geographical Feature drawing tools to popular mapping libraries. There are few key concepts that allow it to stay strongly decoupled and as library-agnostic as possible, let's walk through them.

## Key Concepts

> [!TIP]
> TL;DR? Jump to the [Installation](#installation) section to get started, or:
>
> ```javascript
> npm install terra-draw
> ```

### Store

The Store is the heart of the library and is responsible for managing the state of all Features that are added to the map. The Store is created when Terra Draw is instantiated:

```javascript
// Create a Terra Draw instance and assign it to a variable called `draw`
const draw = new TerraDraw({ adapter, modes });
```

> [!IMPORTANT]
> Throughout the documentation we will use the variable name `draw` to refer to the Terra Draw instance.

Features are added to the Store when interacting with the Map using a number of available drawing Modes (such as `TerraDrawRectangleMode` or `TerraDrawPolygonMode`).

The Store is exposed via the `getSnapshot` method, which returns an Array of all given Feature geometries in the Store:

```javascript
// Get an Array of all Features in the Store
const features = draw.getSnapshot();
```

See the [Store](./2.STORE.md) section to find out more about the store and getting data in and out of Terra Draw.

### Adapters

Adapters are thin wrappers that contain map library specific logic, for creating and updating layers rendered by the mapping library. Terra Draw supports a series of Adapters out of the box, with a series of packages within this monorepo. Currently supported are: Leaflet, OpenLayers, Mapbox GL JS, MapLibre GL JS, Google Maps JS API and the ArcGIS JS SDK. 

Let's say as an example you are using [Leaflet](https://leafletjs.com/), you would install the Leaflet adapter (`TerraDrawLeafletAdapter`) in the following way:

```shell
npm install terra-draw-leaflet-adapter
```

And then in your code you would import it like so:

```javascript

import { TerraDrawLeafletAdapter } from 'terra-draw-leaflet-adapter';

// Create an Adapter for Leaflet
const adapter = new TerraDrawLeafletAdapter({ map, lib });
```

See the [Adapters](./3.ADAPTERS.md) section for more information on the different adapters for different mapping libraries.

### Modes

Modes represent the logic for a specific drawing tool, for example there are `TerraDrawRectangleMode`, `TerrDrawPolygonMode` and `TerraDrawLineStringMode` Modes which allow you to draw rectangles, polygons and lines on the map respectively.

The `TerraDrawSelectMode` allows for the selection and manipulation of features on the Map, while the `TerraDrawRenderMode` is used to render uneditable features, for example contextual data.

Modes are instantiated like so:

```javascript
const polygonMode = new TerraDrawPolygonMode();
const rectangleMode = new TerraDrawRectangleMode();
const renderMode = new TerraDrawRenderMode({
  modeName: "auniquename",
});
```

See the [Modes](./4.MODES.md) section for more information. For information regarding touch support, see [Touch Device Support](./4.MODES.md#touch-device-support).

## Installation

Terra Draw can be added to your site either via the `<script>` tag, or using a package manager like NPM.

### npm

> [!IMPORTANT]
> We start with the assumption that you have both **Node.js** and **npm** [installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

You can install the Terra Draw into your project like so:

```shell
npm install terra-draw
```

View the [npm terra-draw package page](https://www.npmjs.com/package/terra-draw) for more information.

You will need an adapter as well, to connect your mapping library to Terra Draw. Let's install the MapLibre adapter:

```shell
npm install terra-draw-maplibre-gl-adapter
```

View the [npm terra-draw-maplibre-gl-adapter page](https://www.npmjs.com/package/terra-draw-maplibre-gl-adapter) for more information.


#### Usage

Once installed via NPM you can use Terra Draw in your project like so:

```javascript
// Import Terra Draw
import { TerraDraw, TerraDrawRectangleMode } from "terra-draw";

import { TerraDrawMapLibreGLAdapter } from 'terra-draw-maplibre-gl-adapter

// Import MapLibreGL
import { MapLibreGL as lib } from "maplibre-gl";

// Create MapLibre Map, targeting <div id="map">
const map = new MapLibreGL.Map({ container: "map" });

// Create Terra Draw
const draw = new TerraDraw({
  // Using the MapLibre Adapter
  adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),

  // Add the Rectangle Mode
  modes: [new TerraDrawRectangleMode()],
});

// Start drawing
draw.start();
draw.setMode("rectangle");
```

### Script Tag

To use Terra Draw without a build step, you can load the UMD (Universal Module Definition) bundle directly from a CDN (Content Delivery Network) like [unpkg](https://unpkg.com/).

#### Usage

For example if we were using Terra Draw with MapLibre we might do something like this in our `<head>` tag:

```html
<!-- MapLibre -->
<script src="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.js"></script>
<link
  href="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.css"
  rel="stylesheet"
/>
<!-- Terra Draw -->
<script src="https://unpkg.com/terra-draw@1.0.0/dist/terra-draw.umd.js"></script>
<script src="https://unpkg.com/terra-draw-maplibre-gl-adapter@1.0.0/dist/terra-draw-maplibre-gl-adapter.umd.js"></script>

```

Later on in our JavaScript code we can access `terraDraw` globally like so:

```javascript

const TerraDraw = terraDraw.TerraDraw
const TerraDrawMapLibreGLAdapter = terraDrawMapLibreGLAdapter.TerraDrawMapLibreGLAdapter

// Create Terra Draw instance
const draw = new TerraDraw({
  // Using the MapLibre Adapter from the separate package
  adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),

  // Add the Rectangle Mode
  modes: [new TerraDrawRectangleMode()],
});
```

#### Example

Putting these concepts together we can create a simple map with freehand drawing enabled like so:

```html
<!doctype html>
<html>
  <head>
    <!-- Required Styles & Script -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.css"
    />
    <script src="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.js"></script>
    <script src="https://unpkg.com/terra-draw@1.0.0-beta.0/dist/terra-draw.umd.js"></script>
  </head>
  <body>
    <!-- Map Container (must have dimensions set!) -->
    <div id="map" style="height:420px;"></div>

    <script>
      // Create MapLibre Map, targetting <div id="map">
      // See https://maplibre.org/maplibre-gl-js/docs/
      var map = new maplibregl.Map({
        container: "map",
        style: "https://demotiles.maplibre.org/style.json",
        center: [-4.49049, 54.189649], // [lng, lat]
        zoom: 5,
      });

      // Create Terra Draw
      const draw = new terraDraw.TerraDraw({
        adapter: new terraDraw.TerraDrawMapLibreGLAdapter({
          map: map,
          lib: maplibregl,
        }),
        modes: [new terraDraw.TerraDrawFreehandMode()],
      });

      // Start drawing
      draw.start();

      // Set the mode to rectangle
      draw.setMode("freehand");
    </script>
  </body>
</html>
```

## API Docs

You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api).

## Other Examples

There are a few other working examples that you can use as points of reference for creating a new app using Terra Draw:

- [Development Example](https://github.com/JamesLMilner/terra-draw/blob/main/guides/7.DEVELOPMENT.md) - showcases all of Terra Draw Modes and Adapters. It is meant for local development but can also be used as a guide of how to use Terra Draw with each Adapter without any framework.
- [Terra Draw Website](https://terradraw.io/) - 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). It's [Open Source](https://github.com/JamesLMilner/terra-draw-website) too!

---

**Guides**

1. [x] Getting Started
2. [ ] [Store](./2.STORE.md)
3. [ ] [Adapters](./3.ADAPTERS.md)
4. [ ] [Modes](./4.MODES.md)
5. [ ] [Styling](./5.STYLING.md)
6. [ ] [Events](./6.EVENTS.md)
7. [ ] [Development](./7.DEVELOPMENT.md)
8. [ ] [Examples](./8.EXAMPLES.md)