Display Maps With LeafletJS

Introduction

This article explains how to integrate the LeafletJS library into a Kintone App, allowing users to embed maps into their Record Detail views.


This example will illustrate how the LeafletJS library can be used to make a Lunch Map App on Kintone that keeps track of various restaurant locations around the office. Each record contains information regarding a restaurant. A map displaying the geographical location of the restaurant will show up when viewing the Record Details page. There is an option to add a reference point. In this case, the Kintone San Francisco office is the reference point.


Leaflet is an open-source JavaScript library for interactive maps. Be sure to check Leaflet's license page before using it.


This example will also use services from LocationIQ, a Maps & Geocoding platform provider (Search by LocationIQ.com), and OpenStreetMap, a collaborative project to create a free editable map of the world.


For the full list of services and license information pertaining to this article, view the Licenses section down below.

The Customization Result

The customization will display an OpenStreetMap with the restaurant and reference point locations on the Record Details page.

 

The example below displays the restaurant's (Boba Guys Union Square) location and the office (Kintone USA). The restaurant's name and address are stored under two Text fields named Place and Address respectively.

 

LeafletJS Example 1 Screenshot

If the restaurant and the office locations are farther away than the default zoom level, the default map view will show only the restaurant location. The screenshots below show the result.

The first screenshot shows the default view when the selected location is too far away from the reference point.  

LeafletJS Example 2 Screenshot.

 

The second screenshot shows when the user zooms out. Both the restaurant and reference point are shown on the map.

LeafletJS Example 2 Zoomed Out Screenshot.

Setting up the Customization

To set up this customization on a Kintone App, first, create a LocationIQ account and generate an API Token. Next, modify the customization JavaScript file to include the API Token. Finally, upload the JavaScript file and the required libraries into the Kintone App.

Step 1. Generate a LocationIQ API Token

LocationIQ's Forward Geocoding API will be used to convert street addresses to geographical coordinates.

How to generate a LocationIQ API Token:

  1. Create an account on the LocationIQ Registration Page
  2. Go to LocationIQ Access Token Create page

For more information, refer to the following LocationIQ pages:

Step 2. Create the leaflet-map.js JavaScript file

Use the Access Token and insert it in the leaflet-map.js file below (replace the string Insert_Access_Token_Here )

Step 3. Configure the Kintone App

Field settings of the App

Set the Kintone App field settings as listed below:

Field Type

Field Name

Field Code

Text

Place

Place

Text

Address

Address

JavaScript/CSS settings

This App requires the jQuery and LeafletJS libraries.

Refer to the How to use the CDN article for more information on CDNs provided by Kintone for JavaScript libraries.

 

Under the JavaScript and CSS Customization settings, upload the following files and set the following URL in the Upload JavaScript File for PC and Upload CSS File for PC option.

 

Section

Link/File

Notes

JavaScript for PC

https://js.kintone.com/jquery/3.4.1/jquery.min.js

jQuery library

JavaScript for PC

https://unpkg.com/leaflet@1.5.1/dist/leaflet.js

Leaflet JavaScript library that allows for the creation of maps

JavaScript for PC

leaflet-map.js

JavaScript file
*Note: LocationIQ API Token must be interested before usage

CSS File for PC

https://unpkg.com/leaflet@1.5.1/dist/leaflet.css

The LeafletJS CSS File adds the visual components to the map

 

JavaScript and CSS Customization settings page should look like the following:

 

Customization Setting Page Screenshot.

 

 

The GIF below illustrates the steps described in the tutorial to create the Lunch App with Leaflet customization.

 

Gif going through the this tutorial.

 

Code Explanation

The following section will explain the code in the leaflet-map.js file.
For more information on the Leaflet API references, refer to their documentation.

kintone.events.on Event

The event is triggered when a Record Details view is displayed. The event object is passed as an argument so that details of the record, such as the Address and Place values, can be accessed.
For more information, refer to the Kintone Event Handling API article.

Header Space

Using getHeaderMenuSpaceElement(), this snippet fetches the header space in the Record Detail view as an element object. For more information, refer to the Get Record Header Menu Element section of the Get Record article.

 

Since it is inadvisable to directly edit attributes of the Record Header Menu Space Element, create another div element to contain the map and append it to the Header Menu Space Element. Set the style.height attribute to a length suitable for displaying the map - 300px in this example.

Creating the Map View

The first line in this snippet instantiates a map and attaches it to the header space div by referencing its id 'kintone'.

setView(center, zoom, options) is a method that centers the map view around center, a set of geographical coordinates, with a zoom level specified in the second parameter.

tileLayer(urlTemplate, options) adds raster tiles to the map, i.e. the actual geographical details of the place being mapped. This example uses basemaps from Carto.

The first layer adds generic geographical features such as rivers and roads, while the second adds labels. The maxZoom attribute restricts the maximum zoom-in level for the map view. The zIndex attribute controls the vertical stacking order of the two overlaying map layers, ensuring that labels will be superimposed above the generic geographical features.

Reference Point

L.marker(LatLng) is used to place a pin at the location specified in the LatLng variable.
In this example, the referencePointGPS variable is placed in the L.marker() while holding the geographic coordinates of Kintone USA.

bindPopup() specifies the label of the popup, and the autoClose options ensure that multiple popups can appear simultaneously. Finally, openPopup() automatically displays the marker's label by default.

 

To add a reference point, create another variable with the value L.marker(geographic_coordinates_variable).addTo(kintoneMap) and set geographic_coordinates_variable as either the actual GPS coordinates or a variable holding them. Write the coordinates in the format of: [Latitude, Longitude]
(For example, [37.789808, -122.401767])

forwardGeocode(name, address, map) function

LeafletJS requires addresses to be geocoded (converted to geographical coordinates) for processing. Thus the LocationIQ API is required to accomplish this conversion. After UTF-8 encoding the address, kintone.proxy() is used to make an API call using GET to include the address in the URL. For more information, refer to the Kintone Proxy API article.
*Note: Access token from LocationIQ is required to use their API services.

The kintone.proxy() response is returned as a string, so JSON.parse() is used to convert it into an array of objects. LocationIQ returns the coordinates as strings, so parseFloat() is used to convert them to floating-point numbers.

 

Licenses

Service & License Page

License Type

LeafletJS 2-Clause BSD License
CARTO (formerly CartoDB) Apache License 2.0
LocationIQ Creative Commons Attribution-ShareAlike 2.0 Generic (CC BY-SA 2.0) License
jQuery MIT License
OpenStreetMap Open Data Commons Open Database License (ODbL)

 

Finally

The LeafletJS website provides simple examples to get started and has many Plug-ins to extend Leaflet's functionality. For any trouble handling LeafletJS on Kintone, please post an issue in the Kintone Developer Program community.

For another example of a map integration with Kintone, refer to Display maps with OpenStreetMap article.

Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!