Qi-map NPM | npm.io

QI-Map

A feature rich Map library built on OpenLayer 6 to generalise generic Map features for easy use in multiple projects.

Prerequisite

Include the library in your HTML
countryConfig.json - A basic JSON would look like following -

  {
    "SG": {
      "center": [
        1.155209e7,
        151997.9
      ],
      "minZoom": 5,
      "zoom": 12,
      "maxZoom": 25
    },
    "TH": {
        // similar approach
    }
  }

Features and Usage

You need a maintain an HTML block with unique id e.g

<div class="qiMap">
  <div id="mapContainer" class="zdown"></div>
</div>

You need to initialise the library by -

var qiMap = new QIMap({
      containerId: "mapPublicHome",
      baseLayer: ['OSM', 'GOOGLE'],
      googleApiKey: "<YOUR_GOOGLE_MAP_API_KEY>",
      currentCountry: {
        "center": [
          1.155209e7,
          151997.9
        ],
        "minZoom": 5,
        "zoom": 12,
        "maxZoom": 25
      }
      liveTrackCheckDurationInMS: 10 * 60 * 1000,
      dataFormat: {
        lat: "lat",
        lon: "lon",
        time: "recorded_on"
      }
    });

Please Note : mapContainer refers to the id as referred to previous block.

By default it will create TWO instance of base layers i.e OSM and GOOGLE. There is a layer switcher section in the map which will show the base layers.

If want to work with only OSM / GOOGLE as a base layer, you need to pass that as an argument e.g. OSM.

You can enable OSM and GOOGLE both layers using the mentioned example above ['OSM', 'GOOGLE'].

Please Note googleApiKey attribute is required only when you specify GOOGLE as your baseLayer.

liveTrackCheckDurationInMS: If the last received data point is within the check duration time (e.g : 10 60 1000ms means 10 minutes), code will check for new data points untill it's maximum number of try exceeds.

dataFormat: Here user can define their data format before initiating the map. default dataFormat:

dataFormat = {
  lat: "lat",
  lon: "lon",
  time: "time"
}

To initialise and create the map -

qiMap.createMap();

Please Note: To seamlessly work with Google maps, you need to include maps.googleapis.com maps api

To add custom base layer(s) - Maintain an array variables like following to add a custom base layer -

var customBaseLayers = [
        {
        name: "SG_MAP",
        layerType: "Tile",
        title: "QI Map [SG]",
        type: "base",
        visible: false,
        sourceType: "TileWMS",
        source: {
            url: qiMap.geoserverHost2 + "/geoserver/gwc/service/wms/",
            serverType: "geoserver",
            opacity: 1.0,
            params: {
            LAYERS: "SGP_MAP:SGP_MAP_OPENLAYERS_NOPOI",
            format: "image/png",
            VERSION: "1.1.1",
            CRS: "EPSG:4326"
            },
            hidpi: false
            }
        }
    ];

This object is for representational purpose only, and depends on the kind of base layers you're using.

To add the custom layer run-

qiMap.addLayer(customBaseLayers, {addInLayerSwitcher: true/false});

customBaseLayers : The base layer array maintained as shown.

addInLayerSwitcher (Object) : Whether newly added layer will be part of layer switcher block or not

To Add a layer

Pass the layer object like following to add a layer on the map

 qiMap.addLayer({ name: "layer" });

To Remove a layer

To remove a layer, we need to pass the layer name, and an optional parameter specifying the attribute name (default is name). This parameter comes from the payload when we add a layer.

 qiMap.removeLayer("layer", "name");

Here, name is the attribute name.

To Toggle a layer visibility

To toggle a layer visibility from visible to hidden or vice versa -

  qiMap.toggleLayer(:layer_name)

Here, layer_name defines the layer already existing on the map.

To Show a hidden layer

To show a hidden layer -

  qiMap.showLayer(:layer_name)

Here, layer_name defines the layer already existing on the map.

To Hide a layer

To hide a layer -

  qiMap.hideLayer(:layer_name)

Here, layer_name defines the layer already existing on the map.

To Add a Feature

You can add one or multiple features of type line or point. If you wish to show a tooltip, you may send tooltip attribute with showOn attribute featuring "click" or "hover", along with content to show.

Here, in data property you can pass objects with style attribute which will be applied on the coordinates along with it. In case the style is not specified, it will take value of options attribute.

  qiMap.addLayer({ name: "point-layer" }); //Optional: If you have already created the layer
  qiMap.addFeatures({
    layerName: "point-layer",
    type: "point",
    data: [
      {
        style: {
          circleColor: "#9ACB3F",
          circleWidth: 7,
          hasBearing: true,
          bearingProp: 'bearing'
        },
        coordinates: [{
          lon: 103.8484932,
          lat: 1.287768
        }]
      }
    ],
    options: { // Optional: If you have already specified the style in data property
      circleColor: "#fc3903",
      circleWidth: 7
    },
    tooltip: {
      showOn: "click",
      dynamicContent: () => {
        return "<strong>I'm a Marker!</strong>";
      }
    }
  });

hasBearing option signifies whether the feature needs to be roated to specific angle or not. The bearingProp signifies the attribute name of passed data object which signifies the rotation value.

To pass an image, options or style attribute will be like following -

    ....
    options: { 
      image: {
          imagePath: "<:Image_URL>",
          imageAnchor: [0.5, 0.5],
          imageSize: [24, 24]
        }
    }
    ...

To Draw a track By passing only the datapoints you can draw a line track

var sampleData = [
  {
    "id": 1626283020,
    "lat": 1.37244941,
    "lon": 103.75190784,
    "speed": 86.4,
    "drive_id": "2zd7rxgyxt87rskox3hah7xm",
    "bearing": 204,
    "recorded_on": "2019-08-09T10:07:17"
  },
  more ...
];

qiMap.drawTrack({dataPoints: sampleData})

Attributes you can pass to draw a track

qiMap.drawTrack({
  dataPoints: array, ( passs data points to plot )
  layerName: string, ( exisiting layer name )
  trackStyle: string, ( line/point, default: line )
  live: boolean, ( default: false )
  clickHandler: function, ( user define function )
  options: object,
  tooltip: {
    showOn: string, ( hover/click )
    content: string, ( static content)
    dynamicContent: function(attr[]) ( lat: attr[0], long: attr[1] )
  }
})

To work on features that's supported by Openlayers not by our library

Please call, following method to get the open layer reference object