Map | X4Documentation

The <Map> control can be used to integrate maps from various vendors, including Google Maps and OpenStreetMap, into X4 Web Apps. You can view geodata, find locations, and look up routes.

Instructions for use

A <Map> control is created with the <Map> element. The element can only be used in the layout of a Detail Component.

XML

<Map>
...
</Map>

The <Map> element can contain the following elements:

<Geolocation>
<Markers>
<Routing>
<Search>
<SelectedLocationMarkers>
<SingleMarker

<Map> controls can be used in all available layout types: For more information, see Layouts.

Attribute

Note:

There are a number of default attributes that can be set for all controls. For more information about the default attributes, see Default attributes.

In addition to the default attributes, you can define the following attributes for <Map> controls.

Attribute	Description
`apiKey`	Defines the API key if required by the vendor. Possible values: API key Note: Using OpenStreetMap as the map provider does not require an API key. If an API key is entered when using OpenStreetMap, the API key is ignored. When using Google Maps as a map provider, the following APIs must be enabled: Maps JS API Locations (for search and route calculation) Directions (for route calculation) The `apiKey` attribute overwrites the `MapAPIKey` element in the Web App configuration `.wac`.
`initialPointLongitude`	Defines the longitude on which the map should be centered when it is loaded. Data binding with constant values possible Possible values: Longitude in degrees with decimal places (e.g. `6.75000`)
`initialPointLatitude`	Defines the longitude on which the map should be centered when it is loaded. Data binding with constant values possible Possible values: Latitude in degrees with decimal places (e.g. `50.41871`)
`restrictScrolling`	Restrict scrolling behavior in maps Possible values: `true` (default): When scrolling with your mouse or finger on mobile devices, a message informing about alternative scrolling is displayed `false`: Alternative scrolling behavior is disabled.
`satelliteView`	Defines if the satellite view of the map is activated. Possible values: `true` `false` (default) The satellite view cannot be used if OpenStreetMap is used as map vendor.
`selectedIndex`	Selected index The `selectedIndex` attribute inherits the `index` value of a single marker (`SingleMarker`) or a marker group `markers` (`Markers`) as soon as they are selected. Possible values: String binding
`vendor`	Required Specifies the map provider. Possible values: `Bing` `Google` `OpenStreetMap` Note when selecting Bing as the card provider: The use of Bing Maps will no longer be possible in the future. The reason is the termination of the underlying Microsoft API (May 2024, full shutdown for Free Tier from June 2025). As an alternative, Azure Maps will be available as a new map provider in an upcoming X4 BPMS version.
`zoomLevel`	Specifies the initial zoom level of the map. The values give an approximate indication of the meters shown on the map. Please note that there may be deviations in the scale bar, as the scale changes depending on the distance from the equator. Possible values: `10` `25` `50` `100` `250` `500` `750` `1000` `2000` `5000` `10000` `25000` `50000` `100000` `2500000` `5000000`

Use the user's location (`<Geolocation>` element)

Within the <Map> element, the <Geolocation> element can be used to query the user's location. If the <Geolocation> element is used, a button is displayed on the map. By clicking on the button, the user's location is queried and marked on the map.

The <Geolocation/> element can have the following attributes:

Attribute	Description
`iconUrl`	Path to the graphic file to be used as an icon for the markers. The graphic file must be located in the `Resources` folder just below the Web App Project. Path information relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`iconHorizontalPosition`	Horizontal position of the icon
`iconVerticalPosition`	Vertical position of the icon

Attribute

Description

iconUrl

Path to the graphic file to be used as an icon for the markers. The graphic file must be located in the Resources folder just below the Web App Project. Path information relative to the Resources folder.

Data binding possible

Possible values:

String (URI)

iconHorizontalPosition

Horizontal position of the icon

iconVerticalPosition

Vertical position of the icon

Marker group (`<Markers/>` element)

To display multiple markers in a map control, the <Markers/> element is used within <Map> and, if necessary, after <Search/> and <Routing/>.

