Tutorial: LiteMap

LiteMap

Overview

LiteMap is a lightweight iShare map that has been designed to be able to be integrated directly into other web applications.

To successfully integrate a LiteMap in a web application or to build a standalone LiteMap you need to include the LiteMap’s JavaScript and CSS files in your HTML page via Astun Services. The files you need to point to are the following:

To load the map in the page, some configuration is needed, based on LiteMap ol-ishare module.

Getting started

The following example shows how to create a standalone LiteMap.

Setup

Start with a minimal HTML file and include the JavaScript and CSS files. Create some basic styles and a map element that will hold your map:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, user-scalable=no initial-scale=1.0">
    <title>LiteMap - Example guide</title>
    <link rel="stylesheet" href="https://ol-ishare.services.astuntechnology.com/v1/apps/lite/lite.css">
    <style type="text/css">
        html,
        body {
            height: 100%;
            padding: 0;
            margin: 0;
            font-family: sans-serif;
            font-size: small;
        }

        #map {
            width: 100%;
            height: 100%;
        }
    </style>
</head>
<body>
    <div id="map"></div>
    <script src="https://ol-ishare.services.astuntechnology.com/v1/apps/lite/lite.js"></script>
    <script>
      // LiteMap code here...
    </script>
</body>
</html>

CSS and JavaScript

The LiteMap CSS and JavaScript included in the page are bundles and include all dependencies such as OpenLayers.

CSS

The file lite.css includes all styles required to display a LiteMap with default styles for controls, etc. — you can override these styles in your own CSS included after lite.css in the page.

<link 
rel="stylesheet"
href="https://ol-ishare.services.astuntechnology.com/v1/apps/lite/lite.css">
JavaScript

The file lite.js exposes a single global variable oli (short for ol-ishare) which exposes the ol-ishare JavaScript API. The constructor for the LiteMap we will use shortly is available at oli.litemap.LiteMap.

The fact that the lite.js bundles its dependencies means embedding a LiteMap is a matter of including a single JS reference. However, it does also mean that the API is limited to that of LiteMap itself — the OpenLayers API isn't exposed. Should you require access to OpenLayers then you've two options:

Create a LiteMap

Configure and load your map with the layers you desire. To create a LiteMap in the #map element replace the empty <script> element in your html page:

<script>
  // LiteMap code here...
</script>

and create a new LiteMap with the following options (as per the documentation):

  • target — the id of an element on the page in which the map will be created (in this case the map element)
  • iShareUrl — the iShare Maps server to load data from (in this case the Astun Technology demo server)
  • profile — the iShare profile (also known as a MapSource) to load. This determines the available layers; to find the available profiles in your iShare instance you can:
    • refer to Studio, or
    • use the GetData.aspx request with the following parameters (for this example we used the Astun Technology demo server to do the request):
      • RequestType=JSON
      • ms=root
      • Type=MapSource
  • layers — the names of any layers to display. To find the available layers of the profile you'd like to load you can:
    • refer to Studio or
    • use the GetData.aspx request with the following parameters (for this case, we used the Astun Technology demo server to do the request):
      • RequestType=JSON
      • ms=mapsources/ol-ishare
      • Type=MapSource
  • view — the initial view of the map in the coordinate system and units used in the profile (here British National Grid in meters). The easting and northing values are x and y coordinates, and zoom is the approximate width of the map (the actual value will depend on the scales set in the base map).
<script>
        //LiteMap MapOptions
        const lite = new oli.litemap.LiteMap({
            target: 'map',
            iShareUrl: 'https://maps.demo.astuntechnology.com/',
            profile: 'mapsources/ol-ishare',
            layers:
                [
                    "nhsdoctors",
                    "nhshospitals",
                    "nhspharmacies",
                    "ward",
                ],
            view: {
                easting: 521000,
                northing: 161000,
                zoom: 10000
            }
        });
        lite.on('load', function (evt) {
        });
    </script>

Additional map options

  • defaultLayers — This can be one of the following values:
    • "all" — Adds all layers that have been configured in the iShare profile to be visible
    • "initial" — Adds all layers in the iShare profile that have given the property initiallyVisible: true
    • "none" — No additional layers are added
  • baseMap — When not set, LiteMap will use the default baseMap specified in the loaded profile. If you would like to use one of the others, you can set the property like so:
    baseMap: "mapsources/base_ospremium_bw"

Layer options

There are additional options that you can use when configuring layers to add to the map:

  • name — The name of the layer you want to add
  • visible — Whether you want the layer to be visible when the map is created (the default option is true)
  • opacity — The value range is between 0 (totally transparent) and 1 (completely opaque), with 1 being the default
Configuration

Note that the declaration of the value in the map's layers option is done differently when you want to configure a layer.

For instance, the following:

layers:
  [
    "nhsdoctors",
    "nhshospitals",
    "nhspharmacies",
    "ward",
  ]

could be replaced with:

layers:
  [
    { name: "nhsdoctors", visible: false },
    "nhshospitals",
    { name: "nhspharmacies", opacity: 0.5 },
    { name: "ward", opacity: 0.3 } 
  ]

And this would result in a map where the doctors layer is not visible by default, the hospitals layer is shown normally, and the pharmacies and ward layers are shown at different levels of transparency.

ⓘ For more examples on LiteMap please visit the ol-ishare examples page.