API overview

This article describes the structure of dotAtlas API and outlines the typical lifecycle of a dotAtlas instance.

The general principle behind dotAtlas API is to provide a set of fairly low-level features that can be combined into more complex application-specific set ups. Therefore, the core API is limited to creating map layers and exposing low level events, such as mouse click or hover. High-level features, such as point selection or animated effects, are implemented as plugins extending the core API. The plugins are open source, so you can tailor them to the needs of your specific application.

The entry point to the API is the DotAtlas class, which exposes a number of static methods for creating dotAtlas instances. The typical dotAtlas workflow is the following:

  1. Start by embedding a dotAtlas element inside your application. Optionally, you can provide some initial map layers to display.

    import { DotAtlas } from "@carrotsearch/dotatlas";
    
    const dotatlas = DotAtlas.embed({
      element: document.getElementById("dotatlas"),
      layers: [
        // provide layer data here
      ]
    });

    The dotAtlas instance created during embedding exposes a number of methods for interacting with the specific instance, such as setting new data, adding and removing event listeners.

  2. When required, you can set new map layers to display:

    dotatlas.set("layers", [
      // new layer data here
    ]);
  3. To modify properties of specific layers, get the instance of the layer first:

    const elevations = dotatlas.get("layers")[0];
    elevations.set({
      "lightIntensity": 0.25,
      "contourWidth": 0.05
    });

    Then, call redraw() to have the changes reflected in your visualization:

    dotatlas.redraw();
  4. To react on dotAtlas global events, use the on() or once() method:

    dotatlas.on("click", e => {
      // do something
    });

    The same methods are available on the layer instance object, so that you can react on layer-specific events:

    const elevations = dotatlas.get("layers")[0];
    elevations.once("maxElevationChanged", e => {
      // do something
    });
  5. If your dotAtlas container changes dimensions, call the resize() method to reallocate internal display buffers:

    dotatlas.resize();
  6. Once your application does not need dotAtlas any more, make sure to dispose of the instance to remove the internal DOM elements and the associated resources:

    dotatlas.dispose();
  7. dotAtlas comes with a number of plugins. To use them, you'll need to attach the plugins when embedding dotAtlas:

    import { DotAtlas, Theme, Effects } from "@carrotsearch/dotatlas";
    
    const dotatlas = DotAtlas.with(Theme, Effects).embed({
      element: document.getElementById("dotatlas"),
      layers: [
        // provide layer data here
      ]
    });

    Plugins may add extra options for you to set:

    dotatlas.set({
      "theme": "dark",
      "rolloutDuration": 1000
    });