XML

<Map>
	...
	<Markers/>
</Map>

Note:

If several markers are used, the respective icons are displayed in the corresponding order. The first marker group is displayed on the bottom level, the last on the top level. As a result, the icons of the last marker group may overlay the icons of the first markers listed.

The <Markers/> element can have the following attributes:

Attribute	Description
`cluster`	Defines if markers are grouped if they are very close together on the map. Possible values: `true` `false` (default) `cluster` and `number` cannot be used at the same time!
`componentName`	Specifies the name of the component for internal navigation. Possible values: String (name of a component) `componentName` and `externalLink` cannot be used at the same time!
`data`	Required Defines which data is used for the marker set. Data binding required Possible values: Expression for data binding
`description`	Defines the description of the markers. Data binding required Possible values: Data binding expression relative to the expression in `data`
`externalLink`	Specifies the link that appears in the marker pop-up. Data binding required Possible values: Data binding expression relative to the expression in `data` `componentName` and `externalLink` cannot be used at the same time!
`externalLinkTarget`	Specifies whether the link (`externalLink`) opens on the same tab or a new tab. Possible values: `same`: The link opens in the same tab. `new`: The link opens in a new tab.
`iconHorizontalPosition`	Defines the horizontal position of the icon relative to the entered coordinates. This is particularly important at low zoom levels: The icon is displayed to the left/right of the actual coordinate. Possible values: `left`: The icon is to the left of the coordinate. `center` (default): The icon is on the coordinate. `right`: The icon is to the right of the coordinate.
`iconUrl`	Path to the graphic file to be used as an icon for the markers. The graphic file must be located in the `Resources` folder just below the Web App Project. Path information relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`iconVerticalPosition`	Defines the vertical position of the icon relative to the entered coordinates. This is particularly important at low zoom levels: Here the icon is displayed above/below the actual coordinate. Possible values: `top`: The icon is above the coordinate. `center` (default): The icon is on the coordinate. `bottom`: The icon is below the coordinate.
`index`	Index of the marker set Data binding possible Possible values: Any string
`latitude`	Required if `searchString` is not used. Defines the latitude of a marker. Data binding possible Possible values: Data binding expression relative to the expression in `data`
`longitude`	Required if `searchString` is not used. Defines the longitude of a marker. Data binding possible Possible values: Data binding expression relative to the expression in `data`
`name`	Defines the name of the markers. Data binding required Possible values: Data binding expression relative to the expression in `data`
`navigationDisplayName`	Defines the text that appears in the marker pop-up instead of an external link or component name. Data binding possible Possible values: String including spaces
`number`	Defines if the markers are numbered. Possible values: `true` `false` (default) `cluster` and `number` cannot be used at the same time!
`searchString`	Required if `latitude`/`longitude` is not used. Address line to search for selected services from the card vendor. Data binding possible Possible values: String for searching a service, such as a `restaurant` Note: This attribute cannot be used at the same time as the `latitude`/`longitude` attributes. Markers that are searched for based on place names (`searchString`) may be delayed or incomplete for multiple records due to timeouts at the map provider. Preferably use geo-coordinates to display all markers reliably and quickly.
`textHorizontalPosition`	Defines the horizontal position of the numbering relative to the given coordinates. Possible values: `left`: Numbering is to the left of the coordinate (default). `center`: Numbering is on the coordinate. `right` (default): Numbering is to the right of the coordinate. Bing Maps automatically positions the numbering. Therefore, this function has no effect on Bing Maps.
`textVerticalPosition`	Defines the vertical position of the numbering relative to the given coordinates. Possible values: `top`: Numbering is above the coordinate (default). `center` (default): Numbering is on the coordinate. `bottom`: Numbering is below the coordinate. Bing Maps automatically positions the numbering. Therefore, this function has no effect on Bing Maps.

Route calculation (`<Routing/>` element)

To allow a Web App user to calculate a route between two locations in the Map control, the <Routing/> element is used within <Map> and, if necessary, after <Search/>.

