This article uses Leaflet to convert street addresses into geographical locations. The locations are pinned onto maps that are embedded into records of Kintone Apps.

This example illustrates how the Leaflet library can be used to make a Lunch Map App on Kintone. The App 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 shows up when viewing the Record Details page. There is an option to add a reference point. In this example, the Kintone San Francisco office is the reference point.

This example uses the following libraries

• Leaflet : an open-source JavaScript library for interactive maps.
• LocationIQ : a Maps & Geocoding platform provider.
• OpenStreetMap : a collaborative project to create a free editable map of the world.

The customization displays a map on the header of the Record Details page. The location placed in the Address field is pinned on the map.

The reference point is also pinned, and can be viewed if the address is close, or the map is zoomed out.

Create an App that includes the following fields.

CSS

Set the following URL into the App's JavaScript and CSS Customization settings , under the Upload CSS File for PC option.

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

JavaScript

Set the following URLs into the App's JavaScript and CSS Customization settings , under the Upload JavaScript for PC option.

• https://js.kintone.com/jquery/3.4.1/jquery.min.js
• https://unpkg.com/leaflet@1.5.1/dist/leaflet.js

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

1. Create an account on the LocationIQ Registration Page
2. Navigate to LocationIQ Access Token Create page and create an Access Token. Follow the instructions on Location IQ's docs for more details.

Type the following code into a text editor and save it as a JavaScript file. Upload it to the App's JavaScript and CSS Customization settings . Replace Insert_Access_Token_Here with LocationIQ's access token.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

(function() {
  'use strict';

  function forwardGeocode(name, address, map) {
    // Insert LocationIQ Access Token Below
    var locationIQToken = 'Insert_Access_Token_Here'; // include 'pk.' heading as well
    var encodedAddress = encodeURI(address);
    var URL = 'https://us1.locationiq.com/v1/search.php?key=' + locationIQToken + '&q=' + encodedAddress + '&format=json';
    var method = 'GET';
    kintone.proxy(URL, method, {}, {}, function(response) {
      var response_array = JSON.parse(response);
      // restaurant_GPS contains the GPS coordinates of the restaurant in [Latitude, Longitude] format
      var restaurant_GPS = [parseFloat(response_array[0].lat), parseFloat(response_array[0].lon)];
      var restaurant = L.marker(restaurant_GPS).addTo(map);
      restaurant.bindPopup(name, {autoClose: false}).openPopup();
    });
  }

  kintone.events.on('app.record.detail.show', function(event) {
    // Kintone API
    var record = event.record; // Accesses the Record in the Kintone App
    var address = record.address.value; // Gets data from "address" text field from the Record
    var name = record.place.value; // Gets data from "place" text field from the Record
    var headerSpace = kintone.app.record.getHeaderMenuSpaceElement(); // Fetches the header space
    var mapSpace = document.createElement('div');
    mapSpace.style.height = '300px';
    mapSpace.setAttribute('id', 'kintone');
    headerSpace.appendChild(mapSpace);

    // Leaflet Library
    var referencePointGPS = [37.789808, -122.401767]; // [Latitude, Longitude] GPS coordinates for Kintone Office
    var kintoneMap = L.map('kintone').setView(referencePointGPS, 16);
    // Map Layer with Geographical Features
    var geo_layer = L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
      maxZoom: 18
    });
    // Map Layer with Labels
    var label_layer = L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png', {
      maxZoom: 18,
      zIndex: 10
    });
    geo_layer.addTo(kintoneMap);
    label_layer.addTo(kintoneMap);

    // Reference Point
    // Kintone San Francisco Office is pinned as a reference point
    var reference = L.marker(referencePointGPS).addTo(kintoneMap);
    reference.bindPopup('Kintone USA', {autoClose: false}).openPopup();

    forwardGeocode(name, address, kintoneMap);
  });
})();

Attention

Caution: The order in which JavaScript and CSS are uploaded to an app matters. In this example, ensure that the jQuery and leaflet.js libraries are uploaded before the custom JavaScript file. You can change the order of uploads by clicking and dragging on the arrows for each item on the Upload JavaScript / CSS page.

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

After saving the settings and clicking on Update App, navigate to the Record Details page. A map should be displayed in the header of the Record list.

1

kintone.events.on('app.record.detail.show', function(event) {...});

The event is triggered when the 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.

1

var headerSpace = kintone.app.record.getHeaderMenuSpaceElement();

The getHeaderMenuSpaceElement method fetches the header space in the Record Details view as an element object.

1
2
3
4

var mapSpace = document.createElement('div');
mapSpace.style.height = '300px';
mapSpace.setAttribute('id', 'kintone');
headerSpace.appendChild(mapSpace);

A div element is created to contain the map, and is appended to the Header Menu Space Element. The style.height attribute is set to 300px, a length suitable for displaying the map.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

var kintoneMap = L.map('kintone').setView(referencePointGPS, 16);
// Map Layer with Geographical Features
var geo_layer = L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
  maxZoom: 18
});
// Map Layer with Labels
var label_layer = L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png', {
  maxZoom: 18,
  zIndex: 10
});
geo_layer.addTo(kintoneMap);
label_layer.addTo(kintoneMap);

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. A zoom level is 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. This ensures that labels will be superimposed above the generic geographical features.

1
2
3
4

var referencePointGPS = [37.789808, -122.401767]; // [Latitude, Longitude] GPS coordinates for Kintone Office
// ...
var reference = L.marker(referencePointGPS).addTo(kintoneMap);
reference.bindPopup('Kintone USA', {autoClose: false}).openPopup();

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. The autoClose options ensure that multiple popups can appear simultaneously. openPopup() automatically displays the markers' label by default.

To add a reference point, another variable is created with the value L.marker(geographic_coordinates_variable).addTo(kintoneMap). The geographic_coordinates_variable parameter is set as the GPS coordinates. Write the coordinates in the format of: [Latitude, Longitude] (e.g. [37.789808, -122.401767])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

function forwardGeocode(name, address, map) {
  // Insert LocationIQ Access Token Below
  var locationIQToken = 'Insert_Access_Token_Here'; // include 'pk.' heading as well
  var encodedAddress = encodeURI(address);
  var URL = 'https://us1.locationiq.com/v1/search.php?key=' + locationIQToken + '&q=' + encodedAddress + '&format=json';
  var method = 'GET';
  kintone.proxy(URL, method, {}, {}, function(response) {
    var response_array = JSON.parse(response);
    // restaurant_GPS contains the GPS coordinates of the restaurant in [Latitude, Longitude] format
    var restaurant_GPS = [parseFloat(response_array[0].lat), parseFloat(response_array[0].lon)];
    var restaurant = L.marker(restaurant_GPS).addTo(map);
    restaurant.bindPopup(name, {autoClose: false}).openPopup();
  });
}

Leaflet requires addresses to be geocoded (converted to geographical coordinates) for processing. The LocationIQ API is required to accomplish this conversion. After UTF-8 encoding the address, kintone.proxy() is used to make a GET API call with the address included in the URL.

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

• Leaflet: Docs
• Leaflet: Tutorials
• Leaflet: Plugins
• Search by LocationIQ.com
• LocationIQ: Docs
• LocationIQ: Demo

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)