X4 Produktdokumentation

Map

Mit <Map>-Controls können Sie Karten verschiedener Anbieter, u. a. Google Maps und OpenStreetMap, in X4 Web Apps einbinden. Es können Geodaten angezeigt, Standorte gesucht und Routen gefunden werden.

Hinweise zur Verwendung

Ein <Map>-Control wird mit dem Element <Map> erzeugt. Das Element kann nur im Layout einer Detail Component verwendet werden.

XML
<Map>
...
</Map>

Das Element <Map> kann folgende Elemente enthalten:

  • <Geolocation>

  • <Markers>

  • <Routing>

  • <Search>

  • <SelectedLocationMarkers>

  • <SingleMarker

<Map>-Controls können in allen verfügbaren Layouttypen verwendet werden. Weitere Informationen finden Sie unter Layouts.

Attribute

Hinweis:

Es gibt eine Reihe von Standardattributen, die für alle Controls festgelegt werden können. Weitere Informationen zu den Standardattributen finden Sie unter Standardattribute.

Zusätzlich zu den Standardattributen können Sie die folgenden Attribute für <Map>-Controls definieren.

Attribut

Beschreibung

apiKey

Gibt den API-Schlüssel an, falls dieser vom Kartenanbieter verlangt wird.

Mögliche Werte:

API-Schlüssel

Hinweis:

Bei Verwendung von OpenStreetMap als Kartenanbieter wird kein API-Schlüssel benötigt. Falls ein API-Schlüssel eingegeben wird, wenn OpenStreetMap verwendet wird, wird der API-Schlüssel ignoriert.

Bei Verwendung von Google Maps als Kartenanbieter müssen folgende APIs aktiviert sein:

  • Maps JS API

  • Locations (für die Suche und die Routenberechnung)

  • Directions (für die Routenberechnung)

Das Attribut apiKey überschreibt das Element MapAPIKey in der Web App-Konfiguration .wac.

initialPointLongitude

Definiert den Längengrad, auf den die Karte zentriert sein soll, wenn sie geladen wird.

  • Data Binding mit konstanten Werten möglich

Mögliche Werte:

Angabe eines Längengrads in Grad mit Dezimalstellen (z. B. 6.75000)

initialPointLatitude

Definiert den Längengrad, auf den die Karte zentriert sein soll, wenn sie geladen wird.

  • Data Binding mit konstanten Werten möglich

Mögliche Werte:

Angabe eines Breitengrads in Grad mit Dezimalstellen (z. B. 50.41871)

restrictScrolling

Scrolling-Verhalten in Maps einschränken

Mögliche Werte:

  • true (Standard): Beim Scrollen mit der Maus bzw. mit dem Finger auf mobilen Geräten wird eine Meldung eingeblendet, die über das alternative Scrollen informiert.

  • false: Alternatives Scrolling-Verhalten ist deaktiviert.

satelliteView 

Legt fest, ob die Satellitenansicht der Karte aktiviert ist.

Mögliche Werte: 

  • true

  • false (Standard)

Die Satellitenansicht kann nicht verwendet werden, wenn OpenStreetMap als Kartenanbieter verwendet wird.

selectedIndex

Ausgewählter Index

Das Attribut selectedIndex übernimmt den index-Wert eines einfachen Markers (SingleMarker) oder eine Markergruppe (Markers), sobald diese ausgewählt wurden.

Mögliche Werte:

String Binding

​vendor

Erforderlich

​Gibt den Kartenanbieter an.

Mögliche Werte:

  • Bing

  • Google

  • OpenStreetMap

Hinweis bei Auswahl von Bing als Kartenanbieter:

Die Nutzung von Bing Maps wird zukünftig nicht mehr möglich sein. Grund ist die Abkündigung der zugrunde liegenden Microsoft-API (Mai 2024, vollständiges Abschalten für Free Tier ab Juni 2025).
Als Alternative wird in einer kommenden X4 BPMS Version Azure Maps als neuer Kartenanbieter zur Verfügung stehen.

