SuperMap iClient for MapLibreGL

This guide will quickly get you started on SuperMap iClient for MapLibreGL. You can get detailed interface parameters on the API page.

Preparing your page

Get MapLibreGL and SuperMap iClient for MapLibreGL

MapLibreGL and SuperMap iClient for MapLibreGL are needed for development.Among them, MapLibreGL includes CSS files and JS files. You can get these documents in the following way:

MapLibreGL

SuperMap iClient for MapLibreGL

Import

Import files

The following is detailed account of how to import MapLibreGL v1 files online via CDN, and how to import SuperMap iClient for MapLibreGL through online sites.

Create a new HTML file, import MapLibreGL v1 CSS file and JS file in < head> tag, and fill in UNPKG's hosting address, as follows:

      <!DOCTYPE html>
     <html>
        <head>
            <meta charset="UTF-8">
            <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet">
            <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
        </head>
     </html>

Introduce the iclient-maplibregl CSS file and JS file, and fill in the SuperMap iClient for MapLibreGL online site address:

      <!DOCTYPE html>
      <html>
          <head>
            <meta charset="UTF-8">
            <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet" />
            <link href="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.min.css" rel="stylesheet" />
            <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
            <script type="text/javascript" src="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.js"></script>
          </head>
      </html>

npm

Before using this method, please check if the application Node.js，is installed on your computer. If it is not installed, you can install it by downloading the installer Then install SuperMap iClient for MapLibreGL by entering the following command on the command line:

 npm install @supermap/iclient-maplibregl
Import the CSS files

Create a new HTML file and import the MapLibreGL CSS file and the iclient-maplibregl CSS file into the <head> tag as follows: 

  <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css"/>

<link href="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.min.css" rel="stylesheet" />

Modular Development

ES6

You need to use npm to install dependencies before development, and then import the corresponding modules through ES6's import module loading syntax.

  On demand

First，install @supermap/babel-plugin-import:

                              npm install @supermap/babel-plugin-import -D

Then edit .babelrc:

                                {
  "plugins": [
    ["@supermap/babel-plugin-import",
      {
      "libraryName": "@supermap/iclient-maplibregl"
      }
    ]
  ]
}

Next, if you need QueryByBoundsParameters, QueryService, edit:

 import maplibregl from 'maplibre-gl';
import {QueryByBoundsParameters, QueryService} from '@supermap/iclient-maplibregl';

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new QueryByBoundsParameters(...);
  new QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

  Import all modules 

     import maplibregl from 'maplibre-gl';
import '@supermap/iclient-maplibregl';

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
    var param = new maplibregl.supermap.QueryByBoundsParameters(...);
    new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
        map.addLayer(...);
    });
});

CommonJS

CommonJS is a JavaScript modular specification based on the Node.js environment. Use npm to install dependencies before development, and then introduce the corresponding modules via the require method.

  Import partial modules 

     var maplibregl = require('maplibregl') ;
var QueryByBoundsParameters = require('@supermap/iclient-maplibregl').QueryByBoundsParameters;
var QueryService = require('@supermap/iclient-maplibregl').QueryService;

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new QueryByBoundsParameters(...);
  new QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

  Import all modules 

     var maplibregl = require('maplibregl') ;
require('@supermap/iclient-maplibregl');

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new maplibregl.supermap.QueryByBoundsParameters(...);
  new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

AMD

The following example uses the RequireJS library to implement; Download maplibre-gl.js and iclient-maplibregl.js through " Get MapLibreGL and SuperMap iClient for MapLibreGL " and place them in the directory where the entry master file specified by RequireJS is located.

  Import all modules 

                                            
require(['js/maplibre-gl.js'], function(maplibregl) {
    window.maplibregl = maplibregl;
    require(['js/iclient-maplibregl'], function() {
      var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
      var map = new maplibre.Map({
          container: 'map',
          style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
          center: [0, 0],
          zoom: 2
      });

      map.on('load', function() {
        var param = new maplibregl.supermap.QueryByBoundsParameters(...);
        new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
            map.addLayer(...);
        });
      });
    });
});

CMD

