Map Fields

Map

A map field may contain one or more points on a map, linestrings, or an area. The map is integrated directly into the editor. To learn more about how to use maps, please read the documentation of the add-on. This input field will save the map as KML and displays KML correspondingly.

The provider configuration is a JSON object. It is defined by the following TypeScript interface where keys with a question mark are optional:

export interface TilesConfiguration {
 providerName: 'bing' | 'osm' | 'mapbox' | 'custom',
  providerConfiguration?: olx.source.BingMapsOptions | olx.source.OSMOptions | olx.source.XYZOptions,
  availableMapStyles?: Array<MapStyle>,
  saveMapStyle?: boolean,
  searchProviderConfiguration?: SearchProviderConfiguration
}

So the valid names for providerName are either 'bing' for Bing Maps, 'osm' for OpenStreetMap, 'mapbox' for Mapbox or 'custom' for a non-standard tiles provider (e.g. a self hosted OpenStreetMap). The providerConfiguration must be an OpenLayers object. The exact syntax can be found in the OpenLayers documentation. Sample configurations for the three different tiles providers are listed below.

The availableMapStyles, if given, provide a dropdown on the map where the style can be changed. It is a list of 'key'-'label' pairs. The keys depend on the providerName. For OpenStreetMap no further styles are supported. For Bing Maps a value for imagerySet must be given. For Mapbox different URLs can be set. In each case, the label can be chosen freely and will be visible in the dropdown.

When saveMapStyle is set to true, the selected map style in the editor will be saved into the KML within the ExtendedData section.

The searchProviderConfiguration controls which external provider is used for performing the text search. Although the list of providers overlaps with the list of tiles providers, they don't have to match. You totally can display map tiles from Bing but use the search API by Mapbox. By default the search API Nominatim by OpenStreetMap will be used. See the section below for a more detailed explanation on configuration and alternatives.

Example for OpenStreetMap

{
  providerName: 'osm'
}

Example for Bing Maps

{
	providerName: 'bing',
	providerConfiguration: {
		key: 'YourBingApiKey',
		culture: 'de-DE',
		imagerySet: 'Road'
	},
	availableMapStyles: [{
			key: 'Road',
			label: 'Streets'
		}, {
			key: 'Aerial',
			label: 'Satellite'
		}, {
			key: 'AerialWithLabels',
			label: 'Satellite with Labels'
		}
	],
	saveMapStyle: true,
	searchProviderConfiguration: {
		name: 'bing',
		apiKey: 'YourBingApiKey'
	}
}

Example for Mapbox

{
	providerName: 'mapbox',
	providerConfiguration: {
		url: 'https://api.mapbox.com/styles/v1/mycompany/mapId1/tiles/256/{z}/{x}/{y}?access_token=YourAccessToken'
	},
	availableMapStyles: [{
			key: 'https://api.mapbox.com/styles/v1/mycompany/mapId1/tiles/256/{z}/{x}/{y}?access_token=YourAccessToken',
			label: 'Dark'
		}, {
			key: 'https://api.mapbox.com/styles/v1/mycompany/mapId2/tiles/256/{z}/{x}/{y}?access_token=YourAccessToken',
			label: 'Outdoors'
		}, {
			key: 'https://api.mapbox.com/styles/v1/mycompany/mapId3/tiles/256/{z}/{x}/{y}?access_token=YourAccessToken',
			label: 'Satellite'
		}
	],
	searchProviderConfiguration: {
		name: 'mapbox',
		apiKey: 'YourAccessToken'
	}
}

Example for self hosted map tiles

{
  providerName: 'custom',
  providerConfiguration: {
    url: 'https://my-tiles-server.com/osm-default/{z}/{x}/{y}.png',
    tilePixelRatio: 2
  },
  searchProviderConfiguration: {
    name: 'nominatim',
    url: 'https://my-nominatim-server.com/nominatim/search.php'
  }
}

Configuring the search provider

The search provider configuration is a composed Json object itself which follows this syntax:

export interface SearchProviderConfiguration {
  name: 'bing' | 'osm' | 'mapbox' | 'nominatim',
  url:? string,
  apiKey?: string
}

The API-Key is not needed for osm and a custom provider. OSM is the default. If you are using the search API by mapbox then you have to use your AccessToken to fill into the apiKey property.

You can use 'nominatim' to provide a custom Nominatim server.

Map (Bing)

A map field may contain one or more spots on a map, routes, or an area. The map is integrated directly into the document. To learn more about how to use maps, please read the documentation of the add-on.

Map Location (Bing)

With a Map Location field, you will not see the whole map in the document, but only a text field. You can edit the location by clicking on the button on the right which will then open a map. The text field itself is read-only and will always show the currently selected location.