Skip to main content
Version: Upcoming

Integrate Maps

Admin UI and Form Template Settings​

Admin UI Settings​

The first step is to ensure that the App function flag for enabling the map feature is activated in the Form Template settings within the Admin UI. Without this flag, maps will not be available in the Form Templates.

App function feature mapsDark App function feature maps

Next, define the maps that will be globally available across all Form Templates. These settings are configured in the Admin UI under Core Server > App Settings.

App settings mapsDark App settings maps

For other supported map libraries, such as MapLibreGL and OpenLayers, you can configure their availability as follows:

  • Default Maps: If you want that a specific map is available automatically in all of your Form Templates without further doing, use the prefix hfMap- followed by a unique name (e.g., hfMap-MapLibreBaseMap). If no specific map settings are applied in the Form Template, this map will be displayed automatically (assuming the map feature flag is enabled).
  • Optional Maps: If you do not want a map to appear by default in the Form Templates, omit the hfMap- prefix. Use any unique name for the map (e.g., MapLibreBaseMap). This map will then only be available in a Form Template if it is explicitly configured in the Form Template Variable FormSettings (see below).

For detailed instructions on configuring non-Google Maps options, refer to the sections for MapLibreGL and OpenLayers.

Form Template Settings​

If you prefer to override the default maps defined in the Admin UI or want to include maps that are not globally available, you can specify them in the Form Template settings. Use the template variable MediaSettings and the attribute data-hf-registerMaps to define a comma-separated list of map IDs. These IDs correspond to the App setting IDs configured in the Admin UI.

Only the specified maps will be available in your Form Template, overriding any default maps.

hf-registeredMaps
<var data-hf-name="MediaSettings" data-hf-registerMaps="googleMapsApiKey,hfMap-MapLibreBaseMap,Basemap-OpenLayers">
</var>

In this example, three maps are included in the Form Template:

  1. Google Maps (using the googleMapsApiKey),
  2. MapLibreGL Map (with the name MapLibreBaseMap),
  3. OpenLayers Map (with the name Basemap-OpenLayers).

Integrate Google Maps​

To integrate Google Maps into your Form Templates, simply set the Google Maps API key in the App Settings section of the Admin UI using the googleMapsApiKey.

Integrate Custom Maps with MapLibreGL and OpenLayers​

You can select one of two supported map providers — MapLibreGL or OpenLayers — and configure the map features through a JSON configuration that you define the Admin UI as described above.

  1. MapLibreGL: MapLibreGL is an open-source mapping library based on Mapbox GL JS. It enables high-performance, interactive maps rendered in a browser using WebGL. It is ideal for modern, visually rich web applications and supports a wide range of map styles and customizations.

  2. OpenLayers: OpenLayers is a robust and versatile open-source JavaScript library for displaying maps in web browsers. It supports a wide variety of mapping formats and services, making it an excellent choice for applications with complex geospatial requirements.

JSON Configuration Overview​

Below is the structure of the configuration JSON used to define map settings:

