map-init
This bundle provides a common configuration format for maps and a common place for the main map configuration. It also provides a way for other bundles to create own map widgets based on the same configuration format.
Usage
To configure a map, use the following properties:
- Basemaps
- Map (including layers)
- View (including constraints)
For a list of general properties that can be used in both basemaps and map configuration, see:
The following code sample shows the default configuration structure of a map in the app.json
file:
"map-init" : {
"Config" : {
"basemaps" : [...],
"map" : {
"ground": [...],
"layers": [...],
"tables": [...],
},
"view" : {
"viewmode": "2D",
"constraints": {...},
"extent": {...}
}
}
}
The default map widget is registered at the component system with the widget role map
.
Configuration reference
Basemaps
Basemaps can be configured by using either well known identifiers such as streets
or satellite
or specifying basemap objects that define layers similar to operational layers.
To define the basemap that is activated at the start of an app, use the parameter "selected": true
.
The following code sample shows how to configure different types of basemaps:
"map-init": {
"Config": {
"basemaps": [
{
"id": "streets",
"basemap": "streets-vector",
"selected": true
},
{
"id": "mapserver_tiled1",
"basemap": {
"type": "AGS_TILED",
"url": "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer"
}
},
{
"id": "vectortile1",
"basemap": {
"type": "AGS_VECTORTILE",
"url": "https://www.arcgis.com/sharing/rest/content/items/c11ce4f7801740b2905eb03ddc963ac8/resources/styles/root.json"
}
},
{
"id": "wms1",
"basemap": {
"type": "WMS",
"url": "https://sgx.geodatenzentrum.de/wms_topplus_web_open",
"sublayers": [
{
"name": "web",
"title": "TopPlusOpen"
}
]
}
},
{
"id": "wmts1",
"basemap": {
"type": "WMTS",
"url": "https://sgx.geodatenzentrum.de/wmts_topplus_web_open"
}
}
],
"map": {
"layers": [...],
"ground": [...]
}
}
}
If a basemap should have multiple layers it is possible to define them as an array:
"map-init": {
"Config": {
"basemaps": [
{
"id": "mybasemap",
"basemap": [{
"type": "AGS_TILED",
"url": "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer"
},{
"type": "AGS_VECTORTILE",
"url": "https://www.arcgis.com/sharing/rest/content/items/c11ce4f7801740b2905eb03ddc963ac8/resources/styles/root.json"
}]
}
],
"map": {
"layers": [...],
"ground": [...]
}
}
}
For more information about the configuration options for each basemap in detail, see Layer properties.
Basemap thumbnails
Thumbnails are used by the bundles toc and basemaptoggler to display a small preview of a basemap.
Thumbnails for Esri basemaps (such as streets
or satellite
) are set automatically.
To use thumbnails for custom basemaps or change the ones for Esri basemaps, set a thumbnail URL as shown in the following sample:
"map-init": {
"Config": {
"basemaps": [
{
"id": "esri_satellite",
"basemap": "satellite",
"thumbnailUrl": "resource('${app}:mythumbnail.png')"
}
]
}
}
Map
The map configuration can consist of a basemap, ground layers, operational layers and tables, as shown in the following code sample:
"map-init": {
"Config": {
"map": {
"basemap": [...],
"ground": [...],
"layers": [...],
"tables": [...],
}
}
}
Property | Type | Description |
---|---|---|
basemap | String | Object | Array | Specifies a basemap for the map. |
ground | String | Object | Array | Specifies the surface properties for the map. |
layers | Array | A collection of operational layers. |
tables | Array | A collection of tables. |
"map-init": {
"Config": {
"map": {
"basemap": [...],
"ground": [...],
"layers": [...]
}
}
}
Basemap
NOTE: Use this property only if you want to use exactly one base map in your map. To define multiple base maps that the user can switch between, see basemaps.
The following sample shows a minimal configuration to define a basemap:
"map-init": {
"Config": {
"map": {
"basemap": "streets-vector"
}
}
}
Layers
The following code sample shows how to configure different types of layers:
"layers": [
{
"url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/2",
"type": "AGS_FEATURE",
"visible": true
},
{
"url": "http://services.arcgisonline.com/arcgis/rest/services/World_Terrain_Base/MapServer",
"type": "AGS_TILED"
},
{
"id": "test",
"title": "Grenzen",
"type": "AGS_DYNAMIC",
"url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/MapServer",
"visible": true,
"sublayers": [
{
"id": 2
},
{
"id": 3
}
]
},
{
"id": "ogcfeaturelayer",
"url": "https://vtp2.geo-solutions.it/geoserver/ogc/features",
"type": "OGC_FEATURE",
"copyright": "vtp2.geo-solutions.it",
"title": "OGCFeatureLayer",
"collectionId": "ne:countries50m",
"objectIdField": "NE_ID",
"limit": 5000
},
{
"type": "GROUP",
"layers": [
{
"url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
"type": "AGS_DYNAMIC"
},
{
"url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Military/MapServer",
"type": "AGS_DYNAMIC"
}
]
},
{
"id": "topplus2",
"title": "WMS (TopPlus-Web-Open)",
"type": "WMS",
"url": "https://sgx.geodatenzentrum.de/wms_topplus_web_open",
"sublayers": [
{
"name": "web",
"title": "TopPlusOpen"
}
]
}
]
Adding formatting information to a layer
If a layer should be used with the AutoStoreRegistration to serve as source for a store,
it is possible to add formatting information to control, how values of feature are displayed in a data table in the Result UI.
The following configuration options may be used in the fieldConfig
array:
"layers": [
{
"url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/2",
"type": "AGS_FEATURE",
"visible": true,
"fieldConfig": [
{
"name": "expression/title",
"title": "Title"
},
{
"name": "year",
"title": "other-alias",
"dateFormat": "short-date",
"digitSeparator": true,
"places": 2
}
],
"expressionInfos": [
{
"name": "title",
"expression": "`${$feature.name} (${$feature.hauptstadt})`"
}
]
}
]
NOTE: Please note that if you use
fieldConfig
to configure fields in the Result UI, only the fields that are configured infieldConfig
are displayed, all others are not displayed.
The sample is showing the definition of a virtual field by using a reference to an ArcGIS Arcade expression defined in the expressionInfos
option.
For more details, see formatting options in the agssearch bundle.
Tables
The tables
property defines which tables can be used in the map.
Tables are configured in the same way as layers.
Only feature layers can be used as tables (type AGS_FEATURE
).
For example:
"tables": [
{
"url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/1",
"type": "AGS_FEATURE"
}
]
Ground
Ground layers can be configured by using either well known identifiers such as world-elevation
or specifying a service of type AGS_ELEVATION
.
The following sample shows a minimal configuration to define a ground layer:
"ground": "world-elevation"
To define a custom ground layer, use the following syntax:
"ground": {
"title": "MyGround",
"layers": [{
"url": "http://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
"type": "AGS_ELEVATION"
}]
}
To define multiple ground layers, use an array notation:
"ground": [
{
"url": "http://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
"type": "AGS_ELEVATION"
},
{
"url": "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/MtBaldy_Elevation/ImageServer",
"type": "AGS_ELEVATION"
}
]
View
Property | Type | Description |
---|---|---|
viewmode | String | A view provides the means of viewing and interacting with the components of a Map. Allowed values are 2D and 3D . |
extent | Object | The minimum and maximum X and Y coordinates of a bounding box. |
center | Array or object | The center point of the extent in map units. |
scale | Number | Represents the map scale at the center of the view. |
camera | Object | The camera defines the position, tilt, and heading of the point from which a 3D view is observed. |
zoom | Number | Represents the level of detail (LOD) at the center of the view. |
constraints | Object | Represents the constraints of the view to restrict its behavior. |
navigation | Object | Represents settings to control the view's navigation behavior. |
timeExtent | Object | Controls visibility of temporal features. |
"map-init": {
"Config": {
"view": {
"viewmode": "2D",
"center": [
10.138039,
51.008837
],
"scale": 12000000,
"constraints": {
"rotationEnabled": false
}
}
}
}
extent
The extent represents the visible portion of a map within the view. When configured, this property overrides the center, scale, and zoom properties. This property is ignored if the viewpoint or camera are also configured.
"view": {
"extent": {
"xmin": 600000,
"ymin": 5800000,
"xmax": 1700000,
"ymax": 7600000,
"spatialReference": 3857
}
}
center
Represents the view's center point. To set the center, configure a point object or a longitude/latitude pair (for example [long,lat]). This property is ignored if the camera, or extent properties are also configured.
"view": {
"center": {
"x": 12804.24,
"y": -1894032.09,
"spatialReference": 2027
}
}
"view": {
"center": [-112, 38]
}
scale
This property overrides the zoom
property.
This property is ignored if the camera
or extent
properties are also configured.
The following code sample sets the map scale in the view's center to 1:24,000:
"view": {
"scale" : 24000
}
camera
This property overrides the extent
, center
, scale
, and zoom
properties.
A camera position is composed by using the following properties:
Property | Type | Default | Description |
---|---|---|---|
position | Object or array | The position of the camera defined by a map point. | |
fov | Number | 55 | The field of view of the camera in degrees. |
heading | Number | 0 | The heading of the camera in degrees. |
tilt | Number | 0 | The tilt of the camera in degrees with respect to the surface as projected down from the camera position. |
The following code sample shows how to configure a complete camera view point:
"map-init": {
"Config": {
"view": {
"viewmode": "3D",
"camera": {
"fov": 20,
"heading": 120,
"tilt": 65,
"position": {
"x": 852169,
"y": 6787701,
"z": 208,
"spatialReference": {
"wkid": 3857
}
}
}
}
}
}
The following code sample shows how to define a view with a minimal configuration and alternative position composition [x,y,z]:
"map-init": {
"Config": {
"view": {
"viewmode": "3D",
"camera": {
"position": [-117.646733, 34.288857, 5000]
}
}
}
}
zoom
Represents the level of detail (LOD) at the center of the view.
The following code sample shows how to set the LOD to 18 (large map scale):
"view": {
"zoom": 18
}
constraints
Represents the constraints of the view to restrict its behavior. The properties are compatible to the constraints of Esri's MapView and SceneView. All properties are optional.
Property | Type | Viewmode | Description |
---|---|---|---|
minScale | Number | 2D | A user is not allowed to zoom out further than this scale.. |
maxScale | Number | 2D | A user is not allowed to zoom in further than this scale.. |
lods | Array | 2D | An array of LODs. If not specified, this value is read from the map. |
minZoom | Number | 2D | A user is not allowed to zoom out further than this zoom level. |
maxZoom | Number | 2D | A user is not allowed to zoom in further than this zoom level. |
snapToZoom | Boolean | 2D | If true , the view snaps to the next LOD when zooming in or out. If false , the zoom is continuous. |
geometry | Object | 2D | The area in which the user is allowed to navigate the map. Only Extent and Polygon geometry types are supported. If coordinates not given in wgs84, a spatialReference has to be set accordingly. |
rotationEnabled | Boolean | 2D | Defines, if the user can rotate the map. |
altitude | Object | 3D | Specifies a constraint on the minimum and maximum allowed camera altitude. |
clipDistance | Object | 3D | Specifies the near and far webgl clip distances. |
tilt | Object | 3D | Specifies a constraint on the amount of allowed tilting of the view. |
The following code sample shows the configuration of all properties with sample values:
"view": {
"constraints": {
"minScale": 1000000,
"maxScale": 10000,
"lods": [
{
"level": 3,
"resolution": 19567.87924099992,
"scale": 73957190.948944
},
{
"level": 4,
"resolution": 9783.93962049996,
"scale": 36978595.474472
}
],
"minZoom": 10,
"maxZoom": 14,
"snapToZoom": true,
"geometry": {
"type": "extent",
"xmin": 753914,
"ymin": 6590000,
"xmax": 797273,
"ymax": 6635000,
"spatialReference": 3857
},
"rotationEnabled": true,
"altitude": {
"max": 10000,
"min": 1000
},
"clipDistance": {
"near": 100,
"far": 100,
"mode": "auto"
},
"tilt": {
"max": 100,
"mode": "auto"
}
}
}
navigation
Represents settings to control the view's navigation behavior when a user interacts with the browser. The properties are compatible with Esri's Navigation properties. All properties are optional.
Property | Type | Default | Description |
---|---|---|---|
mouseWheelZoomEnabled | Boolean | true | Whether zooming with mouse wheel is enabled. |
browserTouchPanEnabled | Boolean | true | Whether panning the map with with a single finger touch drag event is enabled. |
"view": {
"navigation": {
"mouseWheelZoomEnabled": true,
"browserTouchPanEnabled": true
}
}
timeExtent
Controls visibility of temporal features when time aware layers are used in a map. Setting the time extent only shows features whose date falls into that extent.
This property is compatible with the timeExtent
property on Esri's MapView
and SceneView.
Specify dates in JavaScript compatible simplified ISO 8601 format:
"view": {
"timeExtent": {
"start": "2019-04-01T00:00Z",
"end": "2019-10-06T00:00Z"
}
}
Supported Layer Types
The following layer types are supported:
Layer Type | Type |
---|---|
TileLayer | AGS_TILED |
MapImageLayer | AGS_DYNAMIC |
FeatureLayer | AGS_FEATURE |
VectorTileLayer | AGS_VECTORTILE |
IntegratedMeshLayer | AGS_INTEGRATEDMESH |
SceneLayer | AGS_SCENE |
StreamLayer | AGS_STREAM |
ElevationLayer | AGS_ELEVATION |
ImageryLayer | AGS_IMAGE |
ImageryTileLayer | AGS_IMAGERYTILE |
GroupLayer | GROUP |
WMSLayer | WMS |
WMTSLayer | WMTS |
WFSLayer | WFS |
OGCFeatureLayer | OGC_FEATURE |
CSVLayer | CSV |
KMLLayer | KML |
OpenStreetMapLayer | OSM |
WebTileLayer | WEBTILE |
BingMapsLayer | BING_MAPS |
GeoJSONLayer | GEOJSON |
GeoRSSLayer | GEORSS |
Layer Properties
When defining layers for basemap
, ground
and layers
, you basically create instances of ArcGIS Maps SDK for JavaScript layers.
For every layer object specify a type
as defined in the Supported Layer Types section.
Inside the layer object definition you can use all properties that are available for the corresponding layer type of the ArcGIS Maps SDK for JavaScript with one limitation:
Typed properties can only be used if they support the autocasting feature of the Esri API.
Use Cases
Use different basemaps together with webmaps
To use multiple basemaps together with webmaps and for example allow to switch them with the basemaptoggler, only declare the property basemaps
.
Optimize app startup performance
By default all layers are pre-loaded and initialized independent of their visibility state. If a configuration contains many layers that are invisible when the app started, the following options reduce the startup time of the app.
Delay the initialization of invisible layers
The following configuration delays the initialization of invisible layers for 2 seconds:
"map-init": {
"Config": {
// NOTE: this property can be omitted, default value is 'default'
"initInvisibleLayerStrategy": "delayed",
// NOTE: this property can be omitted, the default value is 5000 (5sec)
"initInvisibleLayerStrategyDelay": 2000
}
}
NOTE: The toc widget shows protected services to users having insufficient access rights during the configured delay.
Initialize a layer only when it becomes visible
The following configuration initializes a layer only when it becomes visible
, for example by setting it visible in the toc widget.
"map-init": {
"Config": {
"initInvisibleLayerStrategy": "on-visible"
}
}
NOTE: The toc widget shows protected services to users having insufficient access rights until the layer becomes
visible
.
Initialize the basemap prior all operational layers
By default the basemap and the operational layers are initialized together. To improve the startup time of the map, the basemap can be initialized with high priority. Operational layers are initialized after the basemap is ready and displayed.
The following configuration delays the initialization of operational layers for 2 seconds:
"map-init": {
"Config": {
"initBaseMapFirst": true,
// NOTE: this property can be omitted, the default value is 1500 (1.5sec)
"initBaseMapFirstDelay": 2000
}
}
NOTE: This approach can only be used for basemaps configured directly in your app. Do not use this feature together with domain bundles.
Disable the sandbox
attribute on IFrames for WMS layer popups
Some WMS services render complex HTML in popups.
By default, the ArcGIS Maps SDK for JavaScript uses the sandbox
attribute for the surrounding <iframe>
that contains the contents of the popup for security reasons.
This behavior disables many HTML features and may cause the popup to display incorrectly or not at all.
map.apps provides an option that disables the "Sandbox" attribute for certain WMS layers:
"map-init": {
"Config": {
"map": {
"layers": [
{
"id": "<wms-layer-id>",
"url": "<WMS_URL>",
"type": "WMS",
"disableSandbox": true
}
]
},
}
}
NOTE: Use the
disableSandbox
property only for trusted WMS services. The embedded HTML code can execute any JavaScript code, for example.
Provide a custom layer type factory
To provide a custom layer type factory, see the specific documentation of the map-config-api bundle.
Provide a custom map widget
To create a custom map widget and reuse the configuration format of this bundle, reference the configuration interpreter in your manifest.json
file as in the following code sample:
{
"name": "YourComponent",
"references": [
{
"name": "interpreter",
"providing": "map-init.Interpreter"
}
]
}
The following code sample shows how to trigger the interpretation of a JSON configuration in your component:
// the map configuration
let config = {map: ..., view : ...};
// the map-init.Interpreter
let interpreter = this.interpreter;
// trigger interpretation
interpreter.interpret(config).toMapWidget()
//a Promise is returned
.then(({map,mapWidgetModel,mapWidget}) => {
// do something with the created parts
// by defining createWidget:false the mapWidget is not created.
});
// if you are only interested into a MapWidgetModel
interpreter.interpret(config).toMapWidgetModel()
For more details, see the API documentation.