XML

<Map ...>
	<Routing/>
</Map>

The <Routing/> element can have the following attributes:

Attribute	Description
`destinationIconHorizontalPosition`	Defines the horizontal position of the target icon relative to the coordinates searched for. Possible values: `left`: The icon is to the left of the coordinate. `center` (default): The icon is on the coordinate. `right`: The icon is to the right of the coordinate.
`destinationIconUrl`	Path to the graphic file to be used as an icon for the target point. The icon marks the target point of the route. The graphic file must be located in the `Resources` folder just below the Web App Project. The path is specified relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`destinationIconVerticalPosition`	Defines the vertical position of the target icon relative to the coordinates searched for. Possible values: `top`: The icon is above the coordinate. `center` (default): The icon is on the coordinate. `bottom`: The icon is below the coordinate.
`startIconHorizontalPosition`	Defines the horizontal position of the start icon relative to the coordinates searched for. Possible values: `left`: The icon is to the left of the coordinate. `center` (default): The icon is on the coordinate. `right`: The icon is to the right of the coordinate.
`startIconUrl`	Path to the graphic file to be used as an icon for the starting point. The icon marks the starting point of the route. The graphic file must be located in the `Resources` folder just below the Web App Project. The path is specified relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`startIconVerticalPosition`	Defines the vertical position of the start icon relative to the coordinates searched for. Possible values: `top`: The icon is above the coordinate. `center` (default): The icon is on the coordinate. `bottom`: The icon is below the coordinate.

Search function (`<Search/>` element)

To allow users to search for locations in the <Map> control, the <Search/> element is used within <Map>.

XML

<Map>
	<Search/>
</Map>

The <Search/> element can have the following attributes:

Attribute	Description
`searchIconHorizontalPosition`	Defines the horizontal position of the icon relative to the coordinates searched for. Possible values: `left`: The icon is to the left of the coordinate. `center` (default): The icon is on the coordinate. `right`: The icon is to the right of the coordinate.
`searchIconUrl`	Path to the graphic file to be used as an icon. The icon is used to highlight the search result. The graphic file must be located in the `Resources` folder just below the Web App Project. The path is specified relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`searchIconVerticalPosition`	Defines the vertical position of the icon relative to the coordinates searched for. Possible values: `top`: The icon is above the coordinate. `center` (default): The icon is on the coordinate. `bottom`: The icon is below the coordinate.

Attribute

Description

searchIconHorizontalPosition

Defines the horizontal position of the icon relative to the coordinates searched for.

Possible values:

left: The icon is to the left of the coordinate.
center (default): The icon is on the coordinate.
right: The icon is to the right of the coordinate.

searchIconUrl

Path to the graphic file to be used as an icon. The icon is used to highlight the search result. The graphic file must be located in the Resources folder just below the Web App Project. The path is specified relative to the Resources folder.

Data binding possible

Possible values:

String (URI)

searchIconVerticalPosition

Defines the vertical position of the icon relative to the coordinates searched for.

Possible values:

top: The icon is above the coordinate.
center (default): The icon is on the coordinate.
bottom: The icon is below the coordinate.

Setting a marker by clicking in the map (`<SelectedLocationMarker>` element)

The <SelectedLocationMarker> element allows the user of a Web App to set a marker by clicking on a specific location on the map. The location marked by the user can be further processed by a Technical Process.

XML

<Map>
	...
	<SelectedLocationMarker .../>
</Map>

The <SelectedLocationMarker/> element can have the following attributes:

Attribute	Description
`description`	Specifies the description of the marker. Data binding possible Possible values: Any string including spaces
`longitude`	Required Longitude of the marker Data binding possible Possible values: Property A property must be set as the value for the attribute.
`latitude`	Required The latitude of the marker Data binding possible Possible values: Property A property must be set as the value for the attribute.
`iconUrl`	Path to the graphic file to be used as an icon. The icon marks the selected location. The graphic file must be located in the `Resources` folder just below the Web App Project. The path is specified relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`name`	Specifies the name of the marker. Data binding possible Possible values: Any string of alphanumeric characters