JSON Configuration
{
    "provider": "[MapLibreGL | OpenLayers]",
    "tileType?": "Raster",
    "style?": "https://url-to-map-style", // MapLibreGL
    "styles?": [ // MapLibreGL alternative to style
        {
            "id": "street",
            "style": "https://url-to-styles-file",
            "label": "Street View",
            "default": true
        },
        {
            "id": "satellite",
            "label": "Satellite View",
            "style": "https://url-to-another-styles-file"
        }
    ],
    "capabilities?": { // only for OpenLayers maps; WMTS cappabilities
        "url": "https://url-to-wmts-xml",
        "layers": [
            {
                "id": "street",
                "base": "[Identifier of the base layer]",
                "baseHiDPI": "[Identifier of an alternative high dpi base layer]",
                "overlays": [
                     {
                        "id": "[additional layer identifier]",
                        "opacity": 0.8,
                    } 
                ],
                "label": "[Label for the layer]",
                "default": true
            },
            {
                "id": "hybrid",
                "base": "ortholayer", // Identifier of the base layer
                "overlays": [
                    {
                        "id": "streetname-layer", // Identifier of the additional layer
                        "opacity": 0.8, // opacity of the layer
                    },
                ],
                "label": "Ortho-Satellite",
            },
        ],
        "wfsLayers?": [
            {
                "type": "explicit",
                "name": "workspace:layer-name",
                "url": "https://geoserver.example.com/wfs?service=WFS&request=GetFeature&typename=workspace:layer-name&outputFormat=application/json&srsname=EPSG:3857&bbox=${extent},EPSG:3857",
                "format": "geojson",
                "label": "Feature layer",
                "strategy": "bbox",
                "zoomToLayerOnLoad": true,
                "styleLayer": "HFFormdefinition.CustomCode.styleLayer"
            },
            {
                "type": "auto",
                "capabilitiesUrl": "https://geoserver.example.com/geoserver/workspace/wfs",
                "autoDetectLayers": true,
                "zoomToLayerOnLoad": true,
                "includeLayers": ["workspace:layer-a"],
                "excludeLayers": ["workspace:internal-layer"]
            }
        ],
        "wfsActions?": {
            "styleLayer": "HFFormdefinition.CustomCode.styleLayer",
            "onFeatureClick": "HFFormdefinition.CustomCode.onFeatureClick"
        }
    },
    "apiKey?": "your-api-key",
    "mapConfig?": {
        "center": [15.439504, 47.070713],
        "zoom": 14,
        "pitch": 61,
        "bearing": 172,
        "hash": true
    },
    "geoJSON?": "districts.geojson", // MapLibreGL attachment filename
    "source?": "https://tiles.example.com/{z}/{x}/{y}.png", // MapLibreGL raster source when tileType=Raster
    "features?": {
        "setMarkers": {
            "maxMarkers": 1,
            "callback": "HFFormdefinition.MLMaps.onMarkerSet"
        },
        "toggleLayerVisibility": true, // MapLibreGL
        "directions": true, // MapLibreGL
        "drawing": true, // MapLibreGL
        "html2Canvas": true,
        "createSnapshot": true
    },
    "controls?": {
        "geolocation": true,
        "mapNavigation": true,
        "geocoding": true // MapLibreGL
    },
    "addressMarkers?": [
        "Alexanderplatz 1, 10178 Berlin, Germany",
        "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
        "[... more addresses ...]"
    ],
    "onLoad?": "HFFormdefinition.CustomCode.mapOnLoad",
    "hooks?": {
        "onMapReady": "HFFormdefinition.CustomCode.onMapReady"
    }
}
Note

If for OpenLayers maps in the capabilities section more than one layer is defined, the user can switch between the layers in the apps map. If in MapLibre maps more than one view should be available, define the styles array at the top level of the configuration object (instead of the style property).

Provider-specific behavior matters:

  • controls.geocoding, features.directions, features.drawing and features.toggleLayerVisibility are relevant for MapLibreGL maps.
  • capabilities.layers, capabilities.wfsLayers, capabilities.wfsActions and hooks.onMapReady are relevant for OpenLayers maps.
  • features.createSnapshot is used to enable snapshot creation in connected map workflows and is enabled in the current OpenLayers app settings examples.

OpenLayers WFS Configuration​

OpenLayers maps can combine WMTS basemaps with WFS feature layers. The current configuration model supports two WFS modes:

  1. type: "explicit" for manually configured feature layers with a fully defined GetFeature URL.
  2. type: "auto" for automatic feature layer discovery from a WFS capabilities document.

You can additionally define capabilities.wfsActions.styleLayer and capabilities.wfsActions.onFeatureClick to style loaded features and react to feature clicks. If hooks.onMapReady is set, the callback runs after the first render and after asynchronous WFS loading has finished.

Explicit WFS Layer Example​

