X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

Map

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

Creating a Map control

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

Possible attributes:

In addition to the standard attributes for controls, the <Map> element can have the following attributes:

Attribute

Description

apiKey

Defines the API key if required by the vendor.

Possible values: API key

To use OpenStreetMap, no API key is required. If an API key is entered when using OpenStreetMap as the map provider, the API key is ignored.

If Google Maps is used as the 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 vendor.

Possible values:

  • OpenStreetMap

  • Google

  • Bing

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

enabled

Specifies whether the user can interact with the control.

  • Data binding (Boolean) is possible

Possible values: true/false or expression for data binding

The enabled attribute replaces the deprecated disabled attribute. enabled="true" corresponds to the obsolete disabled="false" attribute.

horizontalAlign

The direction in which the elements flow. The order of the elements corresponds to their declaration.

Possible values:

  • left (default)

  • center

  • right

textOverflow

Specifies what should happen when the control is full.

Possible values:

  • ellipsis : Use ... to show that the text is not finished

  • hidden : Break off text, watch for whole words

  • wordBreak : Break off text within word

  • allow (default): break off text between words

visible

Defines if the control is visible.

  • Data binding (Boolean) is possible

Possible values: true / false or string for data binding

To allow a web app user to search for locations in the map control, the <Search/> element is used within <Map>.

XML
<Map>
	<Search/>
</Map>

Possible attributes:

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 graphics 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)

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.

Routing

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>

Possible attributes:

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 graphics 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)

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 graphics 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)

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.

Single marker

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>

Possible attributes:

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 on the same tab

  • new: The link opens on 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. 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.

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 when latitude/longitude is not in use. 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.

Marker set

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>

Possible attributes:

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)

data

Required. Defines which data is used for the marker set.

  • Data binding required

Possible values: Data binding expression

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

externalLinkTarget

Specifies whether the link (externalLink) opens on the same tab or a new tab.

Possible values:

  • same: The link opens on the same tab

  • new: The link opens on 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 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.

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 when latitude/longitude is not in use. 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.

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: 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: 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.

"Select" Action within a Map

The Select action is created with the <SelectAction/> element within <SingleMarker>, <Markers>, or <SelectedLocationMarker> and is triggered as soon as a corresponding marker has been selected.

Examples

In this example, the properties are defined and a group of markers is displayed.

Example 1 Map Control (*.wad)
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>
Example 1: 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>


The above example leads to the following result:

Example1.png


In this example, two groups of markers are displayed and search and route calculation are activated.

Example 2 Map Control
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>
Example 2: 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>


The above example leads to the following result:

Example2_Markers.png
Multiple groups of markers with different icons (OpenStreetMap)


Example2_Search.png
Search function (OpenStreetMap)


Example2_Routing.png
Route calculation (OpenStreetMap)


Additional map providers are also available. The following example shows a map control with Google Maps.

Example 2 Map Control
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>
Example 2: 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>


The above example leads to the following result:

RoutingGoogleMaps.png

Setting a marker by clicking in the map

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>

Possible attributes:

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

Attribute

Description

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. Path information relative to the Resources folder.

  • Data binding possible

Possible values: String (URI)

Using the user's location

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.

Possible 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