Simple marker (`<SingleMarker/>` element)

To display a single marker in a Map control, the <SingleMarker/> element is used within <Map> and, if necessary, after <Search/> and <Routing/>.

XML

<Map>
	...
	<SingleMarker/>
</Map>

The <SingleMarker/> element can have the following attributes:

Attribute	Description
`componentName`	Specifies the name of the component for internal navigation. Possible values: String (name of a component)
`description`	Specifies the description of the marker. Data binding possible Possible values: String including spaces
`externalLink`	Specifies the link that appears in the marker pop-up. Data binding possible Possible values: String (URL)
`externalLinkTarget`	Specifies whether the link (`externalLink`) opens on the same tab or a new tab. Possible values: `same`: The link opens in the same tab. `new`: The link opens in a new tab.
`iconHorizontalPosition`	Defines the horizontal position of the icon relative to the entered coordinates. Possible values: `left`: The icon is to the left of the coordinate. `center` (default): The icon is on the coordinate. `right`: The icon is to the right of the coordinate.
`iconUrl`	Path to the graphic file to be used as an icon for the marker. The graphic file must be located in the `Resources` folder just below the Web App Project. The path is specified relative to the `Resources` folder. Data binding possible Possible values: String (URI)
`iconVerticalPosition`	Defines the vertical position of the icon relative to the entered coordinates. Possible values: `top`: The icon is above the coordinate. `center` (default): The icon is on the coordinate. `bottom`: The icon is below the coordinate.
`index`	Index of the marker Data binding possible Possible values: Any string
`latitude`	Required if `searchString` is not used. Specifies the latitude of the marker. Data binding possible Possible values: Latitude in degrees with decimal places (e.g. `50.41871`) This attribute cannot be used at the same time as `searchString`.
`longitude`	Required if `searchString` is not used. Specifies the longitude of the marker. Data binding possible Possible values: Longitude in degrees with decimal places (e.g. `6.75000`) This attribute cannot be used at the same time as `searchString`.
`name`	Specifies the name of the marker. Data binding possible Possible values: String of alphanumeric characters
`navigationDisplayName`	Specifies the text that appears in the marker's pop-up instead of an external link or component name. Data binding possible Possible values: String including spaces
`searchString`	Required if `latitude`/`longitude` is not used. Address line to search for selected services from the card vendor. Data binding possible Possible values: String for searching a service, such as a `restaurant` This attribute cannot be used at the same time as the `latitude`/`longitude` attributes.

Actions

The following action is available for <Map> controls. For more information about actions, see Actions.

`<SelectAction>`

You can insert the Select action using the <SelectAction/> element withinSingleMarker>, <Markers>, or <SelectedLocationMarker>. The action is triggered when the user selects the corresponding marker.

Note:

You must insert the <SelectAction> element before the desired layout type (BoxLayout, FlowLayout, GridLayout, ResponsiveLayout, TabLayout).

Examples

Example 1: `<Map>` control with defined properties and a group of markers

Map control with properties in the .wad file

XML

<Properties>
	<Property name="favorites" type="List">
		<Property name="lat" type="Decimal" />
		<Property name="lng" type="Decimal" />
	</Property>
</Properties>

...

<Map vendor="OpenStreetMap">
	<Markers longitude="#lng" data="#favorites" latitude="#lat" iconUrl="heart.png" name="Favorites" description="Places, I have visited." iconVerticalPosition="top"/>
</Map>

Data provided by the Technical Process (*.xml)

XML

<OkList>
	<favorites>
		<lat>48.94061</lat>
		<lng>8.40471</lng>
	</favorites>
	
	<favorites>
		<lat>49.01396</lat>
		<lng>8.40445</lng>
	</favorites>
</OkList>

Example 2: `<Map>` with two sets of markers and enabled search and route calculation

Map control with properties in the .wad file

XML