Explicit WFS Layer
{
    "provider": "OpenLayers",
    "capabilities": {
        "url": "https://mapsneu.wien.gv.at/basemapneu/1.0.0/WMTSCapabilities.xml",
        "layers": [
            {
                "id": "street",
                "base": "geolandbasemap",
                "baseHiDPI": "bmaphidp",
                "overlays": [],
                "label": "Street",
                "default": true
            }
        ],
        "wfsLayers": [
            {
                "type": "explicit",
                "name": "asfinag-test:testpunkte",
                "url": "https://geoserver.icomedias.com/geoserver/asfinag-test/wfs?service=WFS&version=1.1.0&request=GetFeature&typename=asfinag-test:testpunkte&outputFormat=application/json&srsname=EPSG:3857&bbox=${extent},EPSG:3857",
                "format": "geojson",
                "label": "Testpunkte",
                "strategy": "bbox",
                "zoomToLayerOnLoad": true
            }
        ],
        "wfsActions": {
            "styleLayer": "HFFormdefinition.Playground.customStyleLayer",
            "onFeatureClick": "HFFormdefinition.Playground.customOnFeatureClick"
        }
    },
    "mapConfig": {
        "center": [15.439504, 47.070713],
        "zoom": 14
    },
    "features": {
        "setMarkers": true,
        "createSnapshot": true
    },
    "controls": {
        "geolocation": true,
        "mapNavigation": true
    }
}

Auto-Detected WFS Layers Example​

Auto-Detected WFS Layers
{
    "provider": "OpenLayers",
    "capabilities": {
        "url": "https://mapsneu.wien.gv.at/basemapneu/1.0.0/WMTSCapabilities.xml",
        "layers": [
            {
                "id": "street",
                "base": "geolandbasemap",
                "baseHiDPI": "bmaphidp",
                "overlays": [],
                "label": "Street"
            },
            {
                "id": "hybrid",
                "base": "bmaporthofoto30cm",
                "overlays": [
                    {
                        "id": "bmapoverlay",
                        "opacity": 1
                    }
                ],
                "label": "Hybrid"
            }
        ],
        "wfsLayers": [
            {
                "type": "auto",
                "capabilitiesUrl": "https://geoserver.icomedias.com/geoserver/asfinag-test/wfs",
                "autoDetectLayers": true,
                "zoomToLayerOnLoad": true
            }
        ],
        "wfsActions": {
            "styleLayer": "HFFormdefinition.GeoserverMap.customStyleLayer",
            "onFeatureClick": "HFFormdefinition.GeoserverMap.onFeatureClick"
        }
    },
    "mapConfig": {
        "center": [15.484977, 47.026724],
        "zoom": 17
    },
    "features": {
        "setMarkers": true,
        "createSnapshot": true
    },
    "controls": {
        "geolocation": true,
        "mapNavigation": true
    },
    "hooks": {
        "onMapReady": "HFFormdefinition.GeoserverMap.customOnMapReady"
    }
}

Main MapLibreGL and OpenLayers Options​

mapConfig - required​

Defines the core map settings including center coordinates, zoom level and optional view properties.
How to use:
mapConfig: { center: [15.439504, 47.070713], zoom: 14, pitch: 61, bearing: 172 }
Type: object

provider - required​

Specifies the map provider to use. Supported values are "MapLibreGL" and "OpenLayers".
How to use:
provider: "MapLibreGL"
Type: string

addressMarkers​

Specifies an array of addresses to display with markers on the map.
How to use:
addressMarkers: [ "Alexanderplatz 1, 10178 Berlin, Germany", "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany" ]
Type: array of strings

apiKey​

Optional API key for custom providers or style endpoints, for example some MapLibre-based services.
How to use:
apiKey: "abcd"
Type: string

capabilities​

OpenLayers WMTS and WFS configuration. Use this to define basemap layers and optional WFS feature layers.
How to use:
capabilities: { url: "https://url-to-wmts-xml", layers: [{ id: "street", base: "basemap", label: "Street", default: true }] }
Type: object

controls​

Defines optional map controls such as geolocation, navigation and geocoding.
How to use:
controls: { geolocation: true, mapNavigation: true, geocoding: true }
Type: object

features​

Enables optional map features such as markers, directions, drawing and snapshot handling. Feature availability depends on the selected provider.
How to use:
features: { setMarkers: { maxMarkers: 1, callback: "HFFormdefinition.MLMaps.onMarkerSet" }, toggleLayerVisibility: true, directions: true, drawing: true, createSnapshot: true }
Type: object

geoJSON​

