---
title: Map
description: The Map is the central component of Waymark JS. It is used to display Basemaps, Overlays and an interface for interacting with the Map.
---

Powered by [Leaflet JS](https://leafletjs.com/) with [OpenStreetMap](https://www.openstreetmap.org/) as the default Basemap.

# Map

The Map is the central component of Waymark JS. It is used to display Basemaps, Overlays (Markers, Lines and Shapes) as well as an interface for interacting with the Map. The Map can be used in two modes: Viewer and Editor.

## Instances

Maps can either be read-only using the Viewer, or editable using the Editor. Both the Viewer and Editor extend the `Waymark_Map` class.

Multiple maps can be used on a single page, each with their own configuration. A single Map is known as an Instance and is created using the `Waymark_Map_Factory` which is attached to the `window` object. To create a new Instance, use the `viewer` or `editor` method of the `Waymark_Map_Factory`:

```javascript
// Create a Viewer Instance
const viewer = window.Waymark_Map_Factory.viewer();
```

### Configuration

Once an Instance has been created, it must be initialised with a configuration in order to display a Map.

Each Instance is provided its own configuration, as a JavaScript object, which is passed to the `init` method of the Map Instance.

```javascript
// Initialise with our options
viewer.init({
  map_options: {
    map_init_zoom: 10,
    map_init_latlng: [-128.0094, 50.6539],
    map_init_basemap: "Satellite Imagery",
  },
});
```

### Data

Geographical data is represented in [GeoJSON](https://geojson.org/) format. Data can be [loaded](viewer#loading-data) into the Instance using the `load_json` method, which accepts a GeoJSON object as an argument.

```javascript
// Load GeoJSON data
viewer.load_json({
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: { type: "Point", coordinates: [-85.038, 49.4595] },
      properties: { type: "food" },
    },
  ],
});
```

> [!NOTE]
> The object is expected to be a [FeatureCollection](https://geojson.org/geojson-spec.html#feature-collection-objects) with an array of [Features](https://geojson.org/geojson-spec.html#feature-objects), even if only one Feature is being added.

The current state of the Map is accessible through the `Waymark_Map.map_data` object, which contains the current GeoJSON data. This is a Leaflet [GeoJSON Layer](https://leafletjs.com/reference.html#geojson) and provides the current state of the Map in GeoJSON using the `toGeoJSON` method.

```javascript
// Get GeoJSON data
const map_data = viewer.map_data.toGeoJSON();
```

## Viewer

The Viewer can be used to display [Basemaps](#basemaps) with a single Marker, or many Overlays (Markers, Lines and Shapes). Each Overlay can be given a Title, Description and Image URL, which are displayed in a Popup when the Overlay is clicked. For security, the Title is rendered as plain text, the Description is sanitised HTML (safe tags such as `p`, `a`, `br`, `strong`, `em`, `ul`/`ol`/`li`, `div`, `span` and `blockquote` are allowed; scripts and event handlers are stripped), and Image URLs must use `http`/`https`.

To create a Viewer Instance, use the `viewer` method of the `Waymark_Map_Factory`:

```javascript
// Create a Viewer Instance
const viewer = window.Waymark_Map_Factory.viewer();
```

Overlays can be categorised using Types, provided to the `map_options` [object](#types). These allow you to define custom Icons, Colours and more. To associate an Overlay to a Type, set the `type` property in the GeoJSON feature to the relevant [Type Key](map#marker-types) (based on the Title, "Pub" => `pub`).

The Viewer has some features that are not available in the Editor, such as the Image Gallery, Overlay Filter and Elevation Profile.

## Editor

The Editor can be used to create, edit and delete Overlays. It has a similar interface to the Viewer, but with additional controls for adding and editing Overlays. The Editor can also be used to import and export GeoJSON data, which can be used to save and load Maps.

To Create an Editor Instance, use the `editor` method of the `Waymark_Map_Factory`:

```javascript
// Create an Editor Instance
const editor = window.Waymark_Map_Factory.editor();
```

Data can be added using the `load_json` method, which accepts a GeoJSON object. Every time the Map is edited, the Map is converted to GeoJSON and output into the value of a `<textarea>` element.

This can be used to easily integrate Waymark JS with a form. You can specify the container ID using the `editor_options.data_div_id` [option](editor#options). The default `<textarea id="waymark-data">` will be created automatically if the container is not found.

> [!IMPORTANT]
> Waymark JS does not currently handle reading from file. You can see how Waymark JS can be integrated with a WordPress back-end to handle this [here](https://github.com/OpenGIS/Waymark/blob/master/assets/js/admin.js).

## Map Options

These options, provided in the `map_options` object, are used to customise both Viewer and Editor Modes.

| Option             | Values   | Description                                                                      | Example                    |
| ------------------ | -------- | -------------------------------------------------------------------------------- | -------------------------- |
| `map_div_id`       | string   | The ID of the HTML element to contain the Map. Defaults to `waymark-map`.        | `map`                      |
| `map_height`       | number   | Specify the desired height of the Map (in pixels).                               | `420`                      |
| `map_width`        | number   | Specify the desired width of the Map (in pixels).                                | `800`                      |
| `map_init_zoom`    | `0`-`18` | The initial zoom level of the Map.                                               | `10`                       |
| `map_init_latlng`  | array    | The initial centre coordinates of the Map (Latitude,Longitude).                  | `[51.5074, 0.1278] `       |
| `map_init_basemap` | string   | The initial basemap of the Map. Use the exact title, including spaces.           | `Satellite Imagery`        |
| `map_max_zoom`     | `0`-`18` | The maximum zoom level of the Map.                                               | `12`                       |
| `show_scale`       | `1`/`0`  | Whether to show the scale on the Map.                                            | `1`                        |
| `tile_layers`      | array    | An array of Basemaps to be used on the Map.                                      | [See Below](#basemaps)     |
| `marker_types`     | array    | An array of Marker Types to be used on the Map.                                  | [See Below](#marker-types) |
| `line_types`       | array    | An array of Line Types to be used on the Map.                                    | [See Below](#line-types)   |
| `shape_types`      | array    | An array of Shape Types to be used on the Map.                                   | [See Below](#shape-types)  |
| `debug_mode`       | `1`/`0`  | Whether to enable debug mode. This will output debug information to the console. | `1`                        |

> [!TIP]
> Map options are available to both the Viewer and Editor.

### Basemaps

Waymark uses the excellent [OpenStreetMap](https://www.openstreetmap.org/) as it’s default Basemap and supports [many other providers](https://leaflet-extras.github.io/leaflet-providers/preview/).

Basemaps are added to the Map using the `map_options.tile_layers` array, each Basemap is an object with the following options:

| Option              | Values   | Description                                                                                                     | Example                                                                                   |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `layer_name`        | string   | The Name will appear in a dropdown list shown by the Map when multiple Basemaps have been entered.              | `OpenStreetMap`                                                                           |
| `layer_url`         | string   | Many mapping services support the Slippy Map format. Waymark requires URLs that contain `{z}`, `{x}` and `{y}`. | `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?r=1`                                  |
| `layer_attribution` | string   | The attribution to be displayed on the Map.                                                                     | `&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors` |
| `layer_max_zoom`    | `0`-`18` | The maximum zoom level of the Basemap.                                                                          | `14`                                                                                      |

This is an example of a Basemap configuration:

```javascript
const config = {
  map_options: {
    tile_layers: [
      {
        layer_name: "OpenStreetMap",
        layer_url: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?r=1",
        layer_attribution:
          '@copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        layer_max_zoom: "18",
      },
      {
        layer_name: "OpenTopoMap",
        layer_url: "https://{a|b|c}.tile.opentopomap.org/{z}/{x}/{y}.png",
        layer_attribution:
          '© <a href="https://openstreetmap.org/copyright">OSM</a>-Mitwirkende, SRTM | © <a href="http://opentopomap.org" data-moz-translations-id="285">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>',
        layer_max_zoom: "17",
      },
    ],
  },
};
```

> [!TIP]
> OpenStreetMap is the default Basemap. If you do not provide any Basemaps, OpenStreetMap will be used.

### Types

Customise how Overlays are displayed on the Map. When you add an Overlay (Marker, Line or Shape) to the Map you may want to style it in a certain way. In the case of Markers, you may want to use certain icons and colours.

Types allow you set these styles once, using the `map_options.marker_types`, `map_options.line_types` and `map_options.shape_types` arrays. Once a type has been provided, an Overlay can be assigned to it using the `type` feature property.

We can create a new Marker Type `pub` by adding it to the `marker_types` array like this:

```javascript
const config = {
  map_options: {
    marker_types: [
      {
        marker_title: "Pub",
        marker_shape: "marker",
        marker_size: "large",
        icon_type: "icon",
        marker_icon: "ion-beer",
        marker_colour: "#fbfbfb",
        icon_colour: "#754423",
      },
    ],
  },
};
```

When a Marker is added to the Map, it can be associated with the "Pub" Type by setting the `type` feature property to `pub`:

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-2.548828125, 51.46769693762546]
      },
      "properties": {
        "type": "pub",
        "title": "Great place for a pint!"
      }
    }
  ]
}
```

#### Marker Types

Marker Types are added to the Map using the `marker_types` array, each Marker Type is an object with the following options:

| Option          | Values                          | Description                                                                                                                                                                                                                                                                   | Example   |
| --------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `marker_title`  | string                          | What kind of Marker is this? E.g. `Photo`, `Grocery Store`, `Warning!`. Marker Titles should be unique and are used to generate [Type Keys](#type-keys).                                                                                                                      | `Pub`     |
| `marker_shape`  | `marker`, `circle`, `rectangle` | Which shape of Marker to use. Circles and Squares are centered at the specified location, Markers point down to that location.                                                                                                                                                | `marker`  |
| `marker_size`   | `small`, `medium`, `large`      | Which size of Marker to use.                                                                                                                                                                                                                                                  | `large`   |
| `marker_colour` | CSS Color                       | The Marker background colour, provided as a CSS colour (e.g. `white`, `#ffba00`, `rgb(255, 186, 0)`).                                                                                                                                                                         | `#da3d20` |
| `icon_type`     | `icon`, `text`, `html`          | Font Icons are available from Font Awesome and Ionic Icons. Simple Text or Emojis are supported, as well as custom HTML.                                                                                                                                                      | `icon`    |
| `marker_icon`   | string                          | Enter the `text`/`html` ([Emojis](https://emojifinder.com/) and nested HTML supported!) For `icon` enter the [Ionicons](https://ionic.io/ionicons/v2/cheatsheet.html) or [Font Awesome](https://fontawesome.com/v4/cheatsheet/), icon name e.g. `ion-camera`, or `fa-camera`. | `🍺`      |
| `icon_colour`   | CSS Color                       | The colour of the icon, provided as a CSS colour (e.g. `white`, `#ffba00`, `rgb(255, 186, 0)`).                                                                                                                                                                               | `#ffba00` |

The following is an example of a Marker Type configuration:

```javascript
const config = {
  map_options: {
    marker_types: [
      {
        marker_title: "Pub",
        marker_shape: "marker",
        marker_size: "large",
        icon_type: "icon",
        marker_icon: "ion-beer",
        marker_colour: "#fbfbfb",
        icon_colour: "#754423",
      },
    ],
  },
};
```

#### Line Types

Line Types are added to the Map using the `line_types` array, each Line Type is an object with the following options:

| Option         | Values     | Description                                                                                                                                             | Example     |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `line_title`   | string     | What kind of Line is this? E.g. `Bike Path`, `Walking Only`, `Dark Red`. Line Titles should be unique and are used to generate [Type Keys](#type-keys). | `Bike Path` |
| `line_colour`  | CSS Colour | The colour of the Line, provided as a CSS colour (e.g. `white`, `#ffba00`, `rgb(255, 186, 0)`).                                                         | `#3cbc47`   |
| `line_weight`  | number     | The width of the Line, in pixels.                                                                                                                       | `2`         |
| `line_opacity` | `0`-`1`    | The opacity of the Line, between `0.0` and `1.0`.                                                                                                       | `0.85`      |

The following is an example of a Line Type configuration:

```javascript
const config = {
  map_options: {
    line_types: [
      {
        line_title: "Bike Path",
        line_colour: "#3cbc47",
        line_weight: "2",
        line_opacity: "0.5",
      },
    ],
  },
};
```

#### Shape Types

Shape Types are added to the Map using the `shape_types` array, each Shape Type is an object with the following options:

| Option         | Values     | Description                                                                                                                                       | Example   |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `shape_title`  | string     | What kind of Shape is this? E.g. `Park`, `Danger!`, `Light Blue`. Shape Titles should be unique and are used to generate [Type Keys](#type-keys). | `Park`    |
| `shape_colour` | CSS Colour | The colour of the Shape, provided as a CSS colour (e.g. `white`, `#ffba00`, `rgb(255, 186, 0)`).                                                  | `#81d742` |
| `fill_opacity` | number     | The opacity of the inside of the Shape, between `0.0` and `1.0`.                                                                                  | `0.5`     |

The following is an example of a Shape Type configuration:

```javascript
const config = {
  map_options: {
    shape_types: [
      {
        shape_title: "Park",
        shape_colour: "#81d742",
        fill_opacity: "0.5",
      },
    ],
  },
};
```

#### Type Keys

Type Keys are a unique string that identifies a Type. The Type Title is used to create the Type Key, by removing any non-alpha-numeric characters and converting it to lowercase.

> [!TIP]
> The Type Key for "Pub" would be `pub`. The Type Key for "A Much Longer Title" would be `amuchlongertitle`.

When assigning a Type to an Overlay, the `type` feature property must match the Type Key. For example, to assign the "Pub" Type to a Marker:

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "type": "pub",
        "title": "Great place for a pint!"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-2.548828125, 51.46769693762546]
      }
    }
  ]
}
```

Waymark JS adds the Type Key to the Overlay using the `waymark-marker-[type_key]` class. For example, the "Pub" Type would be:

```html
<div class="waymark-marker waymark-marker-pub">
  <div class="waymark-marker-background" style="background:#fbfbfb;"></div>
  <i
    style="color:#754423;"
    class="waymark-marker-icon waymark-icon-icon ion ion-beer"
  ></i>
</div>
```

You can use this class to target specific Types in your CSS, for example:

```css
/* Adjust the "Pub" Marker Text Icon size */
.waymark-marker-pub i {
  font-size: 24px !important;
}
```

> [!TIP]
> Use your browser’s inspector ([Firefox](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Open_the_Inspector) / [Chrome](https://developer.chrome.com/docs/devtools/open/)) to find Type keys.