<Properties>
	<Property name="favorites" type="List">
		<Property name="lat" type="Decimal" />
		<Property name="lng" type="Decimal" />
	</Property>
	<Property name="destinations" type="List">
		<Property name="lat" type="Decimal" />
		<Property name="lng" type="Decimal" />
	</Property>
</Properties>

...

<Map vendor="OpenStreetMap">
	<Search/>
	<Routing destinationIconUrl="finish.png" startIconUrl="car.png" destinationIconVerticalPosition="top" destinationIconHorizontalPosition="center"/>
	<Markers longitude="#lng" data="#favorites" latitude="#lat" iconUrl="heart.png" name="Favorites" description="Places, I have visited." iconVerticalPosition="top"/>
<Markers longitude="#lng" data="#destinations" latitude="#lat" iconUrl="star.png" name="Destinations" description="Places, I want to visit."/>
</Map>

Data provided by the Technical Process (*.xml)

XML

<OkList>
	<favorites>
		<lat>48.94061</lat>
		<lng>8.40471</lng>
	</favorites>
	
	<favorites>
		<lat>49.01396</lat>
		<lng>8.40445</lng>
	</favorites>
	
	<destinations>
		<lat>51.8058</lat>
		<lng>10.3343</lng>
	</destinations>
	
	<destinations>
		<lat>52.3807</lat>
		<lng>9.7706</lng>
	</destinations>
	
</OkList>

Multiple groups of markers with different icons (OpenStreetMap)

Search function (OpenStreetMap)

Route calculation (OpenStreetMap)

Example 3: `<Map>` control with Google Maps

Map control with properties in the .wad file

XML

<Properties>
	<Property name="favorites" type="List">
		<Property name="lat" type="Decimal" />
		<Property name="lng" type="Decimal" />
	</Property>
	<Property name="destinations" type="List">
		<Property name="lat" type="Decimal" />
		<Property name="lng" type="Decimal" />
	</Property>
</Properties>

...

<Map vendor="Google">
	<Search/>
	<Routing destinationIconUrl="finish.png" startIconUrl="car.png" destinationIconVerticalPosition="top" destinationIconHorizontalPosition="center"/>
	<Markers longitude="#lng" data="#favorites" latitude="#lat" iconUrl="heart.png" name="Favorites" description="Places, I have visited." iconVerticalPosition="top"/>
<Markers longitude="#lng" data="#destinations" latitude="#lat" iconUrl="star.png" name="Destinations" description="Places, I want to visit."/>
</Map>

Data provided by the Technical Process (*.xml)

XML

<OkList>
	<favorites>
		<lat>48.94061</lat>
		<lng>8.40471</lng>
	</favorites>
	
	<favorites>
		<lat>49.01396</lat>
		<lng>8.40445</lng>
	</favorites>
	
	<destinations>
		<lat>51.8058</lat>
		<lng>10.3343</lng>
	</destinations>
	
	<destinations>
		<lat>52.3807</lat>
		<lng>9.7706</lng>
	</destinations>
</OkList>

Instructions for use

Attribute

Use the user's location (<Geolocation> element)

Marker group (<Markers/> element)

Route calculation (<Routing/> element)

Search function (<Search/> element)

Setting a marker by clicking in the map (<SelectedLocationMarker> element)

Simple marker (<SingleMarker/> element)

Actions

<SelectAction>

Examples

Example 1: <Map> control with defined properties and a group of markers

Example 2: <Map> with two sets of markers and enabled search and route calculation

Example 3: <Map> control with Google Maps

Use the user's location (`<Geolocation>` element)

Marker group (`<Markers/>` element)

Route calculation (`<Routing/>` element)

Search function (`<Search/>` element)

Setting a marker by clicking in the map (`<SelectedLocationMarker>` element)

Simple marker (`<SingleMarker/>` element)

`<SelectAction>`

Example 1: `<Map>` control with defined properties and a group of markers

Example 2: `<Map>` with two sets of markers and enabled search and route calculation

Example 3: `<Map>` control with Google Maps