@ogis/waymark-js

Waymark JS

[!CAUTION] Waymark JS v3 is currently in alpha.

Adding meaning to GeoJSON.

Waymark JS is a JavaScript library for rendering GeoJSON data on a OpenStreetMap vector basemap.

«« View the Demo »»

Built on the shoulders of giants:

• MapLibre GL JS for map rendering
• OpenStreetMap for map data
• OpenFreeMap for vector tiles

Installation

NPM

To install via NPM, run:

npm install @ogis/waymark-js

Then import the library and CSS in your JavaScript:

import { createInstance } from "@ogis/waymark-js";
import "@ogis/waymark-js/dist/waymark-js.css";

CDN

ES Module

To use via CDN, include the following in your HTML:

<link
  rel="stylesheet"
  href="https://unpkg.com/@ogis/waymark-js/dist/waymark-js.css"
/>

<script type="module">
  import { createInstance } from "https://unpkg.com/@ogis/waymark-js/dist/waymark-js.js";
</script>

Usage

HTML

Add a container element for the Instance:

<div id="waymark-instance" style="height: 480px"></div>

[!NOTE] Instance element must have a height in order to be visible. If there isn't a DOM element with the given id, Waymark JS will create one for you and append it to the body (with 100% width and height).

JavaScript

Create a Waymark Instance with your configuration, showing some GeoJSON data:

import { createInstance } from "@ogis/waymark-js";
import "@ogis/waymark-js/dist/waymark-js.css";

const instance = createInstance({
  // Will console.log() all Waymark JS Events
  // debug: true,

  // Unique ID repesenting the DOM element to load the Instance into
  // Is added to the DOM if it doesn't exist
  id: "waymark-instance",

  // MapLibre GL JS Options
  // See [MapLibre Map Options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)
  mapOptions: {
    zoom: 12,
  },

  // Can pass GeoJSON here
  geoJSON: {
    type: "FeatureCollection",
    features: [
      {
        // Set an ID here so you can access the Overlay
        id: "pub-marker",
        type: "Feature",
        properties: {
          // Waymark Properties
          waymark: {
            // The Title & Descrption will display when the Marker is clicked
            title: "The Scarlet Ibis",
            description:
              "Great pub, great food! Especially after a Long Ride 🚴🍔🍟🍺🍺💤",

            // MapLibre GL JS Layer Paint Properties
            paint: {
              "circle-radius": 20,
              "circle-color": "white",
              "circle-stroke-color": "brown",
              "circle-stroke-width": 6,
            },

            // Marker Icons
            icon: {
              // <img /> and <i /> tags work well here
              html: `<div style="font-size:32px">🍺</div>`,

              // Inline SVG supported
              // svg: `<svg />`

              // Image URLs supported
              // url: "https://...pint.png
            },
          },
        },
        geometry: {
          type: "Point",
          coordinates: [-128.0094, 50.6539],
        },
      },
    ],
  },

  // This function is called when the Instance has finished loading
  // and is passed the Instance as an argument
  onLoad: (thisInstance) => {
    //Get the Waymark JS Overlay for the "pub-marker" Feature
    const pubMarker = thisInstance.geoJSONStore.getItem("pub-marker");

    // Get the MapLibre GL JS Map
    const map = thisInstance.mapLibreStore.mapLibreMap;

    // Set the map view to fit the Marker (instantly)
    map.setCenter(pubMarker.geometry.coordinates);
    map.setZoom(12);
  },
});

Development

[!IMPORTANT] To build Waymark JS from source, you will need Node + NPM.

# Install dependencies
npm install

# Run the dev server (& tests)
npm run dev

# Build for production
npm run build