zoomLevel

Gibt die initiale Zoomstufe der Karte an.

Die Werte geben die in der Karte angezeigten Meter ungefähr an.

Beachten Sie, dass es beim Maßstabsbalken zu Abweichungen kommen kann, da sich der Maßstab in Abhängigkeit von der Entfernung vom Äquator ändert.

Mögliche Werte:

  • 10

  • 25

  • 50

  • 100

  • 250

  • 500

  • 750

  • 1000

  • 2000

  • 5000

  • 10000

  • 25000

  • 50000

  • 100000

  • 2500000

  • 5000000

Standort des Benutzers verwenden (Element <Geolocation>)

Innerhalb des Elements <Map> kann das Element <Geolocation> verwendet werden, um den Standort des Benutzers abzufragen. Wenn das Element <Geolocation> verwendet wird, dann wird in der Karte ein Button angezeigt. Per Klick auf den Button wird der Standort des Benutzers abgefragt und auf der Karte markiert.

Das Element <Geolocation> kann folgende Attribute haben:

Attribut

Beschreibung

iconUrl

Pfad zur Grafikdatei, die als Icon für die Marker verwendet werden soll. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App-Projekts enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URI)

iconHorizontalPosition

Horizontale Position des Icons

iconVerticalPosition

Vertikale Position des Icons

Markergruppe (Element <Markers/> )

Um mehrere Marker in einem Map-Control anzuzeigen, wird das Element <Markers/> innerhalb von <Map> und ggf. nach <Search/> und <Routing/> verwendet.

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

Hinweis:

Bei Verwendung mehrerer Marker werden die jeweiligen Icons in der entsprechenden Reihenfolge dargestellt. Die erste Marker-Gruppe wird auf der untersten Ebene dargestellt, die letzte auf der oberste Ebene. Dadurch überlagern die Icons der letzten Marker-Gruppe ggf. die Icons der zuerst aufgeführten Marker.

Das Element <Markers/> kann folgende Attribute haben:

Attribut

Beschreibung

cluster

Gibt an, ob Marker zusammengefasst werden sollen, wenn sie auf der Karte sehr dicht beieinander liegen.

Mögliche Werte:

  • true 

  • false (Standard)

cluster und number können nicht gleichzeitig verwendet werden!

componentName

Gibt den Namen der Component für eine interne Navigation an.

Mögliche Werte:

Zeichenkette (Name einer Component)

componentName und externalLink können nicht gleichzeitig verwendet werden!

data​

Erforderlich

Definiert, welche Daten für die Markergruppe verwendet werden.

  • Data Binding erforderlich

Mögliche Werte:

Ausdruck für Data Binding

description

Gibt die Beschreibung der Marker an.

  • Data Binding erforderlich

Mögliche Werte:

Data-Binding-Ausdruck relativ zum Ausdruck in data

externalLink

Gibt den Link an, der im Pop-up des Markers angezeigt wird.

  • Data Binding erforderlich

Mögliche Werte:

Data-Binding-Ausdruck relativ zum Ausdruck in data

componentName und externalLink können nicht gleichzeitig verwendet werden!

externalLinkTarget

Gibt an, ob der Link (externalLink) im selben oder in einem neuen Tab geöffnet wird.

Mögliche Werte:

  • same: Der Link wird im selben Tab geöffnet.

  • new: Der Link wird in einem neuen Tab geöffnet.

iconHorizontalPosition

Definiert die horizontale Position des Icons relativ zu den eingegebenen Koordinaten. Dies wirkt sich vor allem bei niedrigen Zoom-Stufen aus: Hier wird das Icon links/rechts von der tatsächlichen Koordinate dargestellt.

Mögliche Werte:

  • left: Icon ist links von der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • right: Icon ist rechts von der Koordinate.

iconUrl

Pfad zur Grafikdatei, die als Icon für die Marker verwendet werden soll. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App-Projekts enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URI)

