JavaScript API

Overview

Namespace

All API components belong to the mappable namespace.

Component names

The name of any JS API component satisfies two conditions:

  • starts with a capital letter with the prefix MMap
  • written in CamelCase.

For example: MMap, MMapMarker, MMapListener.

Map objects

Name

Description

Representation in the API

Map

The main object that coordinates its components.

MMap class

Layer

An object for displaying data.

Classes with the Layer postfix

Data source

An object for loading data that transfers the display data to layers.

Classes with the DataSource postfix

Marker

A map element with the DOM content, wrapper over MMapFeature.

MMapMarker class

Geo object

A polygon, a line, a marker.

MMapFeature class

Visual elements

Objects used to manage the map: zoom button, geolocation button, and so on.

Classes with the Control postfix

Utilities

Auxiliary objects for working with the API. For example, MMapListener is responsible for subscribing to the map's events.

MMapListener class

Hierarchy of map objects

Some map objects (such as the map itself) may contain internal nodes known as children. Other objects (such as MMapTileDataSource) don't have this feature.

Map

MMap is the root element in the hierarchy. To initialize it, in the constructor of the object you need to pass:

<!-- Create a container for the map -->
<div id="root"></div>

const {MMap} = mappable;

// Initialize the map
const map = new MMap(

  // Pass the link to the HTMLElement of the container
  document.getElementById('root'),

  // Pass the map initialization parameters
  {
    location: {
      zoom: 10,
      center: [25.229762, 55.289311]
    }
  }
);

All JS API objects are initialized according to their own rules, but they are added to the map using the addChild() method called from the map instance. You can delete objects using the symmetric removeChild() method:

const {MMap, MMapLayer} = mappable;

// Initialize the map
const map = new MMap(...);

// Initialize the layer
const layer = new MMapLayer(...);

// Add this layer to the map
map.addChild(layer);

Learn more about MMap.

Layer

A layer is a visual component that is responsible for drawing some objects on the map. For example, the marker layer displays points on the map, and the tile layer displays the geographical map itself.

The map can contain any number of layers, the API has no restrictions on the number of layers. For example, you may add a layer on which images with clouds will be displayed, place a tile layer under it, and add a layer of traffic jams between them.

Alert

By default, the map displays layers in the order they were added.
You can also easily control this order using the zIndex parameter.

Learn more about MMapLayer.

Data sources

Each layer needs data to display. In the JS API, data sources are objects with the DataSource postfix. For example, MMapTileDataSource is an object for loading raster or vector map tiles.

For example, you want to display tiles received from the site https://sitename.com :

const {MMap, MMapTileDataSource, MMapLayer} = mappable;

// Initialize the map
const map = new MMap({...});

// Initialize the data source
const tileDataSource = new MMapTileDataSource({
  id: 'someSource',
  raster: {
    type: 'someType',
    fetchTile: 'https://sitename.com/?x={{x}}&y={{y}}&z={{z}}&scale={{scale}}'
  }
});

// Add the data source to the map
map.addChild(tileDataSource);

// Create a layer with the received data
const layer = new MMapLayer({
  zIndex: 1,
  source: 'someSource',
  type: 'someType'
});

// Add this layer to the map
map.addChild(layer);

Note

A text identifier is used to link the data source and the layer. Be careful, the identifier for the data source is set in the id field, and the source field is used when transferring to the layer.

Layer with data source

There are several layers in the JS API for which data sources are already configured.

  • MMapDefaultFeaturesLayer — adds a data source and a layer of geo objects (polygons, lines, points, placemarks)
  • MMapDefaultSchemeLayer — adds a data source and a schema layer
    • type: 'ground' — the entire schema in the raster version, the earth layer in the vector version
    • type: 'buildings' — a layer of buildings in the vector version
    • type: 'icons' — icon layer in the vector version
    • type: 'labels' — labels layer in the vector version

For example, this code will add all "schema" type layers with all data sources to the map:

map.addChild(new MMapDefaultSchemeLayer({theme: 'light'}));

Note

In this example, the layer constructor receives only the color theme as parameter, the other parameters are used by default from MMapDefaultSchemeLayer.defaultProps

You may manually do all the same things as in the example above:

// First add an invisible layer to the map.
// It is hidden because it is only used for loading data.
map.addChild(new MMapDefaultSchemeLayer({theme: 'light', visible: false, source: 'scheme'}));

// Then add several layers to the map, specifying for each of them
// which data from MMapDefaultSchemeLayer to display.
map.addChild(new MMapLayer({zIndex: 1, source: 'scheme', type: 'ground'}))
map.addChild(new MMapLayer({zIndex: 2, source: 'scheme', type: 'labels'}))
map.addChild(new MMapLayer({zIndex: 3, source: 'scheme', type: 'buildings'}))
map.addChild(new MMapLayer({zIndex: 4, source: 'scheme', type: 'icons'}))

Marker

Marker is DOM-element with reference to coordinates. Markers can be dragged and adjusted their appearance using the HTML.

const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapMarker} = mappable;

// Initialize the map
const map = new MMap({...});

// Add a layer with roads and buildings
map.addChild(new MMapDefaultSchemeLayer());

// Add a layer for markers
map.addChild(new MMapDefaultFeaturesLayer());

// Create a DOM element for the marker content.
// It is important to do this before initializing the marker!
// The element can be created empty. You can add HTML markup inside after initializing the marker.
const content = document.createElement('section');

// Initialize the marker
const marker = new MMapMarker(
  {
    coordinates: [25.229762, 55.289311],
    draggable: true
  },
  content
);

// Add a marker to the map
map.addChild(marker);

// Add custom HTML markup inside the marker content
content.innerHTML = '<h1>You can drag this header</h1>';

Learn more about MMapMarker.

Initialization parameters

Parameters passed to objects during initialization can be mandatory and optional. For example, the MMap component has the location field required, but `behaviors is not.

const {MMap} = mappable;

const map = new MMap(document.getElementById('root'), {
  location: {
    zoom: 10,
    center: [25.229762, 55.289311]
  },
  behaviors: ['drag', 'scrollZoom', 'pinchZoom', 'dblClick']
});

Learn more about initialization parameters.

Strict mode

You can enable strict mode to track errors in the code. Use the global option strictMode:

mappable.strictMode = true;

In strict mode, the JS API checks the input data. For example, if you add an object to the map that is not a descendant of MMapEntity, the JS API will inform you about it. With strict mode turned off, the JS API will not do such a check, and your code may not work correctly.

Learn more about Strict mode.

React

There is a React analog for each object in the JS API. To use the React version of the API, connect the @mappable-world/mappable-reactify module:

const mappableReactify = await mappable.import('@mappable-world/mappable-reactify');
const reactify = mappableReactify.reactify.bindTo(React, ReactDOM);
const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapMarker} = reactify.module(mappable);

Note

The @mappable-world/mappable-reactify module provides a set of methods for accessing React both individual objects and modules/packages as a whole. The hierarchy of objects and initialization parameters are the same.

After connecting the module, use any JS API objects as React components:

<MMap location={{center: [25.229762, 55.289311], zoom: 9}} mode="vector">
  <MMapDefaultSchemeLayer />
  <MMapDefaultFeaturesLayer />

  <MMapMarker coordinates={[25.229762, 55.289311]} draggable={true}>
    <section>
      <h1>You can drag this header</h1>
    </section>
  </MMapMarker>
</MMap>

Note

For more information about integration with React and other frameworks, see the section Integrations

In this article: