Locator JS Library/SDK
- Utsav Ashish Koju
- Rodolfo Melia
LocatorJS provides a user interface to present end user locations for your organization that can be sources from a DHIS2 Organisation Units or FHIR based facility information. The user interface can be embedded into your public website or web application.
Getting Started
Prerequisite
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.
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:
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: |
|
defaultBaseLayer |
|
|
|
|
zoom |
|
|
|
|