iconVerticalPosition

Definiert die vertikale Position des Icons relativ zu den eingegebenen Koordinaten. Dies wirkt sich vor allem bei niedrigen Zoom-Stufen aus: Hier wird das Icon oberhalb/unterhalb von der tatsächlichen Koordinate dargestellt.

Mögliche Werte:

  • top: Icon ist über der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • bottom: Icon ist unter der Koordinate.

index

Index der Markergruppe

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

latitude

Erforderlich, wenn searchString nicht verwendet wird.

Gibt den Breitengrad eines Markers an.

  • Data Binding möglich

Mögliche Werte: Data-Binding-Ausdruck relativ zum Ausdruck in data

longitude

Erforderlich, wenn searchString nicht verwendet wird.

Gibt den Längengrad eines Markers an.

  • Data Binding möglich

Mögliche Werte: 

Data-Binding-Ausdruck relativ zum Ausdruck in data

name

Gibt den Namen der Marker an.

  • Data Binding erforderlich

Mögliche Werte:

Data-Binding-Ausdruck relativ zum Ausdruck in data

navigationDisplayName

Gibt den Text an, der im Pop-up des Markers statt eines externen Links oder eines Component-Namens angezeigt wird.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette inkl. Leerzeichen

number

Gibt an, ob die Marker nummeriert werden sollen.

Mögliche Werte: 

  • true 

  • false (Standard)

cluster und number können nicht gleichzeitig verwendet werden!

searchString

Erforderlich, wenn latitude/longitude nicht verwendet wird.

Adresszeile zur Suche nach ausgewählten Diensten des Kartenanbieters.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette für eine Dienstsuche, z. B. Restaurant

Hinweis:

  • Dieses Attribut kann nicht gleichzeitig mit den Attributen latitude/longitude verwendet werden.

  • Marker, die auf Basis von Ortsnamen (searchString) gesucht werden, werden bei mehreren Datensätzen aufgrund von Timeouts beim Kartenanbieter ggf. verzögert oder unvollständig angezeigt. Verwenden Sie vorzugsweise Geo-Koordinaten, um alle Marker zuverlässig und schnell darzustellen.

textHorizontalPosition

Definiert die horizontale Position der Nummerierung relativ zu den eingegebenen Koordinaten.

Mögliche Werte:

  • left: Nummerierung ist links von der Koordinate (Standard).

  • center: Nummerierung ist auf der Koordinate.

  • right (Standard): Nummerierung ist rechts von der Koordinate.

Bing Maps positioniert die Nummerierung automatisch. Daher hat diese Funktion auf Bing Maps keinen Einfluss.

textVerticalPosition

Definiert die vertikale Position der Nummerierung relativ zu den eingegebenen Koordinaten.

Mögliche Werte:

  • top: Nummerierung ist über der Koordinate (Standard).

  • center (Standard): Nummerierung ist auf der Koordinate.

  • bottom: Nummerierung ist unter der Koordinate.

Bing Maps positioniert die Nummerierung automatisch. Daher hat diese Funktion auf Bing Maps keinen Einfluss.

Routenberechnung Element <Routing/>

Um einem Web App-Benutzer die Berechnung einer Route zwischen zwei Orten im Maps-Control zu ermöglichen, wird das Element <Routing/> innerhalb von <Map> und ggf. nach <Search/> verwendet.

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

Das Element <Routing/> kann folgende Attribute haben:

Attribut

Beschreibung

destinationIconHorizontalPosition

Definiert die horizontale Position des Zielicons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • left: Icon ist links von der Koordinate

  • center (Standard): Icon ist auf der Koordinate

  • right: Icon ist rechts von der Koordinate

destinationIconUrl

Pfad zur Grafikdatei, die als Icon für den Zielpunkt verwendet werden soll. Mit dem Icon wird der Zielpunkt der Route markiert. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App-Projekts enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte: Zeichenkette (URI)

