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

Download CSS file from MapLibreGL Official Website
Download JS file from MapLibreGL Official Website

SuperMap iClient for MapLibreGL

Download the latest version from SuperMap iClient JavaScript Official Website
Download the release version from SuperMap iClient for MapLibreGL GitHub

Import

Import files

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

Create a new HTML file, import MapLibreGL 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).then(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).then(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).then(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).then(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).then(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).then(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.

Web Symbol

Web symbols cover SuperMap iDesktop, SuperMap iDesktopX part of the point line polygon symbols, users can quickly add symbols to the map by Web Symbol ID . At the same time, you can also customize the symbols according to the symbol specification. This section mainly introduces the introductory usage of Web symbols, please refer to the API page for detailed interface.

Import

Import files

First, import MaplibreGL and SuperMap iClient for MaplibreGL .

Then, set the basePath to the absolute or relative path to the resources folder, depending on the following two scenarios.

Default resources folder path

If the resources folder is placed in the same level as the entry HTML file, you do not need to configure the basePath and can just use the default value.
Customize the resources folder path

First, download the SuperMap iClient for MaplibreGL package, move the resources folder to any location in the project.

Then, set basePath to the resources folder absolute or relative to the entry HTML path.
```
                                new maplibregl.supermap.WebSymbol().init({basePath: "./resources/symbols"});
                                
```

npm

First, npm install @supermap/iclient-maplibregl .

Then, move the resources folder under the @supermap/iclient-maplibregl installation package to any folder in the project root directory.

Next, set basePath to the absolute or relative root path to the resources folder.

                        new maplibregl.supermap.WebSymbol().init({basePath: "./resources/symbols"});

Get Started Quickly

Symbol Specification

Web symbols are symbol objects consisting of paint , layout (except visibility property) in Maplibre Layers.

Using Web Symbols

First, get Web Symbol ID.

Then, initialize the Web symbol with new maplibregl.supermap.WebSymbol().init, specify the symbol resource path.

And then, use the interface loadSymbol to load Web symbols.

Next, use the interface addSymbol to add symbols to the map.

Finally, the layer is added using the interface addLayer while the layer sets the Web symbol.

Example code.

                            
    // Web Symbol ID
    const symbolId = "line-962613";
    // Configure symbolic resource paths
    new maplibregl.supermap.WebSymbol().init({basePath: "./resources/symbols"});
    // Load Web Symbols
    map.loadSymbol(symbolId, (error, symbol) => {
        if (error) throw error;

        // Add Web symbols to the map
        map.addSymbol(symbolId, symbol);
        // Set the Web symbol for the specified layer
        map.addLayer({
            "id": "pl@landuse(0_24)",
            "source": "landuse",
            "source-layer": "pl@landuse",
            "type": "line",
            "symbol": symbolId
        });
    });
    See full example code »

Enjoy the result.

Using Custom Web Symbols

First, use the new maplibregl.supermap.WebSymbol().init to initial Web symbol.

Then, use the interface addSymbol to add symbols to the map.

Next, use the interface addLayer to add the layer and set the Web symbol for the layer.

Example code.

                            
    // Configure symbolic resource paths
    new maplibregl.supermap.WebSymbol().init({basePath: "./resources/symbols"});                              
    // Load symbol                          
    map.loadImage("../img/cirecleRed.png", (error, image) => {
        if (error) throw error;

        // Custom symbol image
        const imageId = "cityPoint";
        // Add symbol image to map
        map.addImage(imageId, image); 
        // Custom symbol
        const customPointSymbol = {
            "paint": {
                "icon-translate": [0, 4]
            },
            "layout": {
                "icon-image": imageId,
                "icon-size": 0.1
            }
        };

        const pointSymbolId = "Province_P";
        // Add symbol to map
        map.addSymbol(pointSymbolId, customPointSymbol);
        // Set the point symbol for the specified layer
        map.addLayer({
            "id": "layerId",
            "source": "sourceId",
            "type": "symbol",
            "symbol": symbolId
        });
    });

    // Custom line symbol
    const customLineSymbol = {
        "paint": {
            "line-width": 0.38,
            "line-dasharray": [
                2.5,
                2
            ],
            "line-color": "#AE10FC"
        }
    };
    const lineSymbolId = "Province_P";
    // Add symbol to map
    map.addSymbol(lineSymbolId, customLineSymbol);
    // Set the line symbol for the specified layer
    map.addLayer({
        "id": "Province_L@Population",
        "source": "全国人口密度空间分布图",
        "source-layer": "Province_L@Population",
        "type": "line",
        "symbol": "Province_L"
    });

    // Custom fill symbol in a data-driven manner
    map.addLayer({
        "id": "PopDensity_R@Population",
        "source": "全国人口密度空间分布图",
        "source-layer": "PopDensity_R@Population",
        "type": "fill",
        "symbol": [
        "case",
            ["all", ["<=", ["get", "dMaxZValue"], 70]], "PoPdensity_R_MAX70",
            ["all", [">", ["get", "dMaxZValue"], 70],["<=", ["get", "dMaxZValue"], 140]], "PoPdensity_R_MAX140",
            ["all", [">", ["get", "dMaxZValue"], 210],["<=", ["get", "dMaxZValue"], 280]], "PoPdensity_R_MAX280",
            ["all", [">", ["get", "dMaxZValue"], 350],["<=", ["get", "dMaxZValue"], 420]], "PoPdensity_R_MAX420",
            ["all", [">", ["get", "dMaxZValue"], 490],["<=", ["get", "dMaxZValue"], 560]], "PoPdensity_R_MAX560",
            ["all", [">", ["get", "dMaxZValue"], 640],["<=", ["get", "dMaxZValue"], 700]], "PoPdensity_R_MAX700",
            ["all", [">", ["get", "dMaxZValue"], 770],["<=", ["get", "dMaxZValue"], 1000]], "PoPdensity_R_MAX1000",
            ["all", [">", ["get", "dMaxZValue"], 1000]], "PoPdensity_R_Exceed1000",
            "Country_R"
        ]
    });
    See full example code »

Enjoy the result.

SuperMap iClient for MapLibreGL

Preparing your page

Get MapLibreGL and SuperMap iClient for MapLibreGL

MapLibreGL

SuperMap iClient for MapLibreGL

Import

Import files

npm

Import the CSS files

Modular Development

ES6

CommonJS

AMD

CMD

Package configuration

Creating a map

Map published by SuperMap iServer

Adding controls

Navigation control

Scale control

Using vector tiles

Web Symbol

Import

Import files

Default resources folder path

Customize the resources folder path

npm

Get Started Quickly

Symbol Specification

Using Web Symbols

Using Custom Web Symbols