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:

Supported layer types
Layer properties

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 are configured using the basemaps array property:

"map-init": {
    "Config": {
        "basemaps": []
    }
}

You can define multiple basemaps in the basemaps array, whereby only one basemap is active (selected) in the app at a time. Each entry in the array defines the properties of a basemap, for example:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "streets",
                "title": "Streets",
                "description": "Streets basemap",
                "basemap": "streets-vector",
                "selected": true
            }
        ]
    }
}

Each item in the array has got the following properties:

Property	Type	Description
`ìd`	String	The unique identifier of the basemap within the app.
`title`	String	The title of the basemap.
`description`	String	The description of the basemap.
basemap (required)	String \| Object \| Array	You can configure basemaps via well known identifiers such as `streets-vector` or `satellite`. Note: Well known identifiers of 2D basemaps are considered a legacy API by the ArcGIS Maps SDK for JavaScript. references to the basemap styles service (v2) basemap objects that define layers similar to operational layers. array of basemap objects that define layers similar to operational layers. See section Basemap configuration below for details
thumbnailUrl	String	URL's providing thumbnails used by the toc and basemaptoggler bundles to display a small preview of a basemap. See section basemap thumbnails below for details.
`selected` (required)	Boolean	`true` if the basemap is active at the start of the app, otherwise `false`. You have to set exactly one basemap as `selected` for your app.
`viewmode`	`2D` \| `3D`	If set, the `viewmode` property restricts the visiblity of the base map to a specific view mode. See section Basemap visibility below for details.

Basemap configuration

As described in the table above, the basemap property allows you to configure a basemap in different ways.

The following code sample shows how to configure a basemaps using a well known identifier:

"map-init": {
    "Config": {
        "basemaps": [
            {
                // 
                "basemap": "streets-vector",
                "selected": true
            }
        ]
    }
}

NOTE: Well known identifiers of 2D basemaps are considered a legacy API by the ArcGIS Maps SDK for JavaScript.

The following code sample shows how to configure a basemaps as a reference to the basemap styles service (v2). In this case the basemap property is an object with a style property:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "basemap": {
                    "style": {
                        "id": "arcgis/streets"
                    },
                    "selected": true
                }
            }
        ]
    }
}

This variant of defining a basemap is explained in more detail in section Basemap styles.

The following code sample shows how to configure basemaps as layers similar to operational layers. The basemap property is configured as an object with type and url properties. For more information about the configuration options for each layer, see Layer properties.

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "mapserver_tiled1",
                "basemap": {
                    "type": "AGS_TILED",
                    "url": "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer"
                },
                "selected": true
            },
            {
                "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"
                }
            }
        ]
    }
}

If a basemap should have multiple layers it is also 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"
                }],
                "selected": true
            }
        ]
    }
}

Please note that you could also use a layer of type GROUP to combine multiple layers to a single basemap.

Basemap visibility per view mode

You can restrict the visibility of a basemap to a specific view mode (2D or 3D) using the viewmode property of a basemap.

"map-init": {
    "Config": {
        "basemaps": [
            {
                // ...
                // This basemap is only visible in 3D view mode
                "viewmode": "3D" // or "2D"
                // ...
            }
        ]
    }
}

As described above, only one basemap can be active in the app at a time. It is very likely that you want to ensure that a basemap is still active when you change the view mode. If a selected basemap would be restricted to just one of the viewmodes, it would disappear on a viewmode change. To avoid this, combine basemaps with restricted visibility into one basemap, as shown in the following example:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "mybasemap",
                // basemap is active
                "selected": true,
                "basemap": [
                    {
                        // basemap - visible in 2D
                        "id": "streets-2d",
                        "type": "AGS_VECTORTILE",
                        "url": "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer",
                        "viewmode": "2D"
                    },
                    {
                        // basemap combined from two layers - visible in 3D
                        "type": "GROUP",
                        "layers": [
                            {
                                "id": "streets-3d",
                                "type": "AGS_VECTORTILE",
                                "url": "https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer"
                            },
                            {
                                "id": "buildings-3d",
                                "type": "AGS_SCENE",
                                "url": "https://basemaps3d.arcgis.com/arcgis/rest/services/OpenStreetMap3D_Buildings_v1/SceneServer"
                            }
                        ],
                        "viewmode": "3D"
                    }
                ]
            }
        ]
    }
}

Please note that you could also use a basemap defined as a single GROUP layer to achive the same result.

Basemap styles

The preferred way to define a basemap is via the style property. The basemap styles service provides a set of well known basemap styles (referenced by their id).