The following example uses the SeaJS library to implement; Download maplibre-gl.js and iclient-maplibregl.js through " Get MapLibreGL and SuperMap iClient for MapLibreGL " and place them in the directory where the entry master file specified by SeaJS is located.

  Import all modules 

                                                define(function(require, exports, module) {
    require('./maplibre-gl.js');
    require('./iclient-maplibregl.js');

    var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
    var map = new maplibre.Map({
        container: 'map',
        style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
        center: [0, 0],
        zoom: 2
    });

    map.on('load', function() {
      var param = new maplibregl.supermap.QueryByBoundsParameters(...);
      new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
          map.addLayer(...);
      });
    });
});

Package configuration

Because iClient uses ES6, to be compatible with browsers that do not support ES6 syntax, some configuration, including syntax conversion, needs to be done during the packaging process.

The packaged configuration here is for ES6 and CommonJS modular development, and for projects developed for AMD and CMD modules, there is no need to utilize packaging tools.

Take webpack4 as an example. Since the different package managers will cause the structure of the installation package to be different, the following examples describe the npm and cnpm configurations:

If you use npm install or cnpm install --by=npm to install dependencies, you need to add the following configuration items in the webpack.config.js.

 module: {
    rules: [{
    // Convert ES6 syntax to ES5 using babel-loader
        test: /\.js$/,
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env']
        }
    }]
}

If you use cnpm install to install dependencies, you need to add the following configuration items in the webpack.config.js.

                                                module: {
        rules: [{
            // Convert ES6 syntax to ES5 using babel-loader
            test: /\.js$/,
            loader: 'babel-loader',
            options: {
              presets: ['@babel/preset-env']
            }
        }]
    }

Creating a map

Map published by SuperMap iServer

In the Preparing Your Page section, a new HTML page has been created, and continue to add code to create maps in the page, as follows:

                         <!DOCTYPE HTML>
<html>
    <head>
        <meta charset="UTF-8">
        <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet">
        <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
        <script type="text/javascript" src="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.js"></script>
    </head>
    <body>
        // The div displayed by map
        <div id="map" style="position:absolute;left:0px;right:0px;width:800px;height:500px;"></div>
    </body>
</html>

Taking the world map published in SuperMap iServer as an example, add code to 

  var map = new maplibregl.Map({
    container: 'map',
    style: {
        "version": 8,
        "sources": {
            "raster-tiles": {
                "attribution": attribution,
                "type": "raster",
                "tiles": ['https://iserver.supermap.io/iserver/services/map-china400/rest/maps/China/zxyTileImage.png?z={z}&x={x}&y={y}'],
                "tileSize": 256
            }
        },
        "layers": [{
            "id": "simple-tiles",
            "type": "raster",
            "source": "raster-tiles",
            "minzoom": 0,
            "maxzoom": 22
        }]
    },
    center: [120.143, 30.236], // starting position
    zoom: 3 // starting zoom
});See full example code »

Enjoy the result.

Adding controls

By adding controls to the map, you can achieve interactive operations such as zooming in and zooming out. Commonly used controls:

Control Class name Introduction
Navigation maplibregl.NavigationControl The default is in the top left corner of the map
Scale maplibregl.ScaleControl The default is at the bottom left corner of the map
Fullscreen maplibregl.FullscreenControl The default is in the top right corner of the map
Locate maplibregl.GeolocateControl The default is in the top left corner of the map
Copyright maplibregl.AttributionControl The default is in the lower right corner of the map

When adding a control, you should initialize the map first, and then add the control to the map via the addControl() method, for example:

Navigation control

 // Add Control
map.addControl(new maplibregl.NavigationControl(), 'top-left');See full example code »

Enjoy the result.

Scale control

 map.addControl(new maplibregl.ScaleControl({}));See full example code »

Enjoy the result.

Using vector tiles

Vector tiles organize and define vector data through different description files, analyze data in real time and complete rendering on the client. SuperMap iServer provides vector tile layers

 var map = new maplibregl.Map({
    container: 'map', // container id
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [120.143, 30.236], // starting position
    zoom: 0,
    attributionControl: false
});
         See full example code »

Enjoy the result.