Skip to main content
Version: Upcoming

OLMapControl

The OLMapControl renders an interactive OpenLayers map inside a form. It stores the current map state as JSON and can optionally generate a static image that is used in create view, PDF output and offline mode.

For the structure of the mapConfig object, see the Integrate Maps documentation.

Example
<div
    id="location_map"
    data-hf-control="OLMapControl"
    data-hf-options="{
        label: 'Location map',
        height: 320,
        required: true,
        mapConfig: {
            provider: 'OpenLayers',
            capabilities: {
                url: 'https://maps.example.com/wmts?SERVICE=WMTS&REQUEST=GetCapabilities',
                layers: [
                    {
                        base: 'basemap',
                        overlays: [],
                        label: 'Base map'
                    }
                ]
            },
            mapConfig: {
                center: [15.439504, 47.070713],
                zoom: 10
            },
            controls: {
                mapNavigation: true,
                geolocation: true
            },
            features: {
                toggleLayerVisibility: true,
                setMarkers: false
            }
        },
        staticImage: {
            show: true,
            pdf: 'fullWidth'
        }
    }"
></div>

FormControl Options​

mapConfig - required​

Defines the OpenLayers map configuration. Use this object to provide the provider, layer configuration, center, zoom level, controls and optional map features.
How to use:
mapConfig: {...}
Type: ICustomMLMapConfig

defaultValue​

Provide a default object for the control. A Custom Code function can be used to set defaultValue.
How to use:
defaultValue: { testEntry: 'testValue' }
Type: object | function
Signature: function() => object

doNotCopy​

Set "true" whenever the field should be cleared if the Form is copied.
How to use:
doNotCopy: true
Type: boolean

height​

Defines the map height in pixels. If omitted, the control uses a height of 300 px.
How to use:
height: 300
Type: number

onChanged​

Call a pre-defined JS method when the stored map state changes. The value is provided as a JSON string.
How to use:
onChanged: HFFormdefinition.Namespace.Method
Type: function
Signature: function(value: string) => void

persistent​

It is the value where the "user" sets the initial value of the DataControl to the value of the previous Form item of the current user and overwrites any defaultValue.
How to use:
persistent: 'user'
Type: 'user'

staticImage​

Enables creation of a static JPEG snapshot of the current map view. The snapshot is used for create view, PDF output and as offline fallback.
How to use:
staticImage: {...}
Type: { show: boolean, pdf: 'fullWidth' | 'blockWidth' }

staticImage.pdf​

Controls how the saved static image is rendered in create view and PDF output. Use "fullWidth" for a responsive width or "blockWidth" for a fixed 500 x 300 px block.
How to use:
pdf: 'fullWidth'
Type: 'fullWidth' | 'blockWidth'

staticImage.show​

Set to "true" to store a static image of the current map during save operations.
How to use:
show: true
Type: boolean

Static image and offline mode

​

If staticImage.show is enabled, the control captures the current map view as a JPEG attachment whenever the form is saved. This attachment is used in three places:

  • In create view, where the live map is replaced by the stored image.
  • In PDF output, where staticImage.pdf controls the image size.
  • In offline mode, where the stored image is shown instead of the live map.

If no static image exists and the application is offline, the control displays a placeholder instead of the map.

Stored data

​

The OLMapControl stores the current map center and zoom level as a JSON string:

{
    "id": "location_map",
    "value": "{\"center\":{\"latitude\":47.070713,\"longitude\":15.439504},\"zoom\":10,\"mapLayer\":\"basemap\"}"
}

The JSON stored in the value field has the following structure:

{
    "center": {
        "latitude": 47.070713,
        "longitude": 15.439504
    },
    "zoom": 10,
    "mapLayer": "basemap"
}

Static image shadow field

​

If staticImage.show is enabled, an additional shadow field stores the generated attachment name:

{
    "id": "location_map_HFMapImage",
    "value": "location_map_HFMapImage.jpg"
}