NOTE: Usage of the basemap styles service requires authentication via an ArcGIS API key or via arcgis online user authentication.

Example:

// ...
"basemaps": [
    {
        "id": "...",
        "basemap": {
            "style": {
                "id": "arcgis/streets",
                "language": "...",
                "places": "...",
                "serviceUrl": "...",
                "worldview": "..."
            }
        }
    }
]

All properties except id are optional. By default, the language is derived from the current application locale. Explicitly defining the language property (e.g. to "de" or "en") will override the default.

For more details, see the documentation of BasemapStyle.

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"
        }
    }
}

NOTE: Well known identifiers of 2D basemaps are considered a legacy API by the ArcGIS Maps SDK for JavaScript. See the section Basemap styles for further configuration options.

Layers

The following code sample shows how to configure different types of layers:

"layers": [
    {
        "id": "mylayer1",
        "type": "AGS_FEATURE",
        "url": "https://www.example.com/arcgis/rest/services/mylayer/FeatureServer/0"
    },
    {
        "id": "mylayer2",
        "type": "AGS_TILED",
        "url": "https://www.example.com/arcgis/rest/services/mycachedlayer/MapServer"
    },
    {
        "id": "mylayer3",
        "type": "AGS_DYNAMIC",
        "url": "https://www.example.com/arcgis/rest/services/mylayer/MapServer",
        "sublayers": [
            {
                "id": 2
            },
            {
                "id": 3
            }
        ]
    },
    {
        "id": "ogcfeaturelayer",
        "title": "OGCFeatureLayer",
        "type": "OGC_FEATURE",
        "url": "https://vtp2.geo-solutions.it/geoserver/ogc/features",
        "copyright": "vtp2.geo-solutions.it",
        "collectionId": "ne:countries50m",
        "objectIdField": "NE_ID",
        "limit": 5000
    },
    {
        "type": "GROUP",
        "layers": [
            {
                "type": "AGS_DYNAMIC",
                "url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer"
            },
            {
                "type": "AGS_DYNAMIC",
                "url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Military/MapServer"
            }
        ]
    },
    {
        "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": [
    {
        "id": "mylayer1",
        "type": "AGS_FEATURE",
        "url": "https://www.example.com/arcgis/rest/services/mylayer/FeatureServer/0",
        "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.city})`"
            }
        ]
    }
]

NOTE: Please note that if you use fieldConfig to configure fields in the Result UI, only the fields that are configured in fieldConfig 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.
environment	Object	The environment settings for a 3D view (such as weather and lighting).
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.
viewingMode	String	The viewing mode of the view. Allowed values are `global` and `local`. Only works in 3D.
clippingArea	Object	The clipping area of the view. Only works in 3D and for local scenes.

"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]
            }
        }
    }
}

`environment`

Specifies various properties of the environment's visualization in the view, such as lighting and weather. These settings can only be used in global scenes.

See SceneView for more details.

Property	Type	Default	Description
atmosphereEnabled	Boolean	true	Specifies whether the atmosphere should be displayed.
background	String, Number[], Object	null	Specifies how the background of the scene.
lighting	object	sun	Settings for defining the lighting of the scene (either sun or virtual lighting)
starsEnabled	Boolean	true	Specifies whether stars should be displayed in the sky.
weather	object	sunny	Indicates the type of weather visualization in the scene.

The following code sample shows how to configure the environment with a white background, no stars, and no atmosphere:

"map-init": {
    "Config": {
        "view": {
            "viewmode": "3D",
            "environment": {
                "background": {
                    "type": "color",
                    "color": [255, 252, 244, 1]
                },
                "starsEnabled": false,
                "atmosphereEnabled": false
            }
        }
    }
}

The following code sample shows how to configure the environment with a sun lighting, displaying the sun position at a specific date and time, and a cloudy weather with 20% cloud cover:

"map-init": {
    "Config": {
        "view": {
            "viewmode": "3D",
            "environment": {
                "lighting": {
                    "type": "sun",
                    "date": "2022-03-15T18:30:00"
                },
                "weather": {
                    "type": "cloudy",
                    "cloudCover": 0.2
                }
            }
        }
    }
}

