Maps | X4Documentation

With map controls, maps from different vendors, including Google Maps and OpenStreetMap, can be integrated into X4 Web Apps. Geodata can be displayed, locations searched, and routes found.

Creating a Map Control

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

Possible attributes:

In addition to the standard attributes of a control, the element <Map> 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 a map provider, the API key is ignored. If Google Maps is used as vendor, the following APIs have to be activated: Maps JS API Locations (for searching and routing) Directions (for routing) The `apiKey` attribute in the Map control overrides 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 the 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 attribute `selectedIndex` takes over the `index` value of a single marker (`SingleMarker`) or a marker group (`Markers`) as soon as they are selected. Possible values: String binding
`vendor`	Required. Defines the map vendor. Possible values: `OpenStreetMap` `Google` `Bing`
`zoomLevel`	Specifies the maps's initial zoom level. 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`	Defines if the user can interact with the control. Data binding (boolean) possible Possible values: `true` / `false` or data binding expression The `enabled` attribute replaces the obsolete `disabled` attribute. `enabled="true"` thus corresponds to the obsolete `disabled="false" attribute` .
`horizontalAlign`	Direction in which the elements flow. The order of the elements corresponds to their declaration. Possible values: `left` (default) `center` `right`
`textOverflow`	Defines what happens if the page is full. Possible values: `ellipsis`: Show with `...` that the text is not finished `hidden`: Break off text, paying attention to whole words `wordBreak`: Break off within the word `allow` (default): Break off text between words
`visible`	Defines if the control is visible. Data binding (boolean) possible Possible values: `true` / `false` or data binding expression

Search

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 may have the following attributes:

Attribute	Description
`searchIconHorizontalPosition`	Defines the horizontal position of the icon relative to coordinates searched for. Possible values: `left`: Icon is left to the coordinate `center` (default): Icon is on the coordinate `right`: Icon is right to the coordinate
`searchIconUrl`	Path to the graphic file to be used as icon. The icon marks the search result. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. Data binding possible Possible values: String (URI)
`searchIconVerticalPosition`	Defines the vertical position of the icon relative to the coordinates searched for. Possible values: `top`: Icon is above the coordinate `center` (default): Icon is on the coordinate `bottom`: Icon is below the coordinate

Attribute

Description

searchIconHorizontalPosition

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

Possible values:

left: Icon is left to the coordinate
center (default): Icon is on the coordinate
right: Icon is right to the coordinate

searchIconUrl

Path to the graphic file to be used as icon. The icon marks the search result. The graphic file must be contained in the folder Resources directly below the web app project. Path relative to folder Resources.

Data binding possible

Possible values: String (URI)

searchIconVerticalPosition

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

Possible values:

top: Icon is above the coordinate
center (default): Icon is on the coordinate
bottom: Icon is below the coordinate

Routing

To allow a Web App user to calculate routes 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 may have the following attributes:

Attribute	Description
`destinationIconHorizontalPosition`	Defines the horizontal position of the destination icon relative to the coordinates searched for. Possible values: `left`: Icon is left to the coordinate `center` (default): Icon is on the coordinate `right`: Icon is right to the coordinate
`destinationIconUrl`	Path to the graphic file to be used as icon for the destination. The icon marks the destination of the route. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. Data binding possible Possible values: String (URI)
`destinationIconVerticalPosition`	Defines the vertical position of the destination icon relative to the coordinates searched for. Possible values: `top`: Icon is above the coordinate `center` (default): Icon is on the coordinate `bottom`: Icon is below the coordinate
`startIconHorizontalPosition`	Defines the horizontal position of the start icon relative to the coordinates searched for. Possible values: `left`: Icon is left to the coordinate `center` (default): Icon is on the coordinate `right`: Icon is right to the coordinate
`startIconUrl`	Path to the graphic file to be used as icon for the start. The icon marks the start of the route. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. 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`: Icon is above the coordinate `center` (default): Icon is on the coordinate `bottom`: 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 may have the following attributes:

Attribute	Description
`componentName`	Defines the name of the component for internal navigation. Possible values: String (Name of a component)
`description`	Defines the description of the marker. Data binding possible Possible values: String incl. spaces
`externalLink`	Defines the link that is shown in the pop-up of the marker. Data binding possible Possible values: String (URL)
`externalLinkTarget`	Defines whether the link (`externalLink`) is opened within the same tab or a new tab. Possible values: `same`: The link is opened within the same tab `new`: The link is opened in a new tab
`iconHorizontalPosition`	Defines the horizontal position of the icon relative to the given coordinates. Possible values: `left`: Icon is left to the coordinate `center` (default): Icon is on the coordinate `right`: Icon is right to the coordinate
`iconUrl`	Path to the graphic file to be used as icon for the marker. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. Data binding possible Possible values: String (URI)
`iconVerticalPosition`	Defines the vertical position of the icon relative to the given coordinates. Possible values: `top`: Icon is above the coordinate `center` (default): Icon is on the coordinate `bottom`: Icon is below the coordinate
`index`	Marker index Data binding possible Possible values: Any string
`latitude`	Required if `searchString` is not used. Defines 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. Defines 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`	Defines the name of the marker. Data binding possible Possible values: String of alphanumeric characters
`navigationDisplayName`	Defines the text that is displayed in the marker pop-up instead of an external link or component name. Data binding possible Possible values: String incl. spaces
`searchString`	Required if `latitude`/`longitude` is not used. Address line for searching for selected services of the vendor. Data binding possible Possible values: String for a service search, e.g. `Restaurant` This attribute cannot be used at the same time as the attributes `latitude`/`longitude`.