destinationIconVerticalPosition

Definiert die vertikale Position des Zielicons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • top: Icon ist über der Koordinate

  • center (Standard): Icon ist auf der Koordinate

  • bottom: Icon ist unter der Koordinate

startIconHorizontalPosition

Definiert die horizontale Position des Starticons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • left: Icon ist links von der Koordinate

  • center (Standard): Icon ist auf der Koordinate

  • right: Icon ist rechts von der Koordinate

​startIconUrl

​​Pfad zur Grafikdatei, die als Icon für den Startpunkt verwendet werden soll. Mit dem Icon wird der Startpunkt der Route markiert. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App-Projekts enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte: Zeichenkette (URI)

startIconVerticalPosition

Definiert die vertikale Position des Starticons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • top: Icon ist über der Koordinate

  • center (Standard): Icon ist auf der Koordinate

  • bottom: Icon ist unter der Koordinate

Suchfunktion (Element <Search/>)

Um Benutzern die Suche nach Orten im <Map>-Control zu ermöglichen, wird das Element <Search/> innerhalb von <Map> verwendet.

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

Das Element <Search/> kann folgende Attribute haben:

Attribut

Beschreibung

searchIconHorizontalPosition

Definiert die horizontale Position des Icons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • left: Icon ist links von der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • right: Icon ist rechts von der Koordinate.

​searchIconUrl

​Pfad zur Grafikdatei, die als Icon verwendet werden soll. Mit dem Icon wird das Suchergebnis markiert. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App Projects enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URI)

searchIconVerticalPosition

Definiert die vertikale Position des Icons relativ zu den gesuchten Koordinaten.

Mögliche Werte:

  • top: Icon ist über der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • bottom: Icon ist unter der Koordinate.

Marker per Klick in der Karte setzen (Element <SelectedLocationMarker>)

Das Element <SelectedLocationMarker> ermöglicht dem Benutzer einer Web App, eine Markierung zu setzen, indem er in der Karte auf eine bestimmte Stelle klickt. Die vom Benutzer markierte Stelle kann durch einen Technical Process weiterverarbeitet werden.

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

Das Element <SelectedLocationMarker/> kann folgende Attribute haben:

Attribut

Beschreibung

description

Gibt die Beschreibung des Markers an.

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette inkl. Leerzeichen

longitude

Erforderlich

Längengrad der Markierung

  • Data Binding möglich

Mögliche Werte: 

Property

Als Wert für das Attribut muss eine Property hinterlegt werden.

latitude

Erforderlich

Breitengrad der Markierung

  • Data Binding möglich

Mögliche Werte: 

Property

Als Wert für das Attribut muss eine Property hinterlegt werden.

iconUrl

​Pfad zur Grafikdatei, die als Icon verwendet werden soll. Mit dem Icon wird der gewählte Ort markiert. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web App Projects enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URI)

name

Gibt den Namen des Markers an.

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette aus alphanumerischen Zeichen

Einfacher Marker (Element <SingleMarker/>)

Um einen einfachen Marker in einem Map-Control anzuzeigen, wird das Element <SingleMarker/> innerhalb von <Map> und ggf. nach <Search/> und <Routing/> verwendet.

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

Das Element <SingleMarker/> kann folgende Attribute haben:

Attribut

Beschreibung

componentName

Gibt den Namen der Component für eine interne Navigation an.

Mögliche Werte:

Zeichenkette (Name einer Component)

description

Gibt die Beschreibung des Markers an.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette inkl. Leerzeichen

externalLink

Gibt den Link an, der im Pop-up des Markers angezeigt wird.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URL)

externalLinkTarget

Gibt an, ob der Link (externalLink) im selben oder in einem neuen Tab geöffnet wird.

Mögliche Werte:

  • same: Der Link wird im selben Tab geöffnet.

  • new: Der Link wird in einem neuen Tab geöffnet.

iconHorizontalPosition