Attachment filename of a GeoJSON document that should be loaded and rendered on a MapLibreGL map.
How to use:
geoJSON: "districts.geojson"
Type: string

hooks​

Additional lifecycle hooks. Currently onMapReady is relevant for OpenLayers maps with asynchronous WFS loading.
How to use:
hooks: { onMapReady: "HFFormdefinition.CustomCode.onMapReady" }
Type: object

onLoad​

Specifies a custom function to be called when the map is loaded.
How to use:
onLoad: "HFFormdefinition.CustomCode.mapOnLoad"
Type: string (function name)

source​

Raster tile URL template for MapLibreGL maps when tileType is set to Raster.
How to use:
source: "https://tiles.example.com/{z}/{x}/{y}.png"
Type: string (URL template)

style​

URL to the MapLibre style document. Use this for single-style MapLibreGL maps.
How to use:
style: "https://api.maptiler.com/maps/topo-v2/style.json?key=XYZ"
Type: string (URL)

styles​

Defines multiple switchable MapLibreGL styles. If this property is used, omit the top-level style property.
How to use:
[ {"id": "street", "style": "https://style-url-1.json", "label": "Street View", "default": true}, {"id": "satellite", "style": "https://style-url-2.json", "label": "Satellite View"}]
Type: array of objects

tileType​

Optional MapLibreGL tile mode. Use this when you want to render a raster tile source instead of a style document.
How to use:
tileType: "Raster"
Type: string

OpenLayers Capabilities Options​

layers.base - required​

WMTS identifier of the basemap layer.
How to use:
base: "geolandbasemap"
Type: string

layers.label - required​

Label shown in the OpenLayers basemap switcher.
How to use:
label: "Hybrid"
Type: string

url - required​

The URL of the WMTS capabilities document.
How to use:
url: "https://url-to-wmts-xml"
Type: string (URL)

layers​

Defines the available OpenLayers basemap layers.
How to use:
{"id":"hybrid","base":"ortholayer","overlays":[{"id":"streetname-layer","opacity":0.8}],"label":"Ortho-Satellite"}
Type: array of objects

layers.baseHiDPI​

Optional alternate WMTS layer identifier for high-DPI tiles.
How to use:
baseHiDPI: "bmaphidp"
Type: string

layers.default​

Marks the initially selected OpenLayers basemap layer.
How to use:
default: true
Type: boolean

layers.id​

Stable identifier of the OpenLayers basemap layer. OLMapControl persists this value as the selected mapLayer.
How to use:
id: "hybrid"
Type: string

layers.overlays​

Additional WMTS overlay layers that are rendered on top of the base layer.
How to use:
overlays: [{"id":"bmapoverlay","opacity":1}]
Type: array of objects

wfsActions​

Global action hooks for OpenLayers WFS layers, for example feature styling and click handling.
How to use:
{"styleLayer":"HFFormdefinition.CustomCode.styleLayer","onFeatureClick":"HFFormdefinition.CustomCode.onFeatureClick"}
Type: object

wfsLayers​

Optional WFS feature layers. Two variants are supported: explicit layers and automatic layer detection from WFS capabilities.
How to use:
{"type":"auto","capabilitiesUrl":"https://example.com/geoserver/wfs","autoDetectLayers":true}
Type: array of objects

Map Configuration Options​

center - required​

Array of two numbers representing [longitude, latitude].
How to use:
center: [15.439504, 47.070713]
Type: array of numbers

zoom - required​

Initial zoom level of the map (0–20).
How to use:
zoom: 14
Type: number

bearing​

Bearing angle of the map in degrees.
How to use:
bearing: 172
Type: number

hash​

Enables URL hash synchronization for the current map position and zoom.
How to use:
hash: true
Type: boolean

pitch​

Pitch angle of the map in degrees.
How to use:
pitch: 61
Type: number

Map Controls Options​

geocoding​

Enables the MapLibreGL geocoder control. This option is relevant for MapLibreGL maps.
How to use:
geocoding: true
Type: boolean

geolocation​

Shows a control for centering the map on the current device location.
How to use:
geolocation: true
Type: boolean

mapNavigation​

Enables the standard navigation controls of the selected provider.
How to use:
mapNavigation: true
Type: boolean

