Leaflet Maps

The Logi Info Leaflet Map element, introduced in Logi Info v12.5, allows you to include geo-mapping features in your application, using the Leaflet JavaScript library and a third-party mapping server. This is an alternative to Google Maps and provides an opportunity to combine geographical data with your own information to produce data-driven maps.

About Leaflet Maps

As mentioned above, a Leaflet map uses the Leaflet JavaScript API and third-party mapping servers to produce an interactive geographic maps that can use your data to identify locations and provide other features. The concept is simple: take two different data sources (your data and the map) and combine them into a data-driven map.

A Leaflet map may be an attractive alternative to Google Maps because it works with any Leaflet-compliant map server, as long as you observe their terms of use. At this writing, there are 70+ map servers that work with Leaflet, including:

  • Bing Maps
  • Here Maps
  • MapBox
  • MapQuest
  • OpenStreets
  • Stamen
  • Thunderforest

and many more.

In your Logi Info application, the Leaflet API is implemented as the Leaflet Map element. It makes use of many of the child elements, such as Map Markers and Map Polygons, that are also used for Google Map implementations.
 

The example above shows an OpenStreetMap of the area surrounding Washington, D.C, created using the Leaflet Map element. It's a typical map depicting roads, major land features, and significant points-of-interest. The example also identifies the available optional controls, the scale for indicating map distances, and the cursor shaped that appears when dragging the map within its viewing area.
 

The example above shows the same area, using the Stamen Terrain map.
 

This basic example shows the a MapQuest Satellite map of the same area.

The availability of advanced features, such as Street View, is dependent on the map server.
 

The basic map example above includes a "mashup" of data. When identifying data is fed to the web server, the resulting output can pinpoint locations on the map. The example above shows how a geographic Map Marker is placed on the map to identify a specific location. Map Markers can use the default icon (shown) or a custom image, or a gauge. Optionally, the map can be configured to display a Map MarkerInfo window, containing additional location-specific data, when the marker is clicked.


     

The example shown above includes data-driven, colored regions (in this case, representing postal codes), known as "map polygons", overlaid on a map of Washington, DC. Logi Info can work with GIS boundary data to produce region overlays for states, counties, cities, school districts, and other areas. Like the Map Marker, regions can be clicked to display a pop-up information window with detail data. They're created using the Map Polygons element and are discussed in more detail inMap Polygons.

Similarly, "map polyline" overlays can be plotted from data to show a route, in this case from the Orsay Museum in Paris to the Louvre Museum. They're created using the Map Polylines element; line color, width, and transparency level are all configurable and can be set from data values. They're discussed in more detail in Google Map Polylines.

Leaflet Maps in your Logi application cannot be exported.
 

Google Maps Replacement

If you've implemented Google Maps in your Logi application and wish to convert to using Leaflet Maps, you'll find that most of the Google Map child elements (Map Marker Info, Map Marker Image, etc.) are compatible and can be used with Leaflet Maps without configuration changes. This makes conversion fairly easy. Because they now support both map systems, the names of the child elements have been changed and no longer start with the word "Google".
 

Geocoding

Geographic data for geocoding is not available in Logi Info from Leaflet-compatible map servers. If you want to use the Geocode Columns or Reverse Geocode Columns elements to geocode your location data, you have three choices:

  1. Use Google Maps' services, which you have to license and pay for. For more information, see Google Maps.
  1. Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. Use this connection with the Geocode- and Reverse Geocode Columns elements to access geographic data without engaging with Google. More information is available in Datasource Connections.
     
  2. Create your own geocoding without using the Geocode- and Reverse Geocode Columns elements. This is done by joining your data with other public data that includes geographic lattitude and longitude information. The DevNet Leaflet Maps sample application, for example, joins Starbucks store data with U.S. Postal Service data (which includes geographic information) on postal (Zip) codes to produce the Leaflet map in its Default definition.

About Map Servers

The Leaflet API is designed to work with public map servers. These provide maps as a set of "tiles" which are assembled into a map for display, allowing for dynamic scaling. Your Logi Info app connects to, and sends parameters to, a map server and the server returns appropriate map tiles.
 


The diagram above illustrates how this fits into the Logi application architecture. Typically, the parameters that you send to the map server come from a datasource that your application queries. The results are used in the HTML pages that are output to a browser. Logi Studio elements make the process of connecting to, and communicating with, the map server very easy.
 

Map Service Licensing

Map server providers make their services available to Internet users, sometimes charging a license fee, but more often for free while requiring attribution. You may be required to get an "API Key" from the provider web site. Providers may impose transaction limits or tiered-usage licensing.

 You, as the developer, are responsible for reviewing the current terms of use for the map server you choose to work with, and for taking whatever actions are legally necessary with regard to licensing.

The Leaflet Map Family of Elements

A number of Logi Studio elements make up the family used to create Leaflet Maps. Each element, its function, and its attributes are discussed below:
 

Connection.Leaflet Map - This special type of Connection element is required for communicating with the map server. Like all Connection elements, it resides in your _Settings definition.

See the section below for detailed information about configuring this element.

Leaflet Map - The root element for implementing a Leaflet Map in your report. Attributes include:

  • Height & Width - Specifies optional dimensions, in pixels, for the map.
  • Hide Layer Control - Specifies whether the map Layer selection control is visible on the map or not. The control will appear when there are two or more map layers configured.
  • Hide Scale - Specifies whether the Scale legend is visible on the map or not.
  • Hide Zoom Control - Specifies whether the Zoom control is visible on the map or not.
  • ID - Specifies a unique ID for this element.
  • Security Right ID - When Logi Security is enabled, specifies the Security Right IDs of users who will be able to see this element. Multiple Right IDs, separated by commas may be entered.

Leaflet Map Layer - Required child element that specifies the Connection in the _Settings definition to use to display this layer of map tiles. Multiple Leaflet Map Layer elements may be used and, if so, the Layer Control on the map allows users to switch layers at runtime. This allows you to offer different map types, such as Streets,Terrain, Satellite, etc, from the same map server. Attributes include:

  • Connection ID - (Required) Specifies the ID of a Connection.Leaflet Map element in the _Settings definition.
  • ID - Specifies a unique ID for this element.
  • Map Layer Control Caption - Specifies the identifying text that will appear in the Layer Control for this layer. If left blank, the Connection ID text will appear.
  • Show Layer As Overlay - Specifies whether this layer will be available as an overlay on other layers, allowing layers to the "stacked". If set to True, this layer is displayed in the Layer Control with a checkbox instead of a radio button.

If multiple Leaflet Map Layer elements are used, the first one (top-most in the Element Tree) will be the default layer used when the map is first displayed.

Map Initial View - Optional child element that allows you to set the initial Zoom level and geographic location the map will open to when the page is first displayed. Attributes include:

  • Map Zoom Level - Specifies the resolution of the initial map. Values can range from 0 (the lowest zoom level, in which the entire world appears on the map) to a number reflecting the highest possible zoom level (usually less than 20, varies by map server).
  • Latitude & Longitude - Specifies the positioning values, in the data returned in the associated datalayer, for each marker. If left blank, the defaults are "@Data.Latitude~" and "@Data.Longitude~". Like all tokens, the column names are case-sensitive.

Map Markers - Optional child element that causes Map Markers to appear on the map to pinpoint a location, based on latitude and longitude positioning values. The graphic image for the marker can consist of an image or gauge; a default image is provided. A child datalayer is used to retrieve the geographical data. Attributes include:

  • ID - (Required) Specifies a unique ID for this element.
  • Latitude & Longitude - Specifies the positioning values, in the data returned in the associated datalayer, for each marker. If left blank, the defaults are "@Data.Latitude~" and "@Data.Longitude~". Like all tokens, the column names are case-sensitive.
  • Security Right ID - When Logi Security is enabled, specifies the Security Right IDs of users who will be able to see this element. Multiple Right IDs, separated by commas may be entered..

You can add Action elements below this element so that when a user clicks a marker, an information panel appears or another report is shown.
 

DataLayer - A datalayer element is used to retrieve the data you wish to visualize on the map. As usual, the datalayer can have calculations, aggregations, grouping, etc. to shape the data. Any type of datalayer element can be used.

The schema for data for this purpose should include at least some combination of the following columns (see section About Mapping Data, below):

  • Place Name
  • House Number
  • Street address
  • City
  • State
  • Country
  • Postal Code
     

Geocode Columns - This optional element can be used if your data does not already include geographic coordinates. It accepts address data and, via the Google Map web service, attempts to retrieve latitude and longitude values ("geocoding") for each record in the datalayer. The values are placed into two columns, named "Longitude" and "Latitude", which are added to the datalayer data.

 You must secure a Google Maps API license to use this element or use an alternate geographic data source.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. More information is available in Datasource Connections.

Follow this link for a list of the countries for which Google currently provides geocoding. Other web service brokers also provide geocoding in other countries. Element Attributes include:

  • City Data Column - Name of a datalayer column that has the city name.
  • Connection ID - The ID of the Connection.Google Maps element you added to your _Settings definition. If blank, the first (top-most) element of this type in _Settings will be used by default.
  • Country Data Column - Name of a datalayer column that has the country name.
  • ID - A unique ID for this element.
  • Include Condition - An expression that evaluates to a value of True or False. If the attribute is blank or evaluates to True, geocoding will occur; if the value evaluates to False, the element is skipped.
  • House Number Data Column - The name of a datalayer column that contains the street number.
  • Latitude Column ID & Longitude Column ID - The names of the columns that the web service will add to the datalayer and fill-in with the Latitude and Longitude values. Default column names are "Latitude" and "Longitude".
  • Place Data Column - The name of a datalayer column that has the entire address information or a place name in a single string. Use this attribute when the address data is not broken up into separate columns or when naming a point-of-interest, such as "Washington Monument" or "Grand Canyon". Use of this attribute disables the other location data columns.
  • Postal Code Data Column - The name of a datalayer column that has the postal code data (the "Zip Code" in the U.S.)
  • State Province Data Column - The name of a datalayer column that has the state or province name.
  • Street Data Column - Name of a datalayer column that contains the street name.

Reverse Geocode Columns - This optional element can be used to produce address data from geographic coordinates. Using the Google Maps web service, values returned are put into columns that are added to the datalayer, using these column names:

"StreetNumber", "StreetName", "Locality", "Sublocality", "AreaLevel1",
"AreaLevel2", "AreaLevel3", "Country", "Latitude", "Longitude", and "PostalCode".

 You must secure a Google Maps API license key to use this element or use an alternate geographic data source.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. More information is available in Datasource Connections.

Attributes include:

  • ID - (Required) Specifies a unique ID for this element.
  • Latitude Data Column - (Required) Specifies the name of the existing datalayer column that contains the latitude values.
  • Longitude Data Column - (Required) Specifies the name of the existing datalayer column that contains the longitude values.

Map Marker Image - This optional Map Markers child element is a container for an Image that provides the image for the Map Marker element. If this element is not included in the definition, the default marker image is used. The default image is:

     

Data can be used here in interesting ways. For example, an image caption (image file name) and the image size can be data from the datalayer (their values can be @Data tokens), so locations can be differentiated visually based on their data.

Map Marker Label - This optional Map Markers child element allows you to define a label that will appear under the marker. The label can be styled most easily using CSS.

Map Marker Clustering - When present, this optional Map Markers child element will group markers into clusters according to their distance from a cluster's center. When a marker is added, the marker cluster will find a position in all the clusters or, if it fails to find one, will create a new cluster with the marker. The number of markers in a cluster will be displayed on the cluster marker. Clusters will break apart into individual markers when the mapped is zoomed-in sufficiently. This element has no attributes.

Map Polygons - This optional child element plots overlaid regions onto the map. They can be semi-transparent and have colors that are based on data values. Polygons are plotted from sets of latitude and longitude points. These typically come from a DataLayer.Gpx File or DataLayer.Kml File element.

  • ID - (Required) Specifies a unique ID for this element.
  • Border Color and Thickness - Specifies the polygon border color and thickness in pixels. Default color: Red
  • Border Transparency - Specifies a level of transparency for the border, where 0 = opaque and 15 = completely transparent. Default: 4
  • Fill Color - Specifies the color that fills the polygon interior. Tokens can be used here to set the color based on data. Default: Red
  • Fill Transparency - Specifies a level of transparency for the interior, where 0 = opaque and 15 = completely transparent. Default: 4

You can add Action elements below this element so that when a user clicks a polygon, an information panel appears or another report is displayed.

You can also add a Polygon Color Spectrum Legend element beneath this element. The legend shows a bar displaying a spectrum of colors associated with the polygons and representing the gradation between low and high values in the data. The legend may be displayed to the right or below its parent map.

Map Polylines - Map Polylines are lines plotted onto a map and are optional. They can be semi-transparent and have colors that are based on data values. Polylines are plotted from sets of latitude and longitude points. These typically come from a DataLayer.Gpx File or DataLayer.Kml File element.

  • ID - (Required) A unique ID for this element.
  • Border Color and Thickness - Specifies the polygon border color and thickness in pixels. Default color: Red
  • Border Transparency - Specifies a level of transparency for the border, where 0 = opaque and 15 = completely transparent. Default: 4

You can add Action elements below this element so that when a user clicks a polygon, an information panel appears or another report is shown.

KML Overlay - This optional element allows display of one or more KML files as overlays on the map. When an overlay is used, the boundary viewport details (location and zoom) are set according to the last KML file in the list.

  • ID - (Required) Specifies a unique ID for this element.
  • KML URL - Specifies the URL of a KML or KMZ file. The URL must be publicly-accessible; local intranet URLs will not work.

Action.Map Marker Info - This optional element adds Click event processing to the Map Markers element. When a map marker is clicked, processing flow continues with this element's child elements. Attributes are:

  • ID - (Required) Specifies a unique ID for this element.
  • Security Right ID - When Logi Security is enabled, specifies the Security Right IDs of users who will be able to click a map marker and initiate an action. Multiple Right IDs, separated by commas may be entered.

Map Marker Info - This optional element creates the pop-up "balloon" that appears over the map when a map marker is clicked. A wide variety of elements can be placed as children below this element to display information, including images, links, data, and more. The data from the row associated with the clicked marker is available to the children of this element as @Data tokens.

If you choose to use a SubReport element to display data the pop-up balloon, you must use its Embedded subreport mode.


About Mapping Data

Data used for maps typically contains, at the least, address information. When this information is sent to the map server, the map generated will be scaled to fit the data into the dimensions you set for the map (in the Leaflet Map element).


     

For example, if your data only includes state/province information for a single state, the map generated will be scaled to show as much of the state as necessary to include all of the map markers (above, left). This could be the result, for example, of a SQL query statement that includes a WHERE State = 'MT' clause.

However, if your data includes street address, city, and state/province information, the map generated will be scaled as a street-level map (above, right). This could be the result, for example, of a SQL query statement that includes a WHERE City = 'New York' clause.


     

As shown above, one of the benefits of the interactive nature of these maps is that you can display additional information when the map marker is clicked. Your data might include business intelligence data in addition to the address information such as, for example, revenue figures or employee counts. This data can be displayed, as shown above, in the Info Window that pops up when a marker is clicked. The Info Window can also contain images, gauges, sub-reports, and links, all driven by data.

If your data already includes latitude and longitude positioning data, so much the better. The use of Geocode Column elements to provide that data involves additional requests to the web service and, depending on the map server's usage terms, that could mean exceeding the transaction limit or paying additional transaction fees.

Support for data that includes "MultiGeometry" tags is included.

Connecting to Map Servers

Connections to map servers are made in the _Settings definition, using Connection.Leaflet Map elements, one for each map server:
 

Each map, or "tile", server will have its own connection configuration requirements, and some examples are provided below. Consult the map server's web site for connection details and credentials, if necessary. The Connection.Leaflet Map element's attributes are:
 

Attribute Description

ID

(Required) Specifies a unique element ID.

Tile Server

Specifies the URL of a tile server. For example:  http://my.map.tile.server/{z}/{x}/{y}.png, where:

z  = map zoom level
x, y = map coordinates

The mapping element provides dynamic values for x, y, and z as the user interacts with the map.

There are some pre-defined values, such as "MapQuest", which point to a public MapQuest map server. A pre-defined value may be used in place of the URL value described above.

See the following section for some examples.

Tile Server API Key

Specifies an API key for map servers that require one, for example MapQuest and Thunderforest.

Tile Server Attribution

Specifies an HTML string with server attribution text, for use when the map server requires it for licensing purposes. When a map layer using this connection is displayed the attribute value is displayed in the bottom right corner of the map.

Tile Server Include

Specifies a URL to a JavaScript file that's required by some map servers. Multiple files may be included by delimiting each URL with the pipe "|" symbol.

Tile Server JavaScript

Specifies the JavaScript constructor code for creating map layers when working with certain Leaflet JavaScript plug-ins. For example, to use the official MapQuest Leaflet plug-in and retrieve their satellite map tiles, the value for this attribute should be

new MQ.satelliteLayer()

For some of the pre-defined map servers, such as MapQuest, this value is automatically provided.

Visit http://leafletjs.com/plugins.html to learn more about Leaflet plug-ins.


Attribute Configuration Examples

These are examples of the Connection.Leaflet Map element's attribute values for selected map servers. The servers pre-defined in Logi Info have the word "Easy" in their names; only the required attributes are included in the table below.

Note that these values may be subject to change by the map provider and are only offered here as a courtesy. If in doubt, consult the provider's web site.
 

Map Server Attribute Values

CartoDark

Tile Server: http://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png

MapQuest

Tile Server Include: https://www.mapquestapi.com/sdk/leaflet/v2.2/mq-map.js?key=<yourKey>
Tile Server Javascript: new MQ.mapLayer()

MapQuestEasy

Tile Server: MapQuest
Tile Server API Key: <yourKey>

MapQuestSatellite

Tile Server Include: https://www.mapquestapi.com/sdk/leaflet/v2.2/mq-map.js?key=<yourKey>
Tile Server JavaScript: new MQ.satelliteLayer()

MapQuestSatelliteEasy

Tile Server: MapQuest-Satellite
Tile Server API Key: <yourKey>

OpenStreetMaps

Tile Server: http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
Tile Server Attribution:
Map data &copy; <a href='http://openstreetmap.org'>OpenStreetMap</a> contributors

StamenToner

Tile Server Include: http://maps.stamen.com/js/tile.stamen.js?v1.3.0
Tile Server JavaScript: new L.StamenTileLayer('toner')

StamenTonerEasy

Tile Server: Stamen-Toner

StamenTerrain

Tile Server Include: http://maps.stamen.com/js/tile.stamen.js?v1.3.0
Tile Server JavaScript: new L.StamenTileLayer('terrain')

StamenTerrainEasy

Tile Server: Stamen-Terrain

StamenWatercolor

Tile Server Include: http://maps.stamen.com/js/tile.stamen.js?v1.3.0
Tile Server JavaScript: new L.StamenTileLayer('watercolor')

StamenWatercolorEasy

Tile Server: Stamen-Watercolor

ThunderforestLandscape

Tile Server:
https://{s}.tile.thunderforest.com/landscape/{z}/{x}/{y}.png?apikey=<yourKey>
Tile Server Attribution:
Maps &copy; <a href='http://www.thunderforest.com/'>Thunderforest</a>, Data &copy; <a href='http://www.openstreetmap.org/copyright'>OpenStreetMap contributors</a>

ThunderforestLandscapeEasy

Tile Server: Thunderforest-Landscape
Tile Server API Key: <yourKey>


Refreshing Maps

You may want to refresh your map with new data, either automatically or in response to user input. To do this, you can, of course, use an Action.Report element to refresh the entire report page.

If you just want to refresh the data that drives the map markers, you can make the Leaflet Map element the direct target of an Action.Refresh Element or Refresh Element Timer element.

If you just want to refresh the entire map, but not the entire page, you can place your map in a separate report definition and then include it in your original report as a subreport using the SubReport element:

Make the SubReport element the target of an Action.Refresh Element or Refresh Element Timer element, as shown above. Use Link Parameters under the Action element to pass any necessary values to the Leaflet Map. This is the recommended method of refreshing maps in Dashboard panels.

Special thanks to documentation contributors Michael Kujawski and Jason Scanzoni.