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.
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.
The second screenshot shows when the user zooms out. Both the restaurant and reference point are shown on the map.
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:
- Create an account on the LocationIQ Registration Page
- 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 |
|
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:
Walkthrough Video
The video below illustrates the steps described in the tutorial to create the Lunch App with Leaflet customization.
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
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.