Marker set

To display a set of 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 may 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`	Defines 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 descriptions of the markers. Data binding required Possible values: Data Binding expression relative to the expression in `data`
`externalLink`	Defines the link that is shown in the pop-up of the marker. Data binding required Possible values: Data Binding expression relative to the expression in `data`
`externalLinkTarget`	Defines whether the link (`externalLink`) is opened within the same tab or a new tab. Possible values: `same`: The link is opened within the same tab `new`: The link is opened in a new tab
`iconHorizontalPosition`	Defines the horizontal position of the icon relative to the given coordinates. Possible values: `left`: Icon is left to the coordinate `center` (default): Icon is on the coordinate `right`: Icon is right to the coordinate
`iconUrl`	Path to the graphic file to be used as icon for the markers. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. Data binding possible Possible values: String (URI)
`iconVerticalPosition`	Defines the vertical position of the icon relative to the given coordinates. Possible values: `top`: Icon is above the coordinate `center` (default): Icon is on the coordinate `bottom`: Icon is below the coordinate
`index`	Marker group index 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 names of the markers. Data binding required Possible values: Data Binding expression relative to the expression in `data`
`navigationDisplayName`	Defines the text that is displayed in the marker pop-up instead of an external link or component name. Data binding possible Possible values: String incl. 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 for searching for selected services of the vendor. Data binding possible Possible values: String for a service search, e.g. `Restaurant` This attribute cannot be used at the same time as the attributes `latitude`/`longitude`.
`textHorizontalPosition`	Defines the horizontal position of the numbering relative to the given coordinates. Possible values: `left`: Numbering is left to the coordinate (default) `center`: Numbering is on the coordinate `right`: Numbering is right to 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 via the element <SelectAction/> within <SingleMarker>, <Markers> or <SelectedLocationMarker> and is triggered as soon as a corresponding marker is selected.

Examples

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

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>

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:

In this example, two sets of markers are displayed and searching and routing are activated.

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>

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:

Several groups of markers with different icons (OpenStreetMap)

Searching (OpenStreetMap)

Routing (OpenStreetMap)

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

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>

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:

Set 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 in 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 may 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. 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 icon. The icon marks the selected location. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. Data binding possible Possible values: String (URI)

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. 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 icon. The icon marks the selected location. The graphic file must be contained in the folder Resources directly below the web app project. Path relative to folder Resources.

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, then a button is displayed in the map. By clicking on the button the location of the user is queried and marked on the map.

Possible attributes:

Attribute	Description
`iconUrl`	Path to the graphic file to be used as icon for the markers. The graphic file must be contained in the folder `Resources` directly below the web app project. Path relative to folder `Resources`. 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 icon for the markers. The graphic file must be contained in the folder Resources directly below the web app project. Path relative to folder Resources.

Possible values: String (URI)

iconHorizontalPosition

Horizontal position of the icon

iconVerticalPosition

Vertical position of the icon