Map Features Options​

createSnapshot​

Controls whether snapshot creation is available for connected map overlays. Enabled by default and used in current OpenLayers appSettings examples.
How to use:
createSnapshot: true
Type: boolean

directions​

Enables or disables MapLibreGL directions support.
How to use:
directions: true
Type: boolean

drawing​

Enables or disables drawing tools on MapLibreGL maps.
How to use:
drawing: true
Type: boolean

html2Canvas​

Controls whether html2canvas is used for connected-map snapshot workflows. Enabled by default.
How to use:
html2Canvas: true
Type: boolean

setMarkers​

Enables the ability for users to set markers on the map. Supported by both MapLibreGL and OpenLayers and can be configured as a boolean or an object.
How to use:
setMarkers: { maxMarkers: 1, callback: "HFFormdefinition.MLMaps.onMarkerSet" }
Type: boolean or object

setMarkers.callback​

Function to call when a marker is set.
How to use:
callback: "HFFormdefinition.MLMaps.onMarkerSet"
Type: string (function name)

setMarkers.maxMarkers​

Maximum number of markers users can set.
How to use:
maxMarkers: 1
Type: number

toggleLayerVisibility​

Enables or disables layer visibility controls for MapLibreGL maps.
How to use:
toggleLayerVisibility: true
Type: boolean

OpenLayers WFS Layer Options​

type - required​

Determines the WFS loading mode. Supported values are explicit and auto.
How to use:
type: "auto"
Type: string

autoDetectLayers​

Enables automatic layer detection from the WFS capabilities document.
How to use:
autoDetectLayers: true
Type: boolean

capabilitiesUrl​

WFS capabilities URL used for automatic layer detection.
How to use:
capabilitiesUrl: "https://geoserver.example.com/geoserver/workspace/wfs"
Type: string (URL)

excludeLayers​

Optional deny-list for auto-detected WFS layers.
How to use:
excludeLayers: ["workspace:internalLayer"]
Type: array of strings

format​

Response format of an explicit WFS layer. Supported values are geojson and gml.
How to use:
format: "geojson"
Type: string

includeLayers​

Optional allow-list for auto-detected WFS layers.
How to use:
includeLayers: ["workspace:layerA", "workspace:layerB"]
Type: array of strings

label​

Optional label for the WFS layer.
How to use:
label: "Testpunkte"
Type: string

name​

Required typename of an explicit WFS layer.
How to use:
name: "asfinag-test:testpunkte"
Type: string

strategy​

Loading strategy of an explicit WFS layer. Supported values are bbox and all.
How to use:
strategy: "bbox"
Type: string

styleLayer​

Optional per-layer styling callback for explicit WFS layers. If omitted, the global capabilities.wfsActions.styleLayer hook is used.
How to use:
styleLayer: "HFFormdefinition.CustomCode.styleLayer"
Type: string (function name)

url​

Full GetFeature URL of an explicit WFS layer. For bbox strategy, the URL can contain the ${extent} placeholder.
How to use:
url: "https://geoserver.example.com/wfs?service=WFS&request=GetFeature&typename=test:layer&outputFormat=application/json&srsname=EPSG:3857&bbox=${extent},EPSG:3857"
Type: string (URL)

zoomToLayerOnLoad​

If set to true, OpenLayers fits the map view to the extent of this WFS layer when the map becomes ready.
How to use:
zoomToLayerOnLoad: true
Type: boolean

OpenLayers WFS Actions Options​

onFeatureClick​

Global click handler executed when a WFS feature is clicked on an OpenLayers map.
How to use:
onFeatureClick: "HFFormdefinition.GeoserverMap.onFeatureClick"
Type: string (function name)

styleLayer​

Global styling callback applied to OpenLayers WFS layers.
How to use:
styleLayer: "HFFormdefinition.GeoserverMap.customStyleLayer"
Type: string (function name)

Map Hooks Options​

onMapReady​

OpenLayers lifecycle hook that runs after the first render and after asynchronous WFS sources finished loading.
How to use:
onMapReady: "HFFormdefinition.GeoserverMap.customOnMapReady"
Type: string (function name)