`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"
    }
}

`viewingMode`

Controls the viewing mode of the view (3D only). The following values are supported:

global: The earth is displayed as a sphere.
local: The earth is displays as a flat surface.

The default value depends on the view's spatial reference system. For more details, see SceneView.viewingMode.

Example:

"view": {
    "viewmode": "3D",
    "viewingMode": "local",
    "camera": {
        "heading": 344.1014584878656,
        "tilt": 51.270353382364384,
        "position": {
            "x": 951824.679252616,
            "y": 5989752.339952401,
            "z": 7801.531608327292,
            "spatialReference": {
                "wkid": 3857
            }
        }
    }
}

`clippingArea`

Defines the area of the map that is visible to the user. This property is only available for 3D views and local scenes. See SceneView.clippingArea for more details.

Example:

"view": {
    "viewmode": "3D",
    "viewingMode": "local",
    "clippingArea": {
        "xmin": 944216.1115766508,
        "xmax": 958488.5364598879,
        "ymin": 5996900.354744372,
        "ymax": 6006350.629505203,
        "spatialReference": {
            "wkid": 3857
        }
    },
    "camera": {
        "heading": 344.1014584878656,
        "tilt": 51.270353382364384,
        "position": {
            "x": 951824.679252616,
            "y": 5989752.339952401,
            "z": 7801.531608327292,
            "spatialReference": {
                "wkid": 3857
            }
        }
    }
}

Supported Layer Types

The following layer types are supported:

Layer Type	Type
BuildingSceneLayer	`AGS_BUILDING`
MapImageLayer	`AGS_DYNAMIC`
ElevationLayer	`AGS_ELEVATION`
FeatureLayer	`AGS_FEATURE`
IntegratedMeshLayer	`AGS_INTEGRATEDMESH`
ImageryLayer	`AGS_IMAGE`
ImageryTileLayer	`AGS_IMAGERYTILE`
PointCloudLayer	`AGS_POINTCLOUD`
SceneLayer	`AGS_SCENE`
StreamLayer	`AGS_STREAM`
TileLayer	`AGS_TILED`
VectorTileLayer	`AGS_VECTORTILE`
VoxelLayer	`AGS_VOXEL`
BingMapsLayer	`BING_MAPS`
CSVLayer	`CSV`
GeoJSONLayer	`GEOJSON`
GeoRSSLayer	`GEORSS`
GroupLayer	`GROUP`
KMLLayer	`KML`
OGCFeatureLayer	`OGC_FEATURE`
OpenStreetMapLayer	`OSM`
WebTileLayer	`WEBTILE`
WFSLayer	`WFS`
WMSLayer	`WMS`
WMTSLayer	`WMTS`

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.

Additionally you can restrict the visibility of a layer to a specific view mode (2D or 3D) using the viewmode property of a layer. For example, the following layer is visible in 2D only:

{
    "id": "ground-values-2d",
    "url": "https://services.arcgis.com/ObdAEOfl1Z5LP2D0/arcgis/rest/services/BRW2016_Muenster/FeatureServer/0",
    "type": "AGS_FEATURE",
    "viewmode": "2D"
}

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.

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:

import { InjectedReference } from "apprt-core/InjectedReference";
import Map from "esri/Map";
import { MapWidget, MapWidgetModel } from "map-widget/api";

interface InterpreterResult {
    map: Map;
    mapWidgetModel: MapWidgetModel;
    mapWidget: MapWidget;
}

class MyComponent {
    private interpreter: InjectedReference<any>;
    async doSomething() {
        // the map configuration
        const config = {} as any; // {map: ..., view : ...};

        // trigger interpretation
        const { map, mapWidgetModel, mapWidget }: InterpreterResult = await this.interpreter.interpret(config).toMapWidget();

        // do something with the created parts
        // by defining createWidget:false the mapWidget is not created.

        // if you are only interested in a MapWidgetModel do:
        await this.interpreter.interpret(config).toMapWidgetModel();
    }
}

For more details, see the API documentation.

map-init

Usage

Configuration reference

Basemaps

Basemap configuration

Basemap visibility per view mode

Basemap styles

Basemap thumbnails

Map

Basemap

Layers

Adding formatting information to a layer

Tables

Ground

View

extent

center

scale

camera

environment

zoom

constraints

navigation

timeExtent

viewingMode

clippingArea

Supported Layer Types

Layer Properties

Use Cases

Use different basemaps together with webmaps

Optimize app startup performance

Delay the initialization of invisible layers

Initialize a layer only when it becomes visible

Initialize the basemap prior all operational layers

Disable the sandbox attribute on IFrames for WMS layer popups

Provide a custom layer type factory

Provide a custom map widget

`extent`

`center`

`scale`

`camera`

`environment`

`zoom`

`constraints`

`navigation`

`timeExtent`

`viewingMode`

`clippingArea`

Disable the `sandbox` attribute on IFrames for WMS layer popups