Locator JS library/sdk

LocatorJs provides user interface to map your organisationUnits from DHIS2 or Locations from your fhir server.

Getting Started

Pre-requisite

LocatorJs usages number of external libraries, so please add the following libraries based on your mapping choices

1. Leaflet

Please include following tags in the head section of your web app

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css" integrity="sha256-kLaT2GOSpHechhsozzB+flnD+zUyjE2LlfWPgU04xyI=" crossorigin=""/>
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.7.0/css/all.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-locatecontrol/0.79.0/L.Control.Locate.css"/>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/Leaflet.awesome-markers/2.0.2/leaflet.awesome-markers.css"/>

<script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js" integrity="sha256-WBkoXOwTeyKclOHuWtc+i2uENFpDZ9YPdf5Hf+D7ewM=" crossorigin=""></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-locatecontrol/0.79.0/L.Control.Locate.min.js"></script>

Note: By default leaflet usages OpenStreetMaps, if you want to use google maps please add following additional libraries

<script src="https://unpkg.com/leaflet.gridlayer.googlemutant@latest/dist/Leaflet.GoogleMutant.js"></script>
<script src="https://maps.googleapis.com/maps/api/js?key={API_KEY}&libraries=places&language=fr" async defer></script>

Also please note, for google map you need to generate API KEY and need to replace the {API_KEY} string in script tag above. Please refer to this guide to generate your api key:
Using API Keys | Maps SDK for Android | Google Developers

2. Maplibre

You need to include following library in the head section of your app, if you want to use maplibre-gl to render your map.

<script src='https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js'></script>

Also, maplibre usages mapTilers for its map tiles so we need to create an API KEY in maptiler webpage. You can register an account and get your API KEY from your account.
MapTiler

Installation

There are multiple ways to get started with the library. As we use Vanila JS so you can apply this app into your application with minimum effort and can chose from numbers of possible solutions we have listed below.

1. Using locatorJs.zip

You can extract the zip file into the asset folder of your application and need to specify the source of locator.js inside this folder in the script tag.

2. Using CDN

WIP

3. Using node/npm

WIP

Initializing

Once you have installed the library, you can instantiate the app by providing the HTML Element where you want to render the app and your preferences, which we will discuss below, in JSON format on how you want to render the app.

window.Locator("{HTML_ELEMENT}", {USER_PREFERENCES})

Library Preferences

The user_preferences is a JSON Object, where the user can define their need / preferences as Key/Value pair. The skeleton of the user_preferences look as follow:

{
  ui: {
    showMap: true,
    language: "en"
  },
  data: {
    source: "dhis2",
    baseUrl: "",
    authData: {},
    numberOfOutlets: '20',
    country: 'Kenya',
    countryCode: 'KE',
    distanceRadius: 50000,
    distanceUnit: 'km',
    coordinates: [{latitude}, {longitude}],
    userLocation: false,
  },
  map: {
    lib: "leaflet",
    style: 'osm',
    defaultBaseLayer: '',
    zoomLevel: 13
  }
}

Each preferences are described in detail below:

Option	Description	Default Value	Possible Values	isRequired?
showMap	Switches between map view or List View	true	true: Map View false: List View	No
language	Defines the UI language for all the terms	‘en’		No
source	Defines data source from where we need to fetch the orgunits / location information		fhir dhis2	Yes
baseUrl	Defines the baseURL for the data source			Yes
authData	Authentication information to authorize access to API			Yes
numbersOfOutlets	defines number of outlets we need to fetch and generate in the map	‘20’		No
countryCode	the country code for which we need to fetch the facilities			Yes
country	Name of the country from where we are fetching the facility information			Yes
distanceRadius	The distance around the user location where we will be fetching the facility information			Yes
distanceUnit
coordinates	The default coordinates, other than user location, where we want to center the locator map			Yes
userLocation	If provided and if user allow us to get their location access then it will overwrite the default coordinates	false	true: overwrite default coordinates with user location false: usages default coordinates	No
lib	Defines which maplibrary we will use to render the faciliites	‘leaflet’	leaflet maplibre	Yes
style	Defines which map style we will use		if leaflet: OSM \| google \| esri if maplibre: https://api.maptiler.com/maps/streets/style.json?key={API_KEY}
defaultBaseLayer
zoom