Definiert die horizontale Position des Icons relativ zu den eingegebenen Koordinaten.

Mögliche Werte:

  • left: Icon ist links von der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • right: Icon ist rechts von der Koordinate.

iconUrl

​​Pfad zur Grafikdatei, die als Icon für den Marker verwendet werden soll. Die Grafikdatei muss im Ordner Resources direkt unterhalb des Web-App-Projekts enthalten sein. Pfadangabe relativ zum Ordner Resources.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette (URI)

iconVerticalPosition

Definiert die vertikale Position des Icons relativ zu den eingegebenen Koordinaten.

Mögliche Werte:

  • top: Icon ist über der Koordinate.

  • center (Standard): Icon ist auf der Koordinate.

  • bottom: Icon ist unter der Koordinate.

index

Index des Markers

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

latitude

Erforderlich, wenn searchString nicht verwendet wird.

Gibt den Breitengrad des Markers an.

  • Data Binding möglich

Mögliche Werte:

Angabe eines Breitengrads in Grad mit Dezimalstellen (z. B. 50.41871)

Dieses Attribut kann nicht gleichzeitig mit searchString verwendet werden.

longitude

Erforderlich, wenn searchString nicht verwendet wird.

Gibt den Längengrad des Markers an.

  • Data Binding möglich

Mögliche Werte: Angabe eines Längengrads in Grad mit Dezimalstellen (z. B. 6.75000)

Dieses Attribut kann nicht gleichzeitig mit searchString verwendet werden.

​name

​Gibt den Namen des Markers an.

  • Data Binding möglich

Mögliche Werte: Zeichenkette aus alphanumerischen Zeichen

navigationDisplayName

Gibt den Text an, der im Pop-up des Markers statt eines externen Links oder eines Componentnamens angezeigt wird.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette inkl. Leerzeichen

searchString

Erforderlich, wenn latitude/longitude nicht verwendet wird.

Adresszeile zur Suche nach ausgewählten Diensten des Kartenanbieters.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette für eine Dienstsuche, z. B. Restaurant

Dieses Attribut kann nicht gleichzeitig mit den Attributen latitude/longitude verwendet werden

Actions

Für <Map>-Controls steht Ihnen folgende Action zur Verfügung. Weitere Informationen zu Actions finden Sie unter Actions.

<SelectAction> 

Sie können die Action Select über das Element <SelectAction/> innerhalb von SingleMarker><Markers> oder <SelectedLocationMarker> einfügen. Die Action wird ausgelöst, sobald der Benutzer den entsprechenden Marker auswählt.

Hinweis:

Sie müssen das Element <SelectAction> vor dem gewünschten Layouttyp (BoxLayoutFlowLayout, GridLayoutResponsiveLayoutTabLayout) einfügen.

Beispiele

Beispiel 1: <Map>-Control mit definierten Properties und einer Gruppe von Markern


Map-Control mit Properties in der .wad-Datei
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>
Durch den Technical Process gelieferte Daten (*.xml)
XML
<OkList>
	<favorites>
		<lat>48.94061</lat>
		<lng>8.40471</lng>
	</favorites>
	
	<favorites>
		<lat>49.01396</lat>
		<lng>8.40445</lng>
	</favorites>
</OkList>
Example1.png


Beispiel 2: <Map> mit zwei Gruppen von Markern sowie aktivierter Suche und Routenberechnung

Map-Control mit Properties in der .wad-Datei
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>
Durch den Technical Process gelieferte Daten (*.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>


Example2_Markers.png
Mehrere Gruppen von Markern mit verschiedenen Symbolen (OpenStreetMap)


Example2_Search.png
Suchfunktion (OpenStreetMap)


Example2_Routing.png
Routenberechnung (OpenStreetMap)

Beispiel 3: <Map>-Control mit Google Maps

Map-Control mit Properties in der .wad-Datei
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>
Durch den Technical Process gelieferte Daten (*.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>


RoutingGoogleMaps.png