Powered by Leaflet JS with OpenStreetMap 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:

// Create a Viewer Instanceconst 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.

// 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 format. Data can be loaded into the Instance using the load_json method, which accepts a GeoJSON object as an argument.

// 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 with an array of Features, 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 and provides the current state of the Map in GeoJSON using the toGeoJSON method.

// Get GeoJSON dataconst map_data = viewer.map_data.toGeoJSON();

Viewer

The Viewer can be used to display 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.

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

// Create a Viewer Instanceconst viewer = window.Waymark_Map_Factory.viewer();

Overlays can be categorised using Types, provided to the map_options object. 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 (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:

// Create an Editor Instanceconst 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 inner HTML 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. 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.

Map Options

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

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

Basemaps

Waymark uses the excellent OpenStreetMap as it’s default Basemap and supports many other providers.

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

This is an example of a Basemap configuration:

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:

//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:

{
  "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:

The following is an example of a Marker Type configuration:

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:

The following is an example of a Line Type configuration:

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:

The following is an example of a Shape Type configuration:

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:

{
  "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:

<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:

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

!TIP Use your browser’s inspector (Firefox / Chrome) to find Type keys.