Skip to main content
Version: Upcoming 🦄

Integrate Maps

HybridForms allows you to integrate Custom Maps into your Form Templates. Various libraries can be used to create interactive maps within your Forms. You can configure settings and properties via the Admin UI, while further customizations can be achieved through Custom Code.

Admin UI and Form Template Settings​

Admin UI Settings​

The availability of maps for your Form Templates is managed in the Admin UI. Here, you can define maps that are accessible globally across all Form Templates.

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 hfMaps- followed by a unique name (e.g., hfMaps-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 hfMaps-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 hf-registeredMaps 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]",
    "style?": "https://url-to-map-style",
    "capabilities?": { // only for OpenLayers maps; WMTS cappabilities
        "url": "https://url-to-wmts-xml",
        "layers": [
            {
                "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]",
            },
            {
                "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",
            },
        ],
    },
    "mapConfig?": {
        "style": "https://url-to-styles-file", // only for MapLibre maps
        "styles?": [
              {
            "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"
            }
        ], // only for MapLibre maps
        "center": [15.439504, 47.070713],
        "zoom": 14,
        "pitch": 61,
        "bearing": 172
    },
    "features?": {
        "setMarkers": true,
        "setMarkers": {
            "maxMarkers": 1,
            "callback": "HFFormdefinition.MLMaps.onMarkerSet"
        },
        "toggleLayerVisibility": true,
        "directions": true,
        "drawing": true
    },
    "controls?": {
        "geolocation": true,
        "mapNavigation": true
    },
    "addressMarkers?": [
        "Alexanderplatz 1, 10178 Berlin, Germany",
        "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
        "[... more addresses ...]"
    ],
    "onLoad?": "HFFormdefinition.CustomCode.mapOnLoad"
}
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 (instead of the style-property) in the mapConfig section.

Main MapLibreGL and OpenLayers Options​

mapConfig - required​

Defines the core map settings including style, center coordinates, zoom level, pitch, and bearing. If not specified, the map will set default values.
How to use:
mapConfig: { style: "mapbox://styles/mapbox/streets-v11", 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

capabilities​

Configurations for WMTS capabilities. Applicable only when the provider is "OpenLayers".
How to use:
capabilities: { url: "https://url-to-wmts-xml", hiDPILayer: "bmaphidp", defaultLayer: "basemap" }
Type: object

controls​

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

features​

Enables additional features such as markers, drawing, directions and layer visibility toggling.
How to use:
features: { setMarkers: { maxMarkers: 1, callback: "HFFormdefinition.MLMaps.onMarkerSet" }, toggleLayerVisibility: true, directions: true, drawing: true }
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)

style​

URL to the map style (e.g., MapTiler or custom Mapbox style). Defaults to OpenStreetMap if not specified.
How to use:
style: "https://api.maptiler.com/maps/topo-v2/style.json?key=XYZ"
Type: string (URL)

styles​

To add different map views to the user, define different style objects (containing the url, an id and a label for the view and optionally a default flag). If this property is defined omit the style property.
How to use:
[ {"id": "street", "style": "https://style-url-1.json", "label": "Street View", "default": true}, {"id": "street", "style": "https://style-url-2.json", "label": "Street View", "default": true}]
Type: array of objects

OpenLayers Capabilities Options​

url - required​

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

layers​

The layer name for high-DPI displays.
How to use:
{"base":"ortholayer","overlays":[{"id":"streetname-layer","opacity":0.8}],"label":"Ortho-Satellite"}
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

style - required​

Map style URL, e.g., a Mapbox or custom style.
How to use:
style: "mapbox://styles/mapbox/streets-v11"
Type: string (URL)

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

pitch​

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

Map Features Options​

directions​

Enables or disables the directions functionality.
How to use:
directions: true
Type: boolean

drawing​

Enables or disables drawing tools on the map.
How to use:
drawing: true
Type: boolean

setMarkers​

Enables the ability for users to set markers on the map. Can be a boolean or an object for more control.
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 the ability to toggle layer visibility.
How to use:
toggleLayerVisibility: true
Type: boolean