GET Export Report Map Format

Abstract

Description of the Map export format of the GET Export Report API.

Table of Contents

The map format writes an HTML document to the HTTP response body with an embedded Leaflet map which displays the GeoJSON results from the GeoJSON format. Like the GeoJSON format, the map format is only available if the report has a valid <geojson> element and the base table primaryKeyColumns attribute is specified.

Format Parameter: map

Response Content-Type: text/html

Pull Reports™ Standard Edition Format

This format is only available under the Pull Reports™ Standard Edition license. To evaluate this format with a Pull Reports™ Community Edition license, enable evaluation mode.

OK Response

Status Code: 200

Map format responses without error are valid HTML5 documents into which the output of the GeoJSON format is written as a JavaScript variable and displayed within an embedded Leaflet map.

Error Response

Status Code: 400 and 500

Map format responses with error have the same structure as Error responses from the html format.

Decorating the returned HTML

See the administration chapter for information on how to decorate (wrap) the exported HTML with additional HTML elements such as a custom header and footer.

Customizing the Mapper

In order to control the behavior of the map format's embedded Leaflet mapper, decorate the returned HTML and define an global JavaScript variable within the <head> of the DOM named mapConfig. mapConfig must be a JavaScript object with one or more of the properties below. The map format JavaScript will detect this variable and use it during initialization of the Leaflet Mapper.

`mapConfig` Object Properties

initCallback

A JavaScript function to be invoked after map initialization. The arguments to the function are:

map: The Leaflet map.
geoJsonLayer: The Leaflet markercluster layer which contains the GeoJSON Layer which in turn contains the GeoJSON result of the Export REST API, geojson format.

geoJsonOptions

A JavaScript object to be passed to the Leaflet GeoJSON layer upon construction. See the Leaflet GeoJSON documentation for a complete list of configuration options.

If not specified, Pull Reports™ will set the following default GeoJSON layer option values:

onEachFeature: Set to a function which binds a Leaflet popup to the layer for each feature. The content of the popup is a two column table of GeoJSON feature property names to values. The property names and values are the exported <column>s of the report's base table plus any table in a to-one descendant <relationship> to the base table.

options

A JavaScript object to be passed to the Leaflet map upon construction. See the Leaflet map options documentation for a complete list of configuration options.

If not specified, Pull Reports™ will set the following default map option values:

center: Set to the geographic center of the lower 48 United States.
layers: Set to an array with a single Open Street Map base layer.
zoom: Set to 4

Map customization example

This example customizes the map format Leaflet mapper by adding a Leaflet Layers control to the map with the ability to toggle between two base tile layers and toggle the visibility of the report's GeoJSON layer. The example uses the Servlet include technique to include custom JavaScript within the returned HTML <head> element.

To begin, create a text document called mapConfig.html within the installation WAR's WEB-INF/context directory. This document will define the mapConfig global variable within an HTML <script> element. The example below uses the mapConfig options and initCallback properties to set the default map layers and add a Leaflet Layers control respectively.

<script>
    var baseLayers = [];
    baseLayers['ESRI World Topo'] = 
        L.tileLayer('http://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}', {
        attribution: 'Tiles &copy; Esri &mdash; Esri, DeLorme, NAVTEQ, TomTom, Intermap, iPC, USGS, FAO, NPS, NRCAN, GeoBase, Kadaster NL, Ordnance Survey, Esri Japan, METI, Esri China (Hong Kong), and the GIS User Community'
        ,maxZoom:18
    });
    baseLayers['Open Street Map'] = 
        L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
        attribution: 'Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors'
        ,maxZoom: 18
    });
    
    function initializeMap(map,geojsonLayer){
        L.control.layers(baseLayers, {'My Report Data':geojsonLayer}).addTo(map);
    }

    var mapConfig = {
        options: {
            layers:[baseLayers['Open Street Map']]
        }
        ,initCallback:initializeMap
    };
</script>

To include this file within the map format HTML <head> element, set the export.report.include.map.head.end configuration property in pullreports.properties to the WAR-relative location of mapConfig.html like so:

export.report.include.map.head.end=/WEB-INF/content/mapConfig.html

Pull Reports™ will then insert the mapConfig.html fragment into every map format response and use the mapConfig variable to